AI Project CTO

Multi-agent workflow engine that transforms a software idea into structured project artifacts.

Idea → Business Analysis → PRD → Architecture → Tasks → Markdown Workspace

Run 4 AI agents (Business Analyst, Product Manager, Architect, Engineering Planner) against your idea — preview their output, edit it, approve it, and export a complete project workspace.

Quick Start

# 1. Install deps (first time)
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # add API keys (DeepSeek, Kimi, MiniMax)
cd apps/web && npm install && cd ..

# 2. Run API (port 5101)
make api

# 3. Frontend dev server (port 5100, proxies /api → :5101)
make web

Open http://localhost:5100

Or use the Makefile:

make install       # full install (venv + pip + npm)
make api           # start backend (port 5101)
make web           # start frontend (port 5100)
make reset         # wipe DB + projects (see scripts/reset.sh)

Docker & Render (production)

The app is built as a single-process Docker image — one FastAPI server serves both the API and the built Next.js static SPA, exactly like interview-lab. No separate nginx/frontend container.

# Build the image locally
docker build -t idea2spec .

# Run it (local SQLite is fine for a quick try; set Turso vars for durability)
docker run -p 5101:5101 -e APP_ENV=production idea2spec
# → API + SPA at http://localhost:5101

Deploy to Render (via render.yaml, same flow as interview-lab):

1. Push this repo to GitHub.
2. Render → New + → Blueprint → select the repo.
3. Set the secret env vars in the dashboard: DEEPSEEK_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY, and the Turso pair TURSO_DATABASE_URL + TURSO_AUTH_TOKEN.
4. Render builds the Dockerfile and serves it on its injected $PORT.

The free Render plan has an ephemeral disk, so production storage must be Turso (hosted SQLite) — see Storage below.

Storage

Environment	Backend
Local dev (APP_ENV unset)	Local SQLite file — data/projects.db (aiosqlite, WAL mode)
Production (APP_ENV=production + Turso URL)	Turso (hosted libSQL / SQLite) — durable across redeploys

Turso is selected automatically when APP_ENV=production and a libsql:// URL is configured (either TURSO_DATABASE_URL + TURSO_AUTH_TOKEN, or DATABASE_URL + DATABASE_AUTH_TOKEN). The same SQL and schema are used in both — scripts/init_db.sql runs on startup. No Postgres, no Supabase.

Set it up once:

turso auth login
turso db create idea2spec
turso db show idea2spec            # URL (libsql://<db>-<org>.turso.io)
turso db tokens create idea2spec   # auth token

CLI Pipeline

Run all agents from the terminal with a single command:

PYTHONPATH=. python scripts/cli.py "I want to build AI Resume SaaS" --export

Run specific agents:

PYTHONPATH=. python scripts/cli.py "My idea" --agents business,product

The CLI also supports make cli IDEA="...".

Preview-&-Approve Workflow

The UI follows a human-in-the-loop flow:

1. Create Project — enter your idea, gets an LLM-generated title automatically
2. Run Agents — click individual agent buttons or Run All — results appear in a preview pane, NOT saved to DB
3. Live Status Tracking — each agent row shows real-time status badges:
   • ⏳ Pending — waiting to run
   • 🔄 Running — with live elapsed timer (e.g. 12s, 1m5s)
   • ✅ Done — completed successfully
   • ❌ Failed — error occurred
   • Each row also displays which LLM provider powers that agent (Kimi/DeepSeek/MiniMax + model name)
4. Review & Edit — browse structured views (Business → PRD → Architecture → Tasks) or switch to Raw JSON to edit directly
5. Approve & Save — explicit click persists all artifacts to the database
6. Export — download as Markdown workspace, HTML report, or Mermaid architecture diagram

Note: In dev, all requests — including Run All's sequential per-agent calls (runAllAgents() loops POST /api/agent/{name}/{id}) — route through the same-origin Next.js rewrite proxy (/api/* → backend). In the Docker image the built SPA calls /api/* directly and FastAPI serves the same routes under both / and /api (see services/api/main.py).

A Saved Projects panel lists all persisted projects — load them back for re-review or re-export.

Stack Overview

Layer	Technology
Backend	FastAPI + Uvicorn (port 5101)
Agent Runtime	LangGraph (CLI pipeline) / direct calls (UI)
Frontend	Next.js 15 (port 5100; static export in production)
Storage	SQLite via aiosqlite locally; Turso (hosted SQLite) in production
LLM Router	Async httpx → OpenAI-compatible APIs (DeepSeek / Kimi / MiniMax)
Export	Markdown workspace + HTML report + Mermaid diagram

