# alsh007/forge-ai architecture

> Architecture diagram of the GitHub repository alsh007/forge-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alsh007/forge-ai
- Repository: https://github.com/alsh007/forge-ai

## Overview

ForgeAI accepts a task and GitHub repository, runs six specialized agents in sequence, validates and may repair generated code, then reports progress and can open a pull request. The dashboard polls task and execution state through the authenticated API. The graph reflects README-documented workflow and capabilities plus the shown source references; unsampled modules are represented only where the README or source index supports their role.

Main entry points: [`backend/src/execution.ts`](https://github.com/alsh007/forge-ai/blob/main/backend/src/execution.ts) (Execution service), [`backend/src/index.ts`](https://github.com/alsh007/forge-ai/blob/main/backend/src/index.ts) (HTTP API), [`agent-core/src/index.ts`](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/index.ts) (Agent coordinator), [`agent-core/src/llm/client.ts`](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/llm/client.ts) (Groq LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Task dashboard<br/>[index.tsx]"]
  node_taskform["Task form<br/>[TaskForm.tsx]"]
  node_pipelineview["Live pipeline<br/>[AgentPipeline.tsx]"]
  node_authgate["Sign-in gate<br/>[AuthGate.tsx]"]
  node_frontendapi["API client<br/>[api.ts]"]
  node_frontendstore["Task state<br/>[store.ts]"]
  node_supabaseclient["Supabase client<br/>[supabase.ts]"]
end

subgraph group_api["API and identity"]
  node_backendapi["HTTP API<br/>[index.ts]"]
  node_authverify["JWT verification<br/>[auth.ts]"]
end

subgraph group_orchestration["Task orchestration"]
  node_taskexecution["Execution service<br/>[execution.ts]"]
  node_taskcontrol["Cancel and timeout<br/>[taskControl.ts]"]
end

subgraph group_agents["Agent generation"]
  node_coordinator["Agent coordinator<br/>[index.ts]"]
  node_planning["Plan and design<br/>[base.ts]"]
  node_databaseagent["Database agent<br/>[base.ts]"]
  node_codeagents["Backend and frontend agents<br/>[base.ts]"]
  node_devopsagent["DevOps review<br/>[base.ts]"]
  node_validation["Static validation and repair<br/>[static.ts]"]
end

subgraph group_integrations["Persistence and integrations"]
  node_llmclient["Groq LLM client<br/>[client.ts]"]
  node_repotools["Repository tools<br/>[tools.ts]"]
  node_githubservice["GitHub repository and PR<br/>[github.ts]"]
  node_tokencrypto["GitHub token encryption<br/>[crypto.ts]"]
  node_storage[("Task and execution storage<br/>[storage.ts]")]
end

node_user(("Task submitter"))
node_supabase["Supabase auth"]
node_groq["Groq API"]
node_github["GitHub"]
node_postgres[("PostgreSQL")]

node_user -->|"signs in"| node_authgate
node_user -->|"submits task"| node_taskform
node_authgate -->|"uses auth"| node_supabaseclient
node_supabaseclient -->|"authenticates with"| node_supabase
node_taskform -->|"submits values"| node_dashboard
node_dashboard -->|"requests task data"| node_frontendapi
node_dashboard -->|"updates task state"| node_frontendstore
node_dashboard -->|"renders progress"| node_pipelineview
node_frontendapi -->|"gets session token"| node_supabaseclient
node_frontendapi -->|"calls API"| node_backendapi
node_backendapi -->|"requires auth"| node_authverify
node_authverify -->|"verifies JWT"| node_supabase
node_authverify -->|"upserts user"| node_storage
node_backendapi -->|"reads and writes tasks"| node_storage
node_backendapi -->|"starts execution"| node_taskexecution
node_backendapi -->|"requests cancellation"| node_taskcontrol
node_taskexecution -->|"registers and cancels"| node_taskcontrol
node_taskexecution -->|"records progress"| node_storage
node_taskexecution -->|"runs agent workflow"| node_coordinator
node_taskexecution -->|"loads repo and opens PR"| node_githubservice
node_taskexecution -->|"decrypts user token"| node_tokencrypto
node_backendapi -->|"encrypts submitted token"| node_tokencrypto
node_githubservice -->|"reads repo and creates PR"| node_github
node_coordinator -->|"runs first stages"| node_planning
node_coordinator -->|"runs database stage"| node_databaseagent
node_coordinator -->|"runs code generation"| node_codeagents
node_coordinator -->|"validates and repairs"| node_validation
node_coordinator -->|"runs final review"| node_devopsagent
node_planning -->|"requests completion"| node_llmclient
node_databaseagent -->|"requests generation"| node_llmclient
node_codeagents -->|"requests generation"| node_llmclient
node_devopsagent -->|"requests review"| node_llmclient
node_llmclient -->|"sends model requests"| node_groq
node_codeagents -->|"uses repository tools"| node_repotools
node_repotools -.->|"reads repository context"| node_githubservice
node_taskexecution -.->|"persists when configured"| node_postgres
node_storage -.->|"uses Prisma adapter"| node_postgres

click node_dashboard "https://github.com/alsh007/forge-ai/blob/main/frontend/pages/index.tsx"
click node_taskform "https://github.com/alsh007/forge-ai/blob/main/frontend/components/TaskForm.tsx"
click node_pipelineview "https://github.com/alsh007/forge-ai/blob/main/frontend/components/AgentPipeline.tsx"
click node_authgate "https://github.com/alsh007/forge-ai/blob/main/frontend/components/AuthGate.tsx"
click node_frontendapi "https://github.com/alsh007/forge-ai/blob/main/frontend/lib/api.ts"
click node_frontendstore "https://github.com/alsh007/forge-ai/blob/main/frontend/lib/store.ts"
click node_supabaseclient "https://github.com/alsh007/forge-ai/blob/main/frontend/lib/supabase.ts"
click node_backendapi "https://github.com/alsh007/forge-ai/blob/main/backend/src/index.ts"
click node_authverify "https://github.com/alsh007/forge-ai/blob/main/backend/src/auth.ts"
click node_taskexecution "https://github.com/alsh007/forge-ai/blob/main/backend/src/execution.ts"
click node_taskcontrol "https://github.com/alsh007/forge-ai/blob/main/backend/src/taskControl.ts"
click node_coordinator "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/index.ts"
click node_planning "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts"
click node_databaseagent "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts"
click node_codeagents "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts"
click node_devopsagent "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts"
click node_validation "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/validation/static.ts"
click node_llmclient "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/llm/client.ts"
click node_repotools "https://github.com/alsh007/forge-ai/blob/main/agent-core/src/llm/tools.ts"
click node_githubservice "https://github.com/alsh007/forge-ai/blob/main/backend/src/github.ts"
click node_tokencrypto "https://github.com/alsh007/forge-ai/blob/main/backend/src/crypto.ts"
click node_storage "https://github.com/alsh007/forge-ai/blob/main/backend/src/storage.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_taskform,node_pipelineview,node_authgate,node_frontendapi,node_frontendstore,node_supabaseclient toneBlue
class node_backendapi,node_authverify,node_postgres toneAmber
class node_taskexecution,node_taskcontrol,node_groq toneMint
class node_coordinator,node_planning,node_databaseagent,node_codeagents,node_devopsagent,node_validation,node_user toneRose
class node_llmclient,node_repotools,node_githubservice,node_tokencrypto,node_storage,node_supabase,node_github toneIndigo
```

## Components

### User experience

- [Task dashboard](https://github.com/alsh007/forge-ai/blob/main/frontend/pages/index.tsx): `frontend/pages/index.tsx`
- [Task form](https://github.com/alsh007/forge-ai/blob/main/frontend/components/TaskForm.tsx): `frontend/components/TaskForm.tsx`
- [Live pipeline](https://github.com/alsh007/forge-ai/blob/main/frontend/components/AgentPipeline.tsx): `frontend/components/AgentPipeline.tsx`
- [Sign-in gate](https://github.com/alsh007/forge-ai/blob/main/frontend/components/AuthGate.tsx): `frontend/components/AuthGate.tsx`
- [API client](https://github.com/alsh007/forge-ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Task state](https://github.com/alsh007/forge-ai/blob/main/frontend/lib/store.ts): `frontend/lib/store.ts`
- [Supabase client](https://github.com/alsh007/forge-ai/blob/main/frontend/lib/supabase.ts): `frontend/lib/supabase.ts`

### API and identity

- [HTTP API](https://github.com/alsh007/forge-ai/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [JWT verification](https://github.com/alsh007/forge-ai/blob/main/backend/src/auth.ts): `backend/src/auth.ts`

### Task orchestration

- [Execution service](https://github.com/alsh007/forge-ai/blob/main/backend/src/execution.ts): `backend/src/execution.ts`
- [Cancel and timeout](https://github.com/alsh007/forge-ai/blob/main/backend/src/taskControl.ts): `backend/src/taskControl.ts`

### Agent generation

- [Agent coordinator](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/index.ts): `agent-core/src/index.ts`
- [Plan and design](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts): `agent-core/src/agents/base.ts`
- [Database agent](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts): `agent-core/src/agents/base.ts`
- [Backend and frontend agents](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts): `agent-core/src/agents/base.ts`
- [DevOps review](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/agents/base.ts): `agent-core/src/agents/base.ts`
- [Static validation and repair](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/validation/static.ts): `agent-core/src/validation/static.ts`

### Persistence and integrations

- [Groq LLM client](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/llm/client.ts): `agent-core/src/llm/client.ts`
- [Repository tools](https://github.com/alsh007/forge-ai/blob/main/agent-core/src/llm/tools.ts): `agent-core/src/llm/tools.ts`
- [GitHub repository and PR](https://github.com/alsh007/forge-ai/blob/main/backend/src/github.ts): `backend/src/github.ts`
- [GitHub token encryption](https://github.com/alsh007/forge-ai/blob/main/backend/src/crypto.ts): `backend/src/crypto.ts`
- [Task and execution storage](https://github.com/alsh007/forge-ai/blob/main/backend/src/storage.ts): `backend/src/storage.ts`

### Other components

- **Task submitter**
- **Supabase auth**
- **Groq API**
- **GitHub**
- **PostgreSQL**

## Connections

- Task submitter → Sign-in gate: signs in (evidence: `README.md`)
- Task submitter → Task form: submits task (evidence: `README.md`)
- Sign-in gate → Supabase client: uses auth
- Supabase client → Supabase auth: authenticates with (evidence: `README.md`)
- Task form → Task dashboard: submits values (evidence: `frontend/pages/index.tsx`)
- Task dashboard → API client: requests task data (evidence: `frontend/pages/index.tsx`)
- Task dashboard → Task state: updates task state (evidence: `frontend/pages/index.tsx`)
- Task dashboard → Live pipeline: renders progress (evidence: `frontend/pages/index.tsx`)
- API client → Supabase client: gets session token (evidence: `frontend/lib/api.ts`)
- API client → HTTP API: calls API (evidence: `README.md`)
- HTTP API → JWT verification: requires auth (evidence: `backend/src/index.ts`)
- JWT verification → Supabase auth: verifies JWT (evidence: `backend/src/auth.ts`)
- JWT verification → Task and execution storage: upserts user (evidence: `backend/src/auth.ts`)
- HTTP API → Task and execution storage: reads and writes tasks (evidence: `backend/src/index.ts`)
- HTTP API → Execution service: starts execution (evidence: `backend/src/index.ts`)
- HTTP API → Cancel and timeout: requests cancellation (evidence: `backend/src/index.ts`)
- Execution service → Cancel and timeout: registers and cancels (evidence: `backend/src/execution.ts`)
- Execution service → Task and execution storage: records progress (evidence: `backend/src/execution.ts`)
- Execution service → Agent coordinator: runs agent workflow (evidence: `README.md`)
- Execution service → GitHub repository and PR: loads repo and opens PR (evidence: `backend/src/execution.ts`)
- Execution service → GitHub token encryption: decrypts user token (evidence: `backend/src/execution.ts`)
- HTTP API → GitHub token encryption: encrypts submitted token (evidence: `backend/src/index.ts`)
- GitHub repository and PR → GitHub: reads repo and creates PR (evidence: `README.md`)
- Agent coordinator → Plan and design: runs first stages (evidence: `README.md`)
- Agent coordinator → Database agent: runs database stage (evidence: `README.md`)
- Agent coordinator → Backend and frontend agents: runs code generation (evidence: `README.md`)
- Agent coordinator → Static validation and repair: validates and repairs (evidence: `agent-core/src/index.ts`)
- Agent coordinator → DevOps review: runs final review (evidence: `README.md`)
- Plan and design → Groq LLM client: requests completion (evidence: `agent-core/src/agents/base.ts`)
- Database agent → Groq LLM client: requests generation (evidence: `agent-core/src/agents/base.ts`)
- Backend and frontend agents → Groq LLM client: requests generation (evidence: `agent-core/src/agents/base.ts`)
- DevOps review → Groq LLM client: requests review (evidence: `README.md`)
- Groq LLM client → Groq API: sends model requests (evidence: `README.md`)
- Backend and frontend agents → Repository tools: uses repository tools (evidence: `agent-core/src/agents/base.ts`)
- Repository tools → GitHub repository and PR: reads repository context
- Execution service → PostgreSQL: persists when configured (evidence: `README.md`)
- Task and execution storage → PostgreSQL: uses Prisma adapter (evidence: `README.md`)