# tathadn/parallel-multi-agent-codegen architecture

> Architecture diagram of the GitHub repository tathadn/parallel-multi-agent-codegen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tathadn/parallel-multi-agent-codegen
- Repository: https://github.com/tathadn/parallel-multi-agent-codegen

## Overview

1. **What this repo is**  
A Python-based, LLM-driven code generation system that turns a natural-language request into a planned set of code artifacts, generates them in parallel, integrates the outputs, then reviews and tests the result before returning a final package.

2. **Main runtime entrypoint**  
`app.py` is the user-facing Streamlit application. It likely serves as the control panel for submitting requests and visualizing pipeline progress, DAG state, timings, and generated artifacts. The rest of the repository is the backend workflow that Streamlit drives.

3. **Core architecture: stateful agent pipeline**  
The system centers on a shared typed state in `models/state.py`. That state carries the user request, the plan, the task DAG, produced artifacts, review/test results, logs, timing, and iteration counters. Every agent reads from and writes to this shared state, so the architecture is not request/response RPC style; it is a state machine over a single evolving workflow object.

4. **Planning and decomposition layer**  
The pipeline starts with a Planner agent, then the Orchestrator transforms that plan into a DAG of implementation tasks. The key architectural choice is dependency-aware decomposition: files/modules that can be built independently are separated into parallel nodes, while import or schema dependencies become edges in the graph.

5. **Parallel code generation layer**  
`agents/coder.py` is the concurrent worker layer. Multiple coder agents run in parallel using asyncio, each responsible for one DAG node or grouped module set. This is the main scalability boundary in the system: all independent nodes are dispatched simultaneously, reducing end-to-end latency compared with a sequential agent chain.

6. **Merge and validation layer**  
`agents/integrator.py` reconciles the parallel outputs into a coherent codebase, resolving interface mismatches and import conflicts introduced by concurrent generation. After integration, `agents/reviewer.py` scores or critiques the result, and `agents/tester.py` generates/runs tests. The README indicates a revision loop: failing review/test outcomes can send only the affected DAG nodes back for regeneration rather than rebuilding everything.

7. **Workflow engine**  
`graph/pipeline.py` is the orchestration definition, and the repository uses LangGraph to express conditional transitions between phases. This makes the pipeline a graph of states rather than a fixed linear script, which is important for the revision loop and for routing based on review/test outcomes.

8. **LLM and tracing boundary**  
`agents/llm_utils.py` is the shared API boundary to Anthropic’s native SDK. The README highlights prompt caching via `cache_control={"type": "ephemeral"}` and LangSmith tracing through `@traceable`. This means all agent calls share one LLM transport layer, one tracing strategy, and one place for caching/cost behavior.

9. **Prompting and role separation**  
`prompts/` stores the system prompts/templates for each role. The architecture depends on role specialization: orchestrator, planner, coder, integrator, reviewer, and tester each have distinct prompt contracts and output shapes. That separation is important because the system’s correctness depends on structured outputs, not free-form chat.

10. **Sandboxed execution boundary**  
`sandbox/Dockerfile` defines an isolated environment for test execution. That indicates a safety boundary between generated code and the host machine: tests run in a containerized sandbox rather than directly on the developer’s machine.

11. **Testing strategy for the repo itself**  
The `tests/` folder is focused on infrastructure correctness rather than generated-code correctness. There are tests for models, pipeline routing, LLM JSON parsing, and agent behavior using mocked LLM calls. So the repository’s own test suite validates orchestration logic, DAG scheduling, and agent contracts without requiring real Anthropic traffic.

12. **Architectural summary for diagramming**  
If you draw this repo, the main boxes are: UI (`app.py`) → shared state (`models/state.py`) → orchestrated pipeline (`graph/pipeline.py`) → role-based agents (`agents/*`) → sandboxed testing (`sandbox/`) → final output and revision loop. The key data flow is request → plan → DAG → parallel worker artifacts → integration → review/test → optional targeted regeneration → final result.