Full architecture: docs/tech-stack.md

API Endpoints

Method	Path	Description
POST	/project/create	Create project from idea
GET	/project/{id}	Get project state
GET	/projects	List all saved projects (newest first)
DELETE	/project/{id}	Delete a project
POST	/agent/{name}/{id}	Run a single agent (business/product/architect/planner)
POST	/project/{id}/save-artifacts	Approve & persist agent artifacts
POST	/project/{id}/export	Export workspace (markdown / html / mermaid)
GET	/project/{id}/export/zip?format=…	Download exported file
GET	/project/{id}/run-all	Legacy SSE stream (the UI runs all 4 agents sequentially via POST /agent/{name}/{id})
GET	/health	Health check

Every endpoint is also served under /api/… (the production SPA calls that prefix). The dev rewrite proxy strips the prefix.

LLM Routing

Agent	Provider	Model	Temperature
Business Analyst	Kimi	kimi-k2.5	1.0
Product Manager	DeepSeek	deepseek-v4-pro	0.3
Architect	DeepSeek	deepseek-v4-pro	0.3
Engineering Planner	MiniMax	MiniMax-M2.5	0.3
Fallback (missing key)	DeepSeek	deepseek-v4-pro	0.3

If a provider's API key is missing, the router falls back to DeepSeek. JSON parse failures trigger one automatic retry with a fix prompt.

Project titles are also LLM-generated (via the fallback router) — your idea "I want to build a habit tracker" becomes "Daily Habit Tracker" automatically.

Environment Variables

Variable	Required	Default	Description
DEEPSEEK_API_KEY	Yes	—	DeepSeek API key
KIMI_API_KEY	Yes	—	Kimi/Moonshot API key
MINIMAX_API_KEY	Yes	—	MiniMax API key
APP_ENV	No	development	production enables Turso (with a libsql URL set)
TURSO_DATABASE_URL	No	—	Turso URL (libsql://…); alias DATABASE_URL
TURSO_AUTH_TOKEN	No	—	Turso auth token; alias DATABASE_AUTH_TOKEN
CORS_ORIGINS	No	http://localhost:5100,http://127.0.0.1:5100	Allowed CORS origins
DATABASE_PATH	No	data/projects.db	Local SQLite database path
BACKEND_URL	No	http://127.0.0.1:5101	FastAPI backend URL for Next.js dev rewrites

Project Structure

apps/web/                 Next.js 15 control panel
  components/             React components (ControlPanel, BusinessView, PRDView, …)
  lib/api.ts              TypeScript API client

services/
  api/                    FastAPI backend
    main.py               Routes (bare + /api alias), CORS, static SPA serving
    store.py              Project CRUD (SQLite locally, Turso in production)
    db.py                 Connection manager — picks aiosqlite or Turso
    turso.py              Async Turso (hrana-over-HTTP) client
    export.py             Markdown/HTML/Mermaid workspace export
  agent_runtime/          LangGraph agents + workflow
  llm_router/             Multi-provider LLM client (httpx + JSON extraction)

packages/
  schemas/project.py      Pydantic models — single source of truth
  prompts/agents.py       Agent system prompts

scripts/cli.py            Terminal entrypoint for full pipeline
scripts/init_db.sql       Schema (runs on startup)

data/                     Local SQLite database (gitignored)
projects/                 Exported workspaces (gitignored)
tests/                    Pytest suite (12 tests)

Dockerfile                Single-process image (Node build + FastAPI runtime)
render.yaml               Render Blueprint
requirements.txt          Runtime deps for the Docker image

Clean Reset

To wipe all data and start fresh:

bash scripts/reset.sh        # with confirmation prompt
bash scripts/reset.sh -f     # force reset, no prompt
make reset                   # same as -f

This deletes data/projects.db and the projects/ directory, then restarts the backend to auto-create a fresh database.

Testing

make test                 # PYTHONPATH=. venv/bin/pytest tests/ -q
PYTHONPATH=. venv/bin/pytest tests/ -v     # verbose

Backend tests use pytest-asyncio with an InMemoryStore — no database dependency.

Related Docs

Document	Description
Full Tech Stack	Architecture diagrams, workflows, sequence flows
Next Steps & Roadmap	Product roadmap, visualization pipeline
Preview-&-Approve Flow	Human-in-the-loop design for agent output review
Agent Guide	Detailed commands, agent config, quirks for developers
Design Spec	Original MVP design specification