# mr-saab-29/multi-agent-scaffold architecture

> Architecture diagram of the GitHub repository mr-saab-29/multi-agent-scaffold, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-saab-29/multi-agent-scaffold
- Repository: https://github.com/mr-saab-29/multi-agent-scaffold

## Overview

The product turns an app idea into a traceable starter-specification and stub-generation run, then validates, reviews, optionally corrects, and packages its outputs. The FastAPI API is the main entry point; the Streamlit demo submits prompts and inspects run state, events, and artifacts. The README documents the complete ordered pipeline, while sampled source confirms API/async behavior, LLM fallback and governance, review checks, retrieval, and artifact access. Some stage wiring is documented rather than sampled, so those links follow the README workflow; uncertain implementation details are omitted.

Main entry points: [`app/orchestrator/runner.py`](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/runner.py) (Pipeline runner), [`app/services/llm.py`](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/llm.py) (LLM client), [`app/services/prompt_loader.py`](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/prompt_loader.py) (Prompt loader), [`app/api/routes.py`](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/api/routes.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_ui["Streamlit demo<br/>[streamlit_app.py]"]
  node_api["FastAPI routes<br/>[routes.py]"]
  node_main["FastAPI app<br/>[main.py]"]
end

subgraph group_control["Run Orchestration"]
  node_runner["Pipeline runner<br/>[runner.py]"]
  node_async["Async manager<br/>[async_manager.py]"]
  node_state["Run state<br/>[state.py]"]
end

subgraph group_generation["Planning and Generation"]
  node_planner["Planner<br/>[planner.py]"]
  node_retrieval["Template retrieval<br/>[retrieval.py]"]
  node_architect["Architect<br/>[architect.py]"]
  node_schema["Schema agent<br/>[schema_agent.py]"]
  node_api_agent["API planner<br/>[api_agent.py]"]
  node_frontend["Frontend planner<br/>[frontend_agent.py]"]
  node_codegen["Code generator<br/>[codegen.py]"]
end

subgraph group_quality["Validation and Review"]
  node_validation["Deterministic validation"]
  node_api_checker["API checker<br/>[api_checker.py]"]
  node_ui_mapper["UI mapper<br/>[ui_mapper.py]"]
  node_reviewer["Reviewer<br/>[reviewer.py]"]
  node_packager["Artifact packager<br/>[packager.py]"]
end

subgraph group_runtime["Runtime Services"]
  node_store[("Artifact store<br/>[artifact_store.py]")]
  node_llm["LLM client<br/>[llm.py]"]
  node_prompts["Prompt loader<br/>[prompt_loader.py]"]
  node_cache["Stage cache<br/>[stage_cache.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
end

node_user(("App idea"))
node_gemini["Gemini service"]
node_artifacts["Run artifacts"]

node_user -->|"enters idea"| node_ui
node_ui -->|"submits prompt"| node_api
node_ui -->|"requests run data"| node_api
node_main -->|"mounts routes"| node_api
node_api -->|"runs pipeline"| node_runner
node_api -->|"submits or approves"| node_async
node_async -->|"executes run"| node_runner
node_runner -->|"updates state"| node_state
node_runner -->|"plans"| node_planner
node_runner -->|"retrieves templates"| node_retrieval
node_runner -->|"designs architecture"| node_architect
node_runner -->|"defines schema"| node_schema
node_runner -->|"plans API"| node_api_agent
node_runner -->|"plans frontend"| node_frontend
node_runner -->|"generates stubs"| node_codegen
node_runner -->|"validates schema"| node_validation
node_runner -->|"checks API"| node_api_checker
node_runner -->|"checks mappings"| node_ui_mapper
node_runner -->|"requests review"| node_reviewer
node_reviewer -->|"flags correction"| node_runner
node_runner -->|"packages outputs"| node_packager
node_runner -->|"persists run outputs"| node_store
node_async -->|"persists paused run"| node_store
node_store -->|"writes files"| node_artifacts
node_api -->|"reads artifact content"| node_store
node_ui -->|"browses and downloads"| node_artifacts
node_planner -->|"requests generation"| node_llm
node_architect -->|"requests generation"| node_llm
node_schema -->|"requests generation"| node_llm
node_api_agent -->|"requests generation"| node_llm
node_frontend -->|"requests generation"| node_llm
node_codegen -->|"requests generation"| node_llm
node_reviewer -->|"requests generation"| node_llm
node_llm -.->|"generates content"| node_gemini
node_planner -->|"loads prompts"| node_prompts
node_architect -->|"loads prompts"| node_prompts
node_schema -->|"loads prompts"| node_prompts
node_api_agent -->|"loads prompts"| node_prompts
node_frontend -->|"loads prompts"| node_prompts
node_codegen -->|"loads prompts"| node_prompts
node_reviewer -->|"loads prompts"| node_prompts
node_runner -.->|"reuses stage results"| node_cache
node_main -->|"records HTTP metrics"| node_metrics
node_async -->|"records run metrics"| node_metrics

click node_ui "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/ui/streamlit_app.py"
click node_api "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/api/routes.py"
click node_main "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/main.py"
click node_runner "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/runner.py"
click node_async "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/async_manager.py"
click node_state "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/state.py"
click node_planner "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/planner.py"
click node_retrieval "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/retrieval.py"
click node_architect "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/architect.py"
click node_schema "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/schema_agent.py"
click node_api_agent "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/api_agent.py"
click node_frontend "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/frontend_agent.py"
click node_codegen "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/codegen.py"
click node_validation "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/schema_validator.py"
click node_api_checker "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/api_checker.py"
click node_ui_mapper "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/ui_mapper.py"
click node_reviewer "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/reviewer.py"
click node_packager "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/packager.py"
click node_store "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/artifact_store.py"
click node_llm "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/llm.py"
click node_prompts "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/prompt_loader.py"
click node_cache "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/stage_cache.py"
click node_metrics "https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/core/metrics.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_main toneBlue
class node_runner,node_async,node_state toneAmber
class node_planner,node_retrieval,node_architect,node_schema,node_api_agent,node_frontend,node_codegen toneMint
class node_validation,node_api_checker,node_ui_mapper,node_reviewer,node_packager toneRose
class node_store,node_llm,node_prompts,node_cache,node_metrics,node_user,node_gemini,node_artifacts toneIndigo
```

## Components

### User Interfaces

- [Streamlit demo](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`
- [FastAPI routes](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/api/routes.py): `app/api/routes.py`
- [FastAPI app](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/main.py): `app/main.py`

### Run Orchestration

- [Pipeline runner](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/runner.py): `app/orchestrator/runner.py`
- [Async manager](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/async_manager.py): `app/orchestrator/async_manager.py`
- [Run state](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/orchestrator/state.py): `app/orchestrator/state.py`

### Planning and Generation

- [Planner](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/planner.py): `app/agents/planner.py`
- [Template retrieval](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/retrieval.py): `app/tools/retrieval.py`
- [Architect](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/architect.py): `app/agents/architect.py`
- [Schema agent](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/schema_agent.py): `app/agents/schema_agent.py`
- [API planner](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/api_agent.py): `app/agents/api_agent.py`
- [Frontend planner](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/frontend_agent.py): `app/agents/frontend_agent.py`
- [Code generator](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/codegen.py): `app/agents/codegen.py`

### Validation and Review

- [Deterministic validation](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/schema_validator.py): `app/tools/schema_validator.py`
- [API checker](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/api_checker.py): `app/tools/api_checker.py`
- [UI mapper](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/ui_mapper.py): `app/tools/ui_mapper.py`
- [Reviewer](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/agents/reviewer.py): `app/agents/reviewer.py`
- [Artifact packager](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/tools/packager.py): `app/tools/packager.py`

### Runtime Services

- [Artifact store](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/artifact_store.py): `app/services/artifact_store.py`
- [LLM client](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/llm.py): `app/services/llm.py`
- [Prompt loader](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/prompt_loader.py): `app/services/prompt_loader.py`
- [Stage cache](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/services/stage_cache.py): `app/services/stage_cache.py`
- [Prometheus metrics](https://github.com/mr-saab-29/multi-agent-scaffold/blob/main/app/core/metrics.py): `app/core/metrics.py`

### Other components

- **App idea**
- **Gemini service**
- **Run artifacts**

## Connections

- App idea → Streamlit demo: enters idea
- Streamlit demo → FastAPI routes: submits prompt
- Streamlit demo → FastAPI routes: requests run data
- FastAPI app → FastAPI routes: mounts routes
- FastAPI routes → Pipeline runner: runs pipeline
- FastAPI routes → Async manager: submits or approves
- Async manager → Pipeline runner: executes run
- Pipeline runner → Run state: updates state
- Pipeline runner → Planner: plans
- Pipeline runner → Template retrieval: retrieves templates
- Pipeline runner → Architect: designs architecture
- Pipeline runner → Schema agent: defines schema
- Pipeline runner → API planner: plans API
- Pipeline runner → Frontend planner: plans frontend
- Pipeline runner → Code generator: generates stubs
- Pipeline runner → Deterministic validation: validates schema
- Pipeline runner → API checker: checks API
- Pipeline runner → UI mapper: checks mappings
- Pipeline runner → Reviewer: requests review
- Reviewer → Pipeline runner: flags correction
- Pipeline runner → Artifact packager: packages outputs
- Pipeline runner → Artifact store: persists run outputs
- Async manager → Artifact store: persists paused run
- Artifact store → Run artifacts: writes files
- FastAPI routes → Artifact store: reads artifact content
- Streamlit demo → Run artifacts: browses and downloads
- Planner → LLM client: requests generation
- Architect → LLM client: requests generation
- Schema agent → LLM client: requests generation
- API planner → LLM client: requests generation
- Frontend planner → LLM client: requests generation
- Code generator → LLM client: requests generation
- Reviewer → LLM client: requests generation
- LLM client → Gemini service: generates content
- Planner → Prompt loader: loads prompts
- Architect → Prompt loader: loads prompts
- Schema agent → Prompt loader: loads prompts
- API planner → Prompt loader: loads prompts
- Frontend planner → Prompt loader: loads prompts
- Code generator → Prompt loader: loads prompts
- Reviewer → Prompt loader: loads prompts
- Pipeline runner → Stage cache: reuses stage results
- FastAPI app → Prometheus metrics: records HTTP metrics
- Async manager → Prometheus metrics: records run metrics