Amicable

AI-powered web app builder.
Describe what you want, watch it come to life.

---

Amicable lets you build web applications through conversation. Type a prompt in the editor, and an AI agent writes the code in an isolated sandbox while you watch a live preview update in real time.

How It Works

Browser (Editor)
    | WebSocket
Agent (FastAPI + DeepAgents)
    | HTTP
Sandbox Pod (Kubernetes)
    |-- Runtime API :8888  (file I/O, shell)
    '-- Vite Dev Server :3000  (live preview)

1. You open the editor and describe what you want to build
2. The agent receives your prompt over WebSocket
3. A per-session Kubernetes sandbox is provisioned automatically
4. The agent reads, writes, and executes commands in the sandbox
5. After edits, deterministic QA (lint, typecheck, build) validates the result
6. If QA fails, the agent self-heals and retries
7. You see the result in a live preview iframe

Features

• Conversational UI -- chat with the agent to iteratively build your app
• Live preview -- see changes instantly via an embedded Vite dev server
• Design iteration -- select a visual reference and the agent iterates toward it, with multi-page context to preserve cross-page consistency
• Isolated sandboxes -- each session gets its own Kubernetes pod
• Per-app database -- optional Postgres schema per app, exposed via Hasura
• Deterministic QA -- automated lint, typecheck, and build checks after every edit
• Self-healing -- the agent automatically fixes QA failures
• Human-in-the-loop (HITL) -- approval gates for destructive operations
• GitLab persistence -- optional automatic repo creation and snapshot commits
• Google OAuth -- optional authentication for multi-user deployments
• Observability -- OpenTelemetry tracing, Prometheus metrics, Grafana Faro browser telemetry

Quick Start

git clone https://github.com/mayflower/amicable
cd amicable
pip install -r requirements.txt

cd frontend
npm install
npm run dev

The editor connects to a deployed agent via WebSocket. Set VITE_AGENT_WS_URL in frontend/.env to point at your agent. For full setup instructions, see Development.

Documentation

This project follows the Diataxis documentation framework. Each section below serves a distinct purpose.

Tutorials -- learning-oriented

Start here to understand the product and get a working setup.

Document	What you will learn
Usage	End-to-end user flow: prompts, previews, design iteration, HITL
Development	Local setup, codebase layout, developer workflow
Local kind Setup	Running Amicable on a local Kubernetes cluster

How-to guides -- task-oriented

Step-by-step instructions for specific goals.

Document	What it helps you do
Deployment	Deploy to Kubernetes with Helm
Kubernetes Installation	Set up the cluster, CRDs, and ingress
Sandbox Configuration	Configure sandbox templates and runtimes
Debugging Runbook	Diagnose and resolve common failures

Reference -- information-oriented

Look up specific configuration, protocols, and API surfaces.

Document	What it covers
Configuration	All environment variables and runtime toggles
Architecture	Components, request flow, WebSocket protocol, design iteration loop
DEVELOPMENT.md	Deep-dive developer reference: WS protocol, auth, QA, HITL, Hasura, GitLab sync

Explanation -- understanding-oriented

Background, design rationale, and operational context.

Document	What it explains
Operations	Health checks, incident response, safety and change control
Data-Cluster Notes	Mayflower-specific deployment context and conventions
Testing	Test strategy, QA loop behavior, pre-merge checklist

Development

# Python
pytest                           # run tests
python3 -m compileall -q src     # syntax check
ruff check src/                  # lint
ruff format src/                 # format

# Frontend
cd frontend
npm run build                    # production build
npm run lint                     # eslint

License

License has not been decided on yet. All rights reserved until a license is chosen.