Skip to content

feat(agent): Web UI Agent for natural language app deployment#1719

Open
ChaiWithJai wants to merge 5 commits intomasterfrom
feat/web-ui-agent
Open

feat(agent): Web UI Agent for natural language app deployment#1719
ChaiWithJai wants to merge 5 commits intomasterfrom
feat/web-ui-agent

Conversation

@ChaiWithJai
Copy link
Copy Markdown
Collaborator

@ChaiWithJai ChaiWithJai commented Dec 9, 2025 •
edited
Loading

Summary

Implements a LangGraph-based AI agent that enables users to describe their app idea in natural language and have it automatically deployed as a working Violet Rails application.

Key Features:

  • 🧠 Diagnose user requirements from natural language descriptions
  • 📐 Generate app specifications (subdomains, namespaces, pages)
  • 🔧 Create resources via Violet Rails API
  • 🚀 Deploy to local/GitHub/Heroku targets

Architecture: Deep Agent principles (DIAGNOSE → MULTI-EXPERT → ARTIFACT-FIRST → DOMAIN-NATIVE)

Tools (6):

Tool Purpose
diagnose_requirements Parse app descriptions, identify entities/relationships
generate_specification Create YAML specs for app structure
create_subdomain Provision tenant subdomains
create_namespace Create API namespaces with JSONB properties
create_page Generate CMS pages with Liquid templates
trigger_deployment Handle deployment orchestration

Subagents (5):

Subagent Role
Architect App structure & data modeling (DHH-style Rails)
CMS Designer Page layouts & Liquid templates
Content Researcher Extract styles from reference sites
Deployer GitHub/deployment orchestration
Security Input validation & security review

Walking Through The Workflow

The Violet App Agent follows a Plan → Act → Verify workflow pattern. Here's how to try it yourself:

Step 1: Start the Services

# 1. Start Docker containers (if not running)
docker-compose up -d solutions_db solutions_redis

# 2. Start Rails server
cd /path/to/violet_rails
bin/rails server -p 5250 -b 0.0.0.0

# 3. Start LangGraph agent
cd violet-app-agent
source apps/agent/.venv/bin/activate
export RAILS_ROOT=/path/to/violet_rails
export DATABASE_HOST=localhost DATABASE_PORT=6000
export DATABASE_USERNAME=postgres DATABASE_PASSWORD=password
export DATABASE_NAME=r_solutions_development
export REDIS_URL=redis://localhost:6380/0
langgraph dev --port 8123 --no-browser

Step 2: Open the Streaming UI

Open violet-app-agent/apps/agent/chat_ui_streaming.html in your browser.

Screenshot: Welcome Screen

Welcome Screen

The UI shows:

  • What I can build: Data models, APIs, web pages, forms, subdomains
  • What you'll add: Your actual content and personal style

Step 3: Describe Your App Idea

Type a natural language description of the app you want to build.

Screenshot: User Input

User Input

Example: "Build a task manager app with projects and tasks that have due dates"

Step 4: Plan Phase - Requirements Gathering

The agent asks clarifying questions to understand your requirements.

Screenshot: Clarifying Questions

Clarifying Questions

Step 5: Plan Preview - Specification Review

After gathering requirements, the agent generates a specification with:

  • Data models (entities and properties)
  • Pages to be created
  • Relationships between entities

Screenshot: Plan Preview

Plan Preview

Review and approve the spec, or ask for adjustments.

Step 6: Act Phase - Building

Once approved, the agent executes the plan:

  • Creates subdomain
  • Creates API namespaces
  • Creates CMS pages

Screenshot: Build Progress

Build Progress

Tool calls show real-time progress with checkmarks for completed steps.

Step 7: Verify Phase - Completion Summary

After building, you'll see a summary with links to your app.

Screenshot: Final Result

Final Result

Recent Changes (INC-20251208-003 Remediation)

Database persistence fixes:

  • Added DISABLE_SPRING=1 to prevent fork() issues on macOS
  • Two-step create + verify pattern for all database operations
  • DB health check at agent startup
  • Integration tests for verification

Test Plan

  • E2E tests for JTBD flow (11+ tests passing)
  • test_diagnose_requirements_parses_pet_adoption_app
  • test_generate_specification_creates_valid_yaml
  • test_create_subdomain_validates_name
  • test_create_namespace_validates_properties
  • test_create_page_requires_namespace_for_typed_pages
  • test_trigger_deployment_local_needs_no_repo
  • test_trigger_deployment_heroku_requires_repo
  • test_full_jtbd_flow_pet_adoption (integration)
  • test_blog_app_spec
  • test_inventory_app_spec
  • Subdomain validation edge cases
  • Database verification tests (INC-20251208-003)

Run tests: cd violet-app-agent/apps/agent && pytest tests/ -v

Related

Closes #1715, #1716, #1717, #1720, #1721, #1722

🤖 Generated with Claude Code

Jai Bhagat and others added 2 commits December 8, 2025 20:11
@claude
feat(agent): add Web UI Agent for natural language app deployment
ccee53d 
Implements a LangGraph-based AI agent that allows users to describe their app
idea in natural language and generates working Violet Rails apps with GitHub
deployment.

