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     │  ││
│  │  └─────────────┘  └───────────────┘  └───────────────┘  ││
│  │                                                          ││
│  │  ┌─────────────────────────────────────────────────────┐ ││
│  │  │  13 supported agents; seven require explicit selection  │ ││
│  │  └─────────────────────────────────────────────────────┘ ││
│  └──────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────┘

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 thirteen AI coding agent integrations
• Multi-server support
• Heartbeat-based health monitoring
• Git worktree isolation per task

MiMo Code (mimo, v0.1.14+), Qwen Code (qwen, v0.24.1+), CodeBuddy (codebuddy, v2.156.0+), Qoder CLI (qoder, v1.1.59+), TraeCode CLI (trae), and ZCode (zcode) are selected explicitly by the user or project policy and are not considered by automatic routing or the generated default fallback chain. CodeBuddy and Qoder completed their local AgentHost start/resume acceptance gates. TraeCode CLI and ZCode remain gated pending their real-account and real-protocol live acceptance respectively.

Agent Gateway

DeepSeek Harness (deepseek, exactly 0.2.0-rc.2) adds a seventh explicit integration for Desktop and personal Runtimes. It uses a managed profile with read-only external credentials, not a copied personal profile. Ready requires the matching build/Node/platform acceptance; native Windows, shared pools and automatic routing remain disabled. Native resume requires the same workspace and runtime composition.

• Unified interface to multiple AI agents
• Protocol support: Print mode, CLI, App-Server
• Intelligent agent routing with fallback chains

Quality Gates

• 7-dimension weighted scoring: test pass rate, coverage, static checks, security, diff risk, AI review, and requirement coverage
• 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