Introduction

Forgexa is an autonomous software development platform that orchestrates AI coding agents to convert requirements into working, tested, and reviewed code.

What It Does

1. Requirement Analysis — AI analyzes natural-language requirements and generates structured specifications with acceptance criteria
2. Plan Generation — AI creates execution plans with work items, breaking requirements into actionable tasks
3. Automated Execution — AI agents (Claude Code, Codex, etc.) implement code, guided by your project's WORKFLOW.md
4. Quality Assurance — Automated test-fix loops, lint checks, and 7-dimension quality gate scoring
5. Human Review — Quality gates require human approval before merging, keeping humans in the loop

Key Concepts

Organization

An organization is the top-level multi-tenant container. It manages members, enforces budget limits, and defines shared configurations (SMTP, integrations, workflow templates, runtimes) inherited by all workspaces within it. Each organization has three roles: Owner, Admin, and Member.

Workspace

A workspace belongs to an organization and is the operational container for projects. It holds projects, manages its own budget, team membership with RBAC roles (Owner, Admin, Developer, Viewer), and can define custom roles with fine-grained permissions.

Project

Each project has a Git repository, tech stack definition, and a WORKFLOW.md configuration file that governs how AI agents work on it.

Requirement

Requirements are submitted in natural language and analyzed by AI to produce structured specifications. Each approved requirement generates a plan.

Plan & Execution

Plans consist of work items that map to execution nodes (design → coding → testing → review). The orchestrator dispatches nodes to runtime daemons.

Runtime Daemon

A lightweight process running on your development machine that discovers installed AI agent CLIs, registers with the server, and executes tasks in isolated workspaces.

Quality Gate

After execution, a 7-dimension quality score is calculated. Based on configurable thresholds, changes can auto-merge, require human review, or be blocked.

Architecture at a Glance

┌─────────┐    ┌─────────────┐    ┌──────────────┐
│  Web UI │───▶│  API Server │───▶│  PostgreSQL  │
│ (React) │    │  (FastAPI)  │    │  + pgvector  │
└─────────┘    └──────┬──────┘    └──────────────┘
                      │
┌─────────┐    ┌──────┴──────┐
│ Desktop │───▶│  Redis      │
│ (Tauri) │    │ (Events)    │
└─────────┘    └──────┬──────┘
                      │
            ┌─────────┴─────────┐
            │  Runtime Daemon   │
            │  (Host Machine)   │
            │  ┌─────────────┐  │
            │  │ Claude Code │  │
            │  │ Codex       │  │
            │  │ OpenCode    │  │
            │  └─────────────┘  │
            └───────────────────┘

Data Hierarchy

Organization → Workspace → Project → Requirement → Execution