# shahid0324-git/forge-fsd architecture

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

- Interactive diagram: https://gitdiagram.com/shahid0324-git/forge-fsd
- Repository: https://github.com/shahid0324-git/forge-fsd

## Overview

ForgeFSD is a local-first agent-assisted full-stack app development system. Its principal dashboard workflow gathers and clarifies a request, produces a reviewable proposal, waits for approval, delegates source generation, runs build and independent browser checks, and repairs failures before separately approved preview or release actions. The graph also includes task/handoff state, older typed-plan verification, security, and release capabilities documented in the README. Some subsystem links are based on README descriptions or worker dispatch; unsampled internals are not assumed.

Main entry points: [`src/forge/dashboard_worker.py`](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/dashboard_worker.py) (Job worker), [`src/forge/autonomous_planning.py`](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_planning.py) (Autonomous planning), [`src/forge/autonomous_testing.py`](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_testing.py) (Autonomous QA), [`src/forge/builders.py`](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/builders.py) (Typed workflow builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_ui["Dashboard UI<br/>[App.tsx]"]
  node_api["Dashboard API<br/>[api.py]"]
  node_worker["Job worker"]
end

subgraph group_orchestration["Planning and orchestration"]
  node_planner["Autonomous planning"]
  node_coordinator["Task coordination<br/>[coordinator.py]"]
  node_tasks["Task ledger<br/>[tasks.py]"]
  node_handoffs["Role handoffs<br/>[handoffs.py]"]
  node_persistence[("Job persistence<br/>[persistence.py]")]
end

subgraph group_implementation["App implementation"]
  node_builder["Typed workflow builder<br/>[builders.py]"]
  node_source["Source agent<br/>[source_agent.py]"]
  node_workspace["Workspace boundary<br/>[workspace.py]"]
  node_tools["Workspace tools<br/>[workspace_tools.py]"]
end

subgraph group_quality["Verification and release"]
  node_buildcheck["Autonomous build checks"]
  node_testing["Autonomous QA"]
  node_acceptance["Browser acceptance"]
  node_reviews["Suite and scope review"]
  node_repair["Repair workflow<br/>[repair.py]"]
  node_senior["Senior review<br/>[senior_review.py]"]
  node_verification["Typed verification<br/>[verification.py]"]
  node_security["Security checks<br/>[security.py]"]
  node_preview["Approved preview<br/>[preview.py]"]
  node_release["Release preparation<br/>[releases.py]"]
end

node_user(("Developer"))
node_ollama{{"Ollama models"}}
node_groq{{"Groq inference"}}

node_user -->|"submits request"| node_ui
node_ui -->|"dashboard actions"| node_api
node_api -.->|"dispatches jobs"| node_worker
node_worker -->|"plans autonomously"| node_planner
node_planner -->|"uses coordination"| node_coordinator
node_planner -->|"creates task work"| node_tasks
node_planner -->|"reads workspace context"| node_workspace
node_worker -->|"runs typed generation"| node_builder
node_worker -->|"runs acceptance QA"| node_testing
node_worker -->|"starts approved preview"| node_preview
node_worker -->|"dispatches release actions"| node_release
node_builder -->|"records delegation"| node_handoffs
node_builder -->|"uses workspace context"| node_workspace
node_source -->|"uses editing tools"| node_tools
node_source -->|"reads task state"| node_tasks
node_tasks -->|"loads timestamps"| node_persistence
node_handoffs -->|"records events"| node_persistence
node_testing -->|"executes browser checks"| node_acceptance
node_testing -->|"reviews proposed suite"| node_reviews
node_testing -->|"runs build checks"| node_buildcheck
node_worker -->|"routes repair work"| node_repair
node_senior -->|"records review handoff"| node_handoffs
node_verification -->|"checks generated app"| node_builder
node_preview -->|"requires security evidence"| node_security
node_planner -.->|"uses selected model"| node_ollama
node_planner -.->|"optional hybrid inference"| node_groq

click node_ui "https://github.com/shahid0324-git/forge-fsd/blob/main/apps/web/src/App.tsx"
click node_api "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/api.py"
click node_worker "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/dashboard_worker.py"
click node_planner "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_planning.py"
click node_coordinator "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/coordinator.py"
click node_tasks "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/tasks.py"
click node_handoffs "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/handoffs.py"
click node_persistence "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/persistence.py"
click node_builder "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/builders.py"
click node_source "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/source_agent.py"
click node_workspace "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/workspace.py"
click node_tools "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/workspace_tools.py"
click node_buildcheck "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_build.py"
click node_testing "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_testing.py"
click node_acceptance "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/acceptance_browser.py"
click node_reviews "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/acceptance_review.py"
click node_repair "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/repair.py"
click node_senior "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/senior_review.py"
click node_verification "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/verification.py"
click node_security "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/security.py"
click node_preview "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/preview.py"
click node_release "https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/releases.py"

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_ui,node_api,node_worker toneBlue
class node_planner,node_coordinator,node_tasks,node_handoffs,node_persistence toneAmber
class node_builder,node_source,node_workspace,node_tools toneMint
class node_buildcheck,node_testing,node_acceptance,node_reviews,node_repair,node_senior,node_verification,node_security,node_preview,node_release toneRose
class node_user,node_ollama,node_groq toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/shahid0324-git/forge-fsd/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Dashboard API](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/api.py): `src/forge/api.py`
- [Job worker](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/dashboard_worker.py): `src/forge/dashboard_worker.py`

### Planning and orchestration

- [Autonomous planning](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_planning.py): `src/forge/autonomous_planning.py`
- [Task coordination](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/coordinator.py): `src/forge/coordinator.py`
- [Task ledger](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/tasks.py): `src/forge/tasks.py`
- [Role handoffs](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/handoffs.py): `src/forge/handoffs.py`
- [Job persistence](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/persistence.py): `src/forge/persistence.py`

### App implementation

- [Typed workflow builder](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/builders.py): `src/forge/builders.py`
- [Source agent](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/source_agent.py): `src/forge/source_agent.py`
- [Workspace boundary](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/workspace.py): `src/forge/workspace.py`
- [Workspace tools](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/workspace_tools.py): `src/forge/workspace_tools.py`

### Verification and release

- [Autonomous build checks](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_build.py): `src/forge/autonomous_build.py`
- [Autonomous QA](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/autonomous_testing.py): `src/forge/autonomous_testing.py`
- [Browser acceptance](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/acceptance_browser.py): `src/forge/acceptance_browser.py`
- [Suite and scope review](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/acceptance_review.py): `src/forge/acceptance_review.py`
- [Repair workflow](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/repair.py): `src/forge/repair.py`
- [Senior review](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/senior_review.py): `src/forge/senior_review.py`
- [Typed verification](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/verification.py): `src/forge/verification.py`
- [Security checks](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/security.py): `src/forge/security.py`
- [Approved preview](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/preview.py): `src/forge/preview.py`
- [Release preparation](https://github.com/shahid0324-git/forge-fsd/blob/main/src/forge/releases.py): `src/forge/releases.py`

### Other components

- **Developer**
- **Ollama models**
- **Groq inference**

## Connections

- Developer → Dashboard UI: submits request
- Dashboard UI → Dashboard API: dashboard actions
- Dashboard API → Job worker: dispatches jobs
- Job worker → Autonomous planning: plans autonomously (evidence: `src/forge/dashboard_worker.py`)
- Autonomous planning → Task coordination: uses coordination (evidence: `src/forge/autonomous_planning.py`)
- Autonomous planning → Task ledger: creates task work (evidence: `src/forge/autonomous_planning.py`)
- Autonomous planning → Workspace boundary: reads workspace context (evidence: `src/forge/autonomous_planning.py`)
- Job worker → Typed workflow builder: runs typed generation (evidence: `src/forge/dashboard_worker.py`)
- Job worker → Autonomous QA: runs acceptance QA (evidence: `src/forge/dashboard_worker.py`)
- Job worker → Approved preview: starts approved preview (evidence: `src/forge/dashboard_worker.py`)
- Job worker → Release preparation: dispatches release actions (evidence: `src/forge/dashboard_worker.py`)
- Typed workflow builder → Role handoffs: records delegation (evidence: `src/forge/builders.py`)
- Typed workflow builder → Workspace boundary: uses workspace context (evidence: `src/forge/builders.py`)
- Source agent → Workspace tools: uses editing tools (evidence: `src/forge/source_agent.py`)
- Source agent → Task ledger: reads task state (evidence: `src/forge/source_agent.py`)
- Task ledger → Job persistence: loads timestamps (evidence: `src/forge/tasks.py`)
- Role handoffs → Job persistence: records events (evidence: `src/forge/handoffs.py`)
- Autonomous QA → Browser acceptance: executes browser checks (evidence: `src/forge/autonomous_testing.py`)
- Autonomous QA → Suite and scope review: reviews proposed suite (evidence: `src/forge/autonomous_testing.py`)
- Autonomous QA → Autonomous build checks: runs build checks (evidence: `src/forge/autonomous_testing.py`)
- Job worker → Repair workflow: routes repair work (evidence: `src/forge/dashboard_worker.py`)
- Senior review → Role handoffs: records review handoff (evidence: `src/forge/senior_review.py`)
- Typed verification → Typed workflow builder: checks generated app (evidence: `src/forge/verification.py`)
- Approved preview → Security checks: requires security evidence (evidence: `src/forge/preview.py`)
- Autonomous planning → Ollama models: uses selected model
- Autonomous planning → Groq inference: optional hybrid inference
