DevForge AI — Multi-Agent AI Software Engineering Platform

DevForge AI is a full-stack platform where you describe a software requirement in plain English and a coordinated pipeline of AI agents analyzes it, designs the architecture, generates code, reviews it, fixes issues, writes tests, runs them in an isolated sandbox, and hands you a final project report.

This repo is a working v1 scaffold, not a finished commercial product. Read "What's real vs. simplified" below before you rely on it for anything serious.

---

Quick start (Docker — recommended)

Prerequisites: Docker Desktop (or Docker Engine + Compose) installed and running.

# 1. Clone / unzip, then from the project root:
cp .env.example .env

# 2. Add your Anthropic API key to .env (optional — the app runs without one,
#    but agents will return empty output using the Mock LLM provider)
#    LLM_API_KEY=sk-ant-...

# 3. Build and start everything (Postgres, Redis, backend, frontend)
docker compose up --build

Then open:

• Frontend: http://localhost:5173
• Backend API docs (Swagger): http://localhost:8000/docs
• Backend health check: http://localhost:8000/api/health

The backend auto-creates its database tables on startup (via SQLAlchemy create_all) for local-dev convenience. For anything beyond local dev, switch to Alembic migrations (a placeholder alembic/ layout is referenced in the spec but not wired up yet — see below).

To stop: Ctrl+C, then docker compose down (add -v to also wipe the Postgres volume).

---

Running it in VS Code without Docker (backend + frontend separately)

Backend

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Point at a local Postgres, or use SQLite for a zero-config demo:
export DATABASE_URL=sqlite:///./devforge.db
export JWT_SECRET=dev-secret
export LLM_API_KEY=sk-ant-...     # optional

uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173. Set VITE_API_BASE_URL in a frontend/.env file if your backend isn't on http://localhost:8000.

Recommended VS Code extensions

• Python (ms-python.python)
• Pylance
• ESLint
• Tailwind CSS IntelliSense
• Docker

---

Using the app

1. Register an account, then Create project with a plain-English requirement (e.g. "A task management app where teams can create boards, assign tasks, and get email reminders for due dates").
2. Click Run requirement analysis. Watch the live agent progress panel.
3. Once analysis completes, approve it to move to architecture design.
4. Approve the architecture to kick off the full pipeline: database design → API design → planning → code generation → code review → automated fixing (up to 3 iterations) → test generation → sandboxed test execution → final report.
5. Browse generated files in the Code tab (Monaco editor, versioned saves), inspect issues in Review, see pass/fail results in Testing, and read the Report tab for the final Markdown summary.

---

Architecture

Frontend (React/Vite/TS/Tailwind)
        │  REST + WebSocket
        ▼
FastAPI backend
  API layer        (app/api)
  Service layer     (app/services)
  Agent orchestrator (app/services/orchestrator.py)
  LLM provider layer (app/services/llm_provider.py)
  Repository layer  (SQLAlchemy models, app/models)
        │
        ▼
PostgreSQL

Agents share one JSON state blob per project (Project.state), mirroring the ProjectState design in the spec. Each agent reads the slice of state it needs and writes only its own output; the orchestrator owns all state mutation and status transitions.

Generated code is never executed on the backend process or host. The sandbox_execution stage shells out to docker run with --network none, CPU/memory limits, a --pids-limit, and a hard wall-clock timeout, then destroys the container unconditionally.

---

What's real vs. simplified

Real and working:

• JWT auth, Postgres persistence, full agent pipeline with genuine LLM calls (Anthropic by default) and Pydantic-validated structured outputs
• Human-in-the-loop approval gates before architecture and before code generation
• Incremental (not single-shot) code generation, one file per task
• Iterative code-fixing loop (max 3 iterations) that versions files instead of overwriting them
• Docker-isolated sandboxed test execution with resource/time limits
• Real-time agent progress over WebSockets
• Monaco-based code explorer with file save-as-new-version

Simplified or not yet implemented — treat these as the natural next milestones:

• Background jobs: pipeline stages run as in-process asyncio tasks, not Celery workers. Fine for demos/small teams; add Celery + Redis-backed queues before scaling concurrent users.
• Migrations: uses Base.metadata.create_all() instead of Alembic migrations. Swap in real Alembic revisions before production use.
• Diff viewer / version compare UI: file versions are stored (see files table), but the frontend only shows the latest version — no side-by-side diff yet.
• Admin dashboard / RBAC enforcement: the ADMIN role exists in the data model and a require_admin dependency is provided, but no admin-only endpoints or UI are wired up yet.
• Cancel/stop a running workflow: not implemented; a running pipeline runs to completion or failure.
• PDF report export: the final report is Markdown only; add a PDF export step if you need one.
• Frontend/mobile test generation: the Testing Agent is tuned toward pytest for backend code; frontend test generation is not specialized yet.

---

Project layout

devforge-ai/
├── backend/
│   ├── app/
│   │   ├── api/            # FastAPI routers (auth, projects, workflow, websocket)
│   │   ├── core/           # config, JWT/password security
│   │   ├── db/             # SQLAlchemy session/engine
│   │   ├── models/         # ORM models
│   │   ├── schemas/        # Pydantic request/response + structured LLM schemas
│   │   ├── services/       # LLM provider abstraction + orchestrator
│   │   ├── agents/         # the 10 specialized agents
│   │   ├── sandbox/        # Docker-based test execution
│   │   ├── prompts/        # versioned agent prompt text files
│   │   └── main.py
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── pages/          # Landing, Login, Register, Dashboard, CreateProject, ProjectWorkspace
│   │   ├── components/     # AgentProgress, CodeExplorer, ReviewDashboard, TestingDashboard, layout
│   │   ├── services/       # axios API client
│   │   └── hooks/          # auth store, WebSocket hook
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

---

API reference

Full interactive docs are auto-generated at /docs (Swagger) and /redoc once the backend is running. Key endpoints:

POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/refresh
GET    /api/auth/me

GET    /api/projects
POST   /api/projects
GET    /api/projects/{id}
DELETE /api/projects/{id}

POST   /api/projects/{id}/analyze
POST   /api/projects/{id}/approve
POST   /api/projects/{id}/generate
POST   /api/projects/{id}/review
POST   /api/projects/{id}/fix
POST   /api/projects/{id}/test
POST   /api/projects/{id}/execute

GET    /api/projects/{id}/agent-runs
GET    /api/projects/{id}/files
GET    /api/projects/{id}/files/{file_id}
PUT    /api/projects/{id}/files/{file_id}
GET    /api/projects/{id}/reviews
GET    /api/projects/{id}/tests
GET    /api/projects/{id}/reports

WS     /ws/projects/{id}

---

Resume-ready project description

DevForge AI — Multi-Agent AI Software Engineering Platform

• Developed a full-stack AI software engineering platform using Python, FastAPI, React, PostgreSQL, and LLM-based multi-agent workflows.
• Designed specialized AI agents for requirement analysis, system architecture, code generation, code review, automated testing, and bug fixing, coordinated through a shared workflow state.
• Implemented a secure sandboxed code execution environment with Docker-based isolation, resource limits, timeout controls, and automated test execution.
• Built real-time agent workflow tracking over WebSockets, versioned code storage, AI-generated architecture/ER diagrams, security-focused code review, and automated Markdown project reports.

---

License

MIT — see LICENSE.