Architecture Overview
Forgexa uses a modular, event-driven architecture with clear separation between the control plane (API Server) and execution plane (Runtime Daemons).
Visual System Views
Home Hero
Showcase View
Detailed Technical View
Asset Sizes
- Home hero: 980 × 720
- Showcase view: 1600 × 900
- Detailed technical view: 1600 × 1200
System Architecture
┌──────────────────────────────────────────────────────────────┐
│ Control Plane │
│ │
│ ┌─────────┐ ┌──────────────────────────────────────────┐ │
│ │ Web UI │──▶│ API Server (FastAPI) │ │
│ │ (React) │ │ ┌────────────┐ ┌─────────────────────┐ │ │
│ └─────────┘ │ │ Orchestr. │ │ Workflow Policy Mgr │ │ │
│ │ └────────────┘ └─────────────────────┘ │ │
│ ┌─────────┐ │ ┌────────────┐ ┌─────────────────────┐ │ │
│ │ CLI │──▶│ │ Gate Score │ │ Plan Generator │ │ │
│ └─────────┘ │ └────────────┘ └─────────────────────┘ │ │
│ └──────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ┌─────▼───┐ ┌────▼────┐ ┌────▼────┐ │
│ │Postgres │ │ Redis │ │ MinIO │ │
│ │pgvector │ │ Streams │ │ (S3) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└──────────────────────────────────────────────────────────────┘
Polling / HTTP
┌──────────────────────────────────────────────────────────────┐
│ Execution Plane │
│ │
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Runtime Daemon ││
│ │ ┌─────────────┐ ┌───────────────┐ ┌───────────────┐ ││
│ │ │ Agent │ │ Workspace │ │ Process │ ││
│ │ │ Discovery │ │ Manager │ │ Manager │ ││
│ │ └─────────────┘ └───────────────┘ └───────────────┘ ││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────┐ ││
│ │ │ AI Agents: Claude Code │ Codex │ OpenCode │ Gemini │ ││
│ │ └─────────────────────────────────────────────────────┘ ││
│ └──────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────┘Core Components
API Server
- FastAPI backend with async SQLAlchemy
- RESTful API with JWT + Personal Access Token (PAT) authentication
- Multi-tenant: Organization → Workspace → Project hierarchy
- RBAC at two levels:
- Organization: Owner, Admin, Member
- Workspace: Owner, Admin, Developer, Viewer + Custom Roles
Orchestrator
- Polling-based task scheduler
- Dependency-aware node dispatch
- Budget enforcement (project + workspace + organization)
- Test-fix loop (up to 5 iterations)
- Rollback handling
Runtime Daemon
- Runs on developer machines (host-native)
- Auto-discovers installed AI agents
- Multi-server support
- Heartbeat-based health monitoring
- Git worktree isolation per task
Agent Gateway
- Unified interface to multiple AI agents
- Protocol support: Print mode, CLI, App-Server
- Intelligent agent routing with fallback chains
Quality Gates
- 6-dimension weighted scoring
- Configurable thresholds via WORKFLOW.md
- Human review workflow
Data Model
Organization (1) ──▶ (N) Workspace
Organization (1) ──▶ (N) OrganizationMember
Organization (1) ──▶ (N) OrgInvitation
Organization (1) ──▶ (N) IntegrationConfig (org-level)
Workspace (1) ──▶ (N) Project
Workspace (1) ──▶ (N) WorkspaceMember
Workspace (1) ──▶ (N) CustomRole
Project (1) ──▶ (N) Requirement
Requirement (1) ──▶ (N) RequirementVersion
Requirement (1) ──▶ (1) Plan
Plan (1) ──▶ (1) ExecutionGraph
ExecutionGraph (1) ──▶ (N) ExecutionNode
ExecutionNode (1) ──▶ (1) WorkItem
WorkItem ──▶ Board (5-column Kanban)
User (1) ──▶ (N) PersonalAccessToken
AuditLog ──▶ Organization / Workspace / Project (scoped)Technology Stack
| Layer | Technology |
|---|---|
| Frontend | React 19 + TypeScript + Ant Design 5 + Vite |
| Backend | Python 3.12 + FastAPI + SQLAlchemy 2.0 async |
| Database | PostgreSQL 16 + pgvector |
| Cache/Events | Redis 7 Streams |
| Storage | MinIO (S3-compatible) |
| Containerization | Docker + Docker Compose |