# gagriglobal2025/forgeai architecture

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

- Interactive diagram: https://gitdiagram.com/gagriglobal2025/forgeai
- Repository: https://github.com/gagriglobal2025/forgeai

## Overview

Forge AI is a config-driven multi-agent workforce that turns a project brief into versioned SDLC artifacts. Its principal workflow loads the project and task DAG, dispatches dependency-ready agents, gathers their inputs and project context, calls an LLM, then stores and validates each output. Human approval, retries, rework, and escalation govern task completion. The README documents the domain stages and parallel branches; sampled source confirms the runtime and memory interactions. Some stage-level links are documented rather than directly visible in sampled implementation.

Main entry points: [`run.py`](https://github.com/gagriglobal2025/forgeai/blob/main/run.py) (Workflow entry), [`orchestrator/scheduler.py`](https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/scheduler.py) (Task scheduler), [`agents/base_agent.py`](https://github.com/gagriglobal2025/forgeai/blob/main/agents/base_agent.py) (Agent runtime), [`configs/agents.yaml`](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml) (Product and architecture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run coordination"]
  node_runner["Workflow entry<br/>[run.py]"]
  node_dag["Task DAG<br/>[dag_engine.py]"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
end

subgraph group_workforce["SDLC workforce"]
  node_stage_product["Product and architecture<br/>[agents.yaml]"]
  node_stage_design["UX and accessibility<br/>[agents.yaml]"]
  node_stage_frontend["Frontend delivery<br/>[agents.yaml]"]
  node_stage_backend["Backend delivery<br/>[agents.yaml]"]
  node_stage_qa["QA and security<br/>[agents.yaml]"]
  node_stage_release["DevOps and handoff<br/>[agents.yaml]"]
  node_registry["Agent registry<br/>[registry.py]"]
  node_agent["Agent runtime<br/>[base_agent.py]"]
end

subgraph group_memory["Shared memory"]
  node_global_memory[("Project context<br/>[global_memory.py]")]
  node_agent_memory[("Agent scratch<br/>[agent_memory.py]")]
  node_artifacts[("Versioned artifacts<br/>[artifact_store.py]")]
end

subgraph group_services["LLM and events"]
  node_llm["LLM client<br/>[client.py]"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
end

node_operator(("Project operator"))
node_human(("Approver"))
node_providers["Anthropic or OpenAI"]

node_operator -->|"starts run"| node_runner
node_runner -->|"loads workflow"| node_dag
node_runner -->|"loads agents"| node_registry
node_runner -->|"seeds brief"| node_global_memory
node_runner -->|"configures and starts"| node_scheduler
node_runner -->|"creates"| node_agent_memory
node_runner -->|"creates"| node_artifacts
node_runner -->|"creates and subscribes"| node_event_bus
node_scheduler -->|"resolves ready tasks"| node_dag
node_scheduler -->|"dispatches agents"| node_registry
node_registry -->|"instantiates"| node_agent
node_scheduler -->|"emits task events"| node_event_bus
node_scheduler -->|"requests approval"| node_human
node_human -->|"approves or rejects"| node_scheduler
node_agent -->|"reads context"| node_global_memory
node_agent -->|"tracks attempts"| node_agent_memory
node_agent -->|"reads inputs and writes output"| node_artifacts
node_agent -->|"requests completion"| node_llm
node_llm -->|"calls selected API"| node_providers
node_agent -->|"publishes outcomes"| node_event_bus
node_scheduler -.->|"runs configured stages"| node_stage_product
node_stage_product -.->|"branches to design"| node_stage_design
node_stage_design -.->|"feeds frontend"| node_stage_frontend
node_stage_product -.->|"feeds backend"| node_stage_backend
node_stage_frontend -.->|"enters QA"| node_stage_qa
node_stage_backend -.->|"enters QA"| node_stage_qa
node_stage_qa -.->|"advances to release"| node_stage_release

click node_runner "https://github.com/gagriglobal2025/forgeai/blob/main/run.py"
click node_dag "https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/dag_engine.py"
click node_scheduler "https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/scheduler.py"
click node_stage_product "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_stage_design "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_stage_frontend "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_stage_backend "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_stage_qa "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_stage_release "https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml"
click node_registry "https://github.com/gagriglobal2025/forgeai/blob/main/agents/registry.py"
click node_agent "https://github.com/gagriglobal2025/forgeai/blob/main/agents/base_agent.py"
click node_global_memory "https://github.com/gagriglobal2025/forgeai/blob/main/memory/global_memory.py"
click node_agent_memory "https://github.com/gagriglobal2025/forgeai/blob/main/memory/agent_memory.py"
click node_artifacts "https://github.com/gagriglobal2025/forgeai/blob/main/memory/artifact_store.py"
click node_llm "https://github.com/gagriglobal2025/forgeai/blob/main/llm/client.py"
click node_event_bus "https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/event_bus.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_runner,node_dag,node_scheduler toneBlue
class node_stage_product,node_stage_design,node_stage_frontend,node_stage_backend,node_stage_qa,node_stage_release,node_registry,node_agent toneAmber
class node_global_memory,node_agent_memory,node_artifacts toneMint
class node_llm,node_event_bus toneRose
class node_operator,node_human,node_providers toneIndigo
```

## Components

### Run coordination

- [Workflow entry](https://github.com/gagriglobal2025/forgeai/blob/main/run.py): `run.py`
- [Task DAG](https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/dag_engine.py): `orchestrator/dag_engine.py`
- [Task scheduler](https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/scheduler.py): `orchestrator/scheduler.py`

### SDLC workforce

- [Product and architecture](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [UX and accessibility](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [Frontend delivery](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [Backend delivery](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [QA and security](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [DevOps and handoff](https://github.com/gagriglobal2025/forgeai/blob/main/configs/agents.yaml): `configs/agents.yaml`
- [Agent registry](https://github.com/gagriglobal2025/forgeai/blob/main/agents/registry.py): `agents/registry.py`
- [Agent runtime](https://github.com/gagriglobal2025/forgeai/blob/main/agents/base_agent.py): `agents/base_agent.py`

### Shared memory

- [Project context](https://github.com/gagriglobal2025/forgeai/blob/main/memory/global_memory.py): `memory/global_memory.py`
- [Agent scratch](https://github.com/gagriglobal2025/forgeai/blob/main/memory/agent_memory.py): `memory/agent_memory.py`
- [Versioned artifacts](https://github.com/gagriglobal2025/forgeai/blob/main/memory/artifact_store.py): `memory/artifact_store.py`

### LLM and events

- [LLM client](https://github.com/gagriglobal2025/forgeai/blob/main/llm/client.py): `llm/client.py`
- [Event bus](https://github.com/gagriglobal2025/forgeai/blob/main/orchestrator/event_bus.py): `orchestrator/event_bus.py`

### Other components

- **Project operator**
- **Approver**
- **Anthropic or OpenAI**

## Connections

- Project operator → Workflow entry: starts run (evidence: `README.md`)
- Workflow entry → Task DAG: loads workflow (evidence: `run.py`)
- Workflow entry → Agent registry: loads agents (evidence: `run.py`)
- Workflow entry → Project context: seeds brief (evidence: `run.py`)
- Workflow entry → Task scheduler: configures and starts (evidence: `run.py`)
- Workflow entry → Agent scratch: creates (evidence: `run.py`)
- Workflow entry → Versioned artifacts: creates (evidence: `run.py`)
- Workflow entry → Event bus: creates and subscribes (evidence: `run.py`)
- Task scheduler → Task DAG: resolves ready tasks (evidence: `orchestrator/scheduler.py`)
- Task scheduler → Agent registry: dispatches agents (evidence: `orchestrator/scheduler.py`)
- Agent registry → Agent runtime: instantiates (evidence: `agents/registry.py`)
- Task scheduler → Event bus: emits task events (evidence: `orchestrator/scheduler.py`)
- Task scheduler → Approver: requests approval (evidence: `orchestrator/scheduler.py`)
- Approver → Task scheduler: approves or rejects (evidence: `orchestrator/scheduler.py`)
- Agent runtime → Project context: reads context (evidence: `agents/base_agent.py`)
- Agent runtime → Agent scratch: tracks attempts (evidence: `agents/base_agent.py`)
- Agent runtime → Versioned artifacts: reads inputs and writes output (evidence: `agents/base_agent.py`)
- Agent runtime → LLM client: requests completion (evidence: `agents/base_agent.py`)
- LLM client → Anthropic or OpenAI: calls selected API (evidence: `llm/client.py`)
- Agent runtime → Event bus: publishes outcomes (evidence: `agents/base_agent.py`)
- Task scheduler → Product and architecture: runs configured stages (evidence: `README.md`)
- Product and architecture → UX and accessibility: branches to design (evidence: `README.md`)
- UX and accessibility → Frontend delivery: feeds frontend (evidence: `README.md`)
- Product and architecture → Backend delivery: feeds backend (evidence: `README.md`)
- Frontend delivery → QA and security: enters QA (evidence: `README.md`)
- Backend delivery → QA and security: enters QA (evidence: `README.md`)
- QA and security → DevOps and handoff: advances to release (evidence: `README.md`)