Main entry points: [`graph/pipeline.py`](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/graph/pipeline.py) (Pipeline graph), [`models/state.py`](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/models/state.py) (Workflow state), [`agents/coder.py`](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/coder.py) (Coder pool), [`tests/test_agents.py`](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_agents.py) (Agent tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app["Streamlit app<br/>ui entrypoint<br/>[app.py]"]
end

subgraph group_core["Core flow"]
  node_state[("Workflow state<br/>typed state<br/>[state.py]")]
  node_pipeline{{"Pipeline graph<br/>workflow engine<br/>[pipeline.py]"}}
end

subgraph group_agents["Agents"]
  node_planner["Planner<br/>decomposer<br/>[planner.py]"]
  node_orchestrator{{"Orchestrator<br/>dag builder<br/>[orchestrator.py]"}}
  node_coder["Coder pool<br/>parallel workers<br/>[coder.py]"]
  node_integrator["Integrator<br/>merge stage<br/>[integrator.py]"]
  node_reviewer["Reviewer<br/>critique stage<br/>[reviewer.py]"]
  node_tester["Tester<br/>test stage<br/>[tester.py]"]
  node_llm_utils["LLM utils<br/>api boundary<br/>[llm_utils.py]"]
  node_prompts["Prompts<br/>prompt library"]
end

subgraph group_infra["Runtime"]
  node_sandbox[("Sandbox<br/>test runtime")]
end

subgraph group_tests["Tests"]
  node_tests_models["Model tests<br/>unit tests<br/>[test_models.py]"]
  node_tests_pipeline["Pipeline tests<br/>unit tests<br/>[test_pipeline.py]"]
  node_tests_llm["LLM tests<br/>unit tests<br/>[test_llm_utils.py]"]
  node_tests_agents["Agent tests<br/>unit tests<br/>[test_agents.py]"]
  node_tests_conftest["Test fixtures<br/>[conftest.py]"]
end

node_app -->|"writes request"| node_state
node_app -->|"starts flow"| node_pipeline
node_pipeline -->|"route"| node_planner
node_planner -->|"calls LLM"| node_llm_utils
node_planner -->|"uses prompts"| node_prompts
node_planner -->|"updates plan"| node_state
node_pipeline -->|"route"| node_orchestrator
node_orchestrator -->|"builds DAG"| node_state
node_orchestrator -->|"dispatches tasks"| node_coder
node_coder -->|"calls LLM"| node_llm_utils
node_coder -->|"uses prompts"| node_prompts
node_coder -->|"emits artifacts"| node_state
node_pipeline -->|"route"| node_integrator
node_integrator -->|"merges outputs"| node_state
node_pipeline -->|"route"| node_reviewer
node_reviewer -->|"scores result"| node_state
node_pipeline -->|"route"| node_tester
node_tester -->|"runs in"| node_sandbox
node_tester -->|"records results"| node_state
node_pipeline -.->|"revise subset"| node_coder
node_tests_models -->|"verifies"| node_state
node_tests_pipeline -->|"verifies"| node_pipeline
node_tests_llm -->|"verifies"| node_llm_utils
node_tests_agents -->|"verifies"| node_planner
node_tests_agents -->|"verifies"| node_orchestrator
node_tests_agents -->|"verifies"| node_coder
node_tests_agents -->|"verifies"| node_integrator
node_tests_conftest -->|"supports"| node_tests_models
node_tests_conftest -->|"supports"| node_tests_agents

click node_app "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/app.py"
click node_state "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/models/state.py"
click node_pipeline "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/graph/pipeline.py"
click node_planner "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/planner.py"
click node_orchestrator "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/orchestrator.py"
click node_coder "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/coder.py"
click node_integrator "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/integrator.py"
click node_reviewer "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/reviewer.py"
click node_tester "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/tester.py"
click node_llm_utils "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/llm_utils.py"
click node_prompts "https://github.com/tathadn/parallel-multi-agent-codegen/tree/main/prompts"
click node_sandbox "https://github.com/tathadn/parallel-multi-agent-codegen/tree/main/sandbox/Dockerfile"
click node_tests_models "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_models.py"
click node_tests_pipeline "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_pipeline.py"
click node_tests_llm "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_llm_utils.py"
click node_tests_agents "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_agents.py"
click node_tests_conftest "https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/conftest.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_app toneBlue
class node_state,node_pipeline toneAmber
class node_planner,node_orchestrator,node_coder,node_integrator,node_reviewer,node_tester,node_llm_utils,node_prompts toneMint
class node_sandbox toneRose
class node_tests_models,node_tests_pipeline,node_tests_llm,node_tests_agents,node_tests_conftest toneIndigo
```

## Components

### UI

User-facing request submission and progress view

- [Streamlit app](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/app.py): ui entrypoint · User interface for submitting requests and viewing pipeline progress · `app.py`

### Core flow

Shared state and orchestration of the generation pipeline

- [Workflow state](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/models/state.py): typed state · Shared evolving state carrying plan, DAG, artifacts, logs, timings, and iterations · `models/state.py`
- [Pipeline graph](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/graph/pipeline.py): workflow engine · LangGraph orchestration and conditional routing between phases · `graph/pipeline.py`

### Agents

Role-specialized LLM workers and support code

- [Planner](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/planner.py): decomposer · Converts the request into a structured implementation plan · `agents/planner.py`
- [Orchestrator](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/orchestrator.py): dag builder · Transforms the plan into dependency-aware implementation tasks · `agents/orchestrator.py`
- [Coder pool](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/coder.py): parallel workers · Concurrent workers that generate code for DAG nodes or module groups · `agents/coder.py`
- [Integrator](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/integrator.py): merge stage · Reconciles parallel outputs into a coherent codebase · `agents/integrator.py`
- [Reviewer](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/reviewer.py): critique stage · Evaluates generated code and detects quality or contract issues · `agents/reviewer.py`
- [Tester](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/tester.py): test stage · Creates and runs tests against the integrated result · `agents/tester.py`
- [LLM utils](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/agents/llm_utils.py): api boundary · Shared Anthropic SDK wrapper, caching, and tracing support · `agents/llm_utils.py`
- [Prompts](https://github.com/tathadn/parallel-multi-agent-codegen/tree/main/prompts): prompt library · Role-specific prompt templates and output contracts · `prompts`

### Runtime

Execution and validation boundaries

- [Sandbox](https://github.com/tathadn/parallel-multi-agent-codegen/tree/main/sandbox/Dockerfile): test runtime · Containerized environment for isolated test execution · `sandbox/Dockerfile`

### Tests

Repository-level correctness checks

- [Model tests](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_models.py): unit tests · Checks the typed state and related models · `tests/test_models.py`
- [Pipeline tests](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_pipeline.py): unit tests · Validates orchestration and routing behavior · `tests/test_pipeline.py`
- [LLM tests](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_llm_utils.py): unit tests · Exercises JSON parsing and LLM utility behavior with mocks · `tests/test_llm_utils.py`
- [Agent tests](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/test_agents.py): unit tests · Verifies agent contracts and behaviors with mocked model calls · `tests/test_agents.py`
- [Test fixtures](https://github.com/tathadn/parallel-multi-agent-codegen/blob/main/tests/conftest.py): fixtures · Shared pytest fixtures and test setup · `tests/conftest.py`

## Connections

- Streamlit app → Workflow state: writes request · UI populates the shared workflow state
- Streamlit app → Pipeline graph: starts flow · Streamlit drives the orchestration pipeline
- Pipeline graph → Planner: route · Initial stage sends the request to planning
- Planner → LLM utils: calls LLM · Planner uses the shared model transport layer
- Planner → Prompts: uses prompts · Planner consumes role-specific prompt templates
- Planner → Workflow state: updates plan · Planner writes the structured plan into shared state
- Pipeline graph → Orchestrator: route · Planned work is transformed into a dependency graph
- Orchestrator → Workflow state: builds DAG · Orchestrator stores tasks and dependencies in state
- Orchestrator → Coder pool: dispatches tasks · Independent nodes are scheduled for concurrent generation
- Coder pool → LLM utils: calls LLM · Parallel workers use the shared LLM API boundary
- Coder pool → Prompts: uses prompts · Coder behavior is driven by role-specific templates
- Coder pool → Workflow state: emits artifacts · Generated code and metadata are accumulated in shared state
- Pipeline graph → Integrator: route · Parallel outputs are merged after generation
- Integrator → Workflow state: merges outputs · Integrator reconciles artifacts and updates state
- Pipeline graph → Reviewer: route · Integrated code is reviewed for correctness and quality
- Reviewer → Workflow state: scores result · Review findings and issues are written back to state
- Pipeline graph → Tester: route · Tests are generated or executed after review
- Tester → Sandbox: runs in · Testing happens inside an isolated container boundary
- Tester → Workflow state: records results · Test outcomes and failures are captured in state
- Pipeline graph → Coder pool: revise subset · Failed review or test outcomes can target only affected nodes for regeneration
- Model tests → Workflow state: verifies · Model tests validate the shared typed state
- Pipeline tests → Pipeline graph: verifies · Pipeline tests validate routing and orchestration logic
- LLM tests → LLM utils: verifies · LLM utility tests check parsing and transport behavior
- Agent tests → Planner: verifies · Agent tests cover role contracts and mocked execution
- Agent tests → Orchestrator: verifies · Agent tests cover decomposition and orchestration behavior
- Agent tests → Coder pool: verifies · Agent tests cover worker behavior and concurrency paths
- Agent tests → Integrator: verifies · Agent tests cover merge behavior and output reconciliation
- Test fixtures → Model tests: supports · Shared fixtures support repository tests
- Test fixtures → Agent tests: supports · Shared fixtures support mocked agent tests