Architecture follows Deep Agent principles (DIAGNOSE, MULTI-EXPERT,
ARTIFACT-FIRST, DOMAIN-NATIVE):

Tools:
- diagnose_requirements: Analyze app descriptions and identify entities
- generate_specification: Create YAML specs for app structure
- create_subdomain: Provision tenant subdomains via API
- create_namespace: Create API namespaces with properties
- create_page: Generate CMS pages with Liquid templates
- trigger_deployment: Handle local/GitHub/Heroku deployments

Subagents:
- Architect: App structure and data modeling (DHH-style Rails)
- CMS Designer: Page layout and Liquid template design
- Deployer: GitHub and deployment orchestration
- Security: Input validation and security review

Includes E2E tests for core JTBD: "describe app idea → deployed app"
11 tests covering diagnostic, specification, validation, and deployment flows.

Closes #1715

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(agent): use Rails runner pattern for tool implementations
a022f10 
Refactors the Violet App Agent tools to use direct Rails model access
via `bin/rails runner` instead of non-existent API endpoints. This is
the DHH-approved pattern for direct model manipulation.

Key changes:
- agent.py: Fixed deepagents 0.3.0 API compatibility by using
  ChatAnthropic model object instead of string
- Added rails_runner.py: Core implementation for subprocess-based
  Rails model access
- Refactored subdomain.py, namespace.py, cms.py: Replaced httpx API
  calls with rails_runner functions
- Added langgraph.json: Local development configuration
- Added docs/README.md: Required for package installation

Tested E2E via Playwright:
- create_subdomain: pr1719-test subdomain created
- create_namespace: Task namespace with 4 properties
- create_page: Task Manager Home page at /home

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ChaiWithJai ChaiWithJai mentioned this pull request Dec 9, 2025
Open
4 tasks
Jai Bhagat and others added 3 commits December 8, 2025 22:24
@claude
feat(agent): add Plan/Act/Verify UX enhancements and E2E test suite
1c43f54 
Implements RFC-001 Plan Mode UX for the Violet App Agent with streaming UI
that provides real-time feedback during app building.

UX Enhancements:
- chat_ui_streaming.html: Enhanced streaming UI with Plan/Act/Verify phases
- detectBuildPhase(): Detects plan-preview vs verify-complete phases
- renderCapabilityCard(): Shows "What I Can Build" vs "What You'll Add"
- renderPlanPreview(): Displays YAML spec with Approve/Adjust buttons
- renderBuildProgress(): Shows numbered progress steps during build

New Subagent:
- content_researcher.py: Bridges infrastructure and content creation
  - research_reference_site: Extract style patterns from reference sites
  - extract_writing_style: Create style guides from author references
  - generate_content_brief: Produce actionable content briefs

E2E Test Suite:
- 22 semantically-labeled screenshots covering full UX flow
- trace_summary.md: Documents tool execution sequence (18 tool results)
- Verified Plan/Act/Verify pattern with real blog creation

RFC Documentation:
- RFC-001-plan-mode-ux.md: Complete specification for Plan Mode UX
- Defines capability separation (CAN_BUILD vs YOULL_ADD)
- Outlines streaming progress events and upsell path

Related: #1720, #1721, #1722, #1723

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(agent): database verification + Act/Verify UI enhancements
591d1ad 
Incident Response (INC-20251208-003):
- Add DISABLE_SPRING=1 to prevent macOS fork() issues
- Add OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES for subprocess safety
- Implement two-step create + verify pattern for all Rails operations
- Add check_db_health() for startup connectivity validation
- Add startup health check to agent.py module load

Act Phase UI Enhancements:
- Implement build tracker with [1/N] numbered step progress
- Dark themed build-tracker div with animated pulse icons
- Tool name mapping for human-readable step descriptions
- Real-time progress updates during build phase

Verify Phase UI Enhancements:
- Success summary with green gradient design
- List of verified resources with checkmarks
- Clickable App URL and Admin Panel links
- "What You'll Add Next" guidance section

Plan Approval UI:
- Styled three-button approval group
- "Approve & Build" (green), "Modify" (orange), "Start Over" (grey)
- State machine transitions (idle → plan → act → verify)

Testing:
- TestDatabaseVerification class with 5 integration tests
- Verify DISABLE_SPRING in environment
- Confirm verified:true in all create responses

Related: INC-20251208-003

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
docs(agent): add E2E workflow screenshots for PR walkthrough
624f6bf 
Screenshots documenting the Plan/Act/Verify workflow:
- 01-welcome-screen.png: Initial UI with capability cards
- 02-user-input.png: Natural language app description
- 03-building-started.png: Agent clarifying questions
- 04-plan-preview-spec.png: Generated specification review
- 05-act-phase-building.png: Tool execution starting
- 06-act-phase-progress.png: Build progress with checkmarks
- 07-act-phase-pages.png: Page creation in progress

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ChaiWithJai ChaiWithJai mentioned this pull request Dec 9, 2025
Draft
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

epic: Web UI Agent for Natural Language App Deployment via GitHub

1 participant

@ChaiWithJai