# ruslanmv/agent-generator architecture

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

- Interactive diagram: https://gitdiagram.com/ruslanmv/agent-generator
- Repository: https://github.com/ruslanmv/agent-generator

## Overview

agent-generator combines deterministic multi-agent project generation with the Matrix Builder contract engine. The primary workflow turns an idea into a plan/spec, renders a framework-specific project, and validates the result. The second major workflow creates a locked blueprint and scoped batches, then validates coder changes and produces repair guidance or versioned commits. The repository also exposes these capabilities through SDK, CLI, HTTP, web, and demo surfaces. Some subsystem links are documented rather than verified from sampled implementation; those use README evidence.

Main entry points: [`src/agent_generator/engine.py`](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/engine.py) (AgentGenerator engine), [`src/agent_generator/control`](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/control) (Contract enforcement), [`src/agent_generator/domain/project_spec.py`](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/domain/project_spec.py) (Project specification), [`backend/app/main.py`](https://github.com/ruslanmv/agent-generator/blob/master/backend/app/main.py) (Wizard service API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Project Generation"]
  node_plan["Idea planning"]
  node_project_spec["Project specification<br/>[project_spec.py]"]
  node_frameworks["Framework generators"]
  node_generated_project["Generated project"]
end

subgraph group_matrix["Matrix Builder Engine"]
  node_matrix_engine["AgentGenerator engine<br/>[engine.py]"]
  node_blueprints["Blueprint design"]
  node_blueprint_contract["Blueprint contract<br/>[blueprint.py]"]
  node_batch_contract["Batch contract<br/>[batch.py]"]
  node_version_contract["Version contract<br/>[versioning.py]"]
  node_coder_changes["Coder changes"]
  node_control["Contract enforcement"]
  node_repair["Repair guidance<br/>[repair.py]"]
end

subgraph group_validation["Validation and Release"]
  node_project_validation["Project validation<br/>[pipeline.py]"]
  node_validation_contract["Validation results<br/>[validation.py]"]
  node_artifacts["Release bundles"]
  node_standards[("Signed standards")]
end

subgraph group_interfaces["Service Interfaces"]
  node_cli["CLI and mb<br/>[cli.py]"]
  node_http_api["Matrix HTTP API<br/>[app.py]"]
  node_backend_api["Wizard service API<br/>[main.py]"]
  node_project_store[("Application database<br/>[session.py]")]
  node_demo_service["Hosted demo API<br/>[main.py]"]
end

subgraph group_experience["Builder Experience"]
  node_frontend["Builder interface<br/>[App.tsx]"]
  node_pipeline_editor["Pipeline editor<br/>[Pipeline.tsx]"]
  node_pipeline_loader["Project pipeline loader<br/>[usePipeline.ts]"]
end

node_user(("Idea author"))
node_coder(("AI coder"))

node_user -->|"describes idea"| node_plan
node_plan -->|"builds spec"| node_project_spec
node_project_spec -->|"renders project"| node_frameworks
node_frameworks -->|"writes files"| node_generated_project
node_project_spec -->|"validates spec"| node_project_validation
node_generated_project -->|"validates files"| node_project_validation
node_user -->|"submits idea"| node_matrix_engine
node_matrix_engine -->|"generates candidates"| node_blueprints
node_blueprints -->|"forms blueprint"| node_blueprint_contract
node_matrix_engine -->|"plans batches"| node_batch_contract
node_blueprint_contract -->|"bounds work"| node_coder
node_coder -->|"produces changes"| node_coder_changes
node_coder_changes -->|"submits patch"| node_control
node_control -->|"validates patch"| node_validation_contract
node_control -->|"requests repair"| node_repair
node_control -->|"records commit"| node_version_contract
node_matrix_engine -->|"exports bundle"| node_artifacts
node_artifacts -->|"locks standards"| node_standards
node_cli -->|"invokes engine"| node_matrix_engine
node_http_api -->|"calls SDK"| node_matrix_engine
node_backend_api -->|"initializes database"| node_project_store
node_backend_api -.->|"serves wizard APIs"| node_frontend
node_frontend -.->|"opens editor"| node_pipeline_editor
node_pipeline_editor -->|"loads project graph"| node_pipeline_loader
node_pipeline_loader -.->|"fetches project"| node_backend_api
node_demo_service -->|"serves demo SPA"| node_frontend

click node_plan "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/application/planning_service.py"
click node_project_spec "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/domain/project_spec.py"
click node_frameworks "https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/frameworks"
click node_project_validation "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/validators/pipeline.py"
click node_matrix_engine "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/engine.py"
click node_blueprints "https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/blueprints"
click node_blueprint_contract "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/blueprint.py"
click node_batch_contract "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/batch.py"
click node_version_contract "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/versioning.py"
click node_control "https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/control"
click node_validation_contract "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/validation.py"
click node_repair "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/control/repair.py"
click node_artifacts "https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/artifacts"
click node_standards "https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/standards"
click node_cli "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/cli.py"
click node_http_api "https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/http/app.py"
click node_backend_api "https://github.com/ruslanmv/agent-generator/blob/master/backend/app/main.py"
click node_frontend "https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/App.tsx"
click node_pipeline_editor "https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/pages/Pipeline.tsx"
click node_pipeline_loader "https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/pages/pipeline/usePipeline.ts"
click node_project_store "https://github.com/ruslanmv/agent-generator/blob/master/backend/app/db/session.py"
click node_demo_service "https://github.com/ruslanmv/agent-generator/blob/master/hf/space_app/main.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_plan,node_project_spec,node_frameworks,node_generated_project toneBlue
class node_matrix_engine,node_blueprints,node_blueprint_contract,node_batch_contract,node_version_contract,node_coder_changes,node_control,node_repair toneAmber
class node_project_validation,node_validation_contract,node_artifacts,node_standards toneMint
class node_cli,node_http_api,node_backend_api,node_project_store,node_demo_service toneRose
class node_frontend,node_pipeline_editor,node_pipeline_loader,node_user,node_coder toneIndigo
```

## Components

### Project Generation

- [Idea planning](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/application/planning_service.py): `src/agent_generator/application/planning_service.py`
- [Project specification](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/domain/project_spec.py): `src/agent_generator/domain/project_spec.py`
- [Framework generators](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/frameworks): `src/agent_generator/frameworks`
- **Generated project**

### Matrix Builder Engine

- [AgentGenerator engine](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/engine.py): `src/agent_generator/engine.py`
- [Blueprint design](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/blueprints): `src/agent_generator/blueprints`
- [Blueprint contract](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/blueprint.py): `src/agent_generator/contracts/blueprint.py`
- [Batch contract](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/batch.py): `src/agent_generator/contracts/batch.py`
- [Version contract](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/versioning.py): `src/agent_generator/contracts/versioning.py`
- **Coder changes**
- [Contract enforcement](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/control): `src/agent_generator/control`
- [Repair guidance](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/control/repair.py): `src/agent_generator/control/repair.py`

### Validation and Release

- [Project validation](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/validators/pipeline.py): `src/agent_generator/validators/pipeline.py`
- [Validation results](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/contracts/validation.py): `src/agent_generator/contracts/validation.py`
- [Release bundles](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/artifacts): `src/agent_generator/artifacts`
- [Signed standards](https://github.com/ruslanmv/agent-generator/tree/master/src/agent_generator/standards): `src/agent_generator/standards`

### Service Interfaces

- [CLI and mb](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/cli.py): `src/agent_generator/cli.py`
- [Matrix HTTP API](https://github.com/ruslanmv/agent-generator/blob/master/src/agent_generator/http/app.py): `src/agent_generator/http/app.py`
- [Wizard service API](https://github.com/ruslanmv/agent-generator/blob/master/backend/app/main.py): `backend/app/main.py`
- [Application database](https://github.com/ruslanmv/agent-generator/blob/master/backend/app/db/session.py): `backend/app/db/session.py`
- [Hosted demo API](https://github.com/ruslanmv/agent-generator/blob/master/hf/space_app/main.py): `hf/space_app/main.py`

### Builder Experience

- [Builder interface](https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Pipeline editor](https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/pages/Pipeline.tsx): `frontend/src/pages/Pipeline.tsx`
- [Project pipeline loader](https://github.com/ruslanmv/agent-generator/blob/master/frontend/src/pages/pipeline/usePipeline.ts): `frontend/src/pages/pipeline/usePipeline.ts`

### Other components

- **Idea author**
- **AI coder**

## Connections

- Idea author → Idea planning: describes idea
- Idea planning → Project specification: builds spec (evidence: `src/agent_generator/application/planning_service.py`)
- Project specification → Framework generators: renders project
- Framework generators → Generated project: writes files
- Project specification → Project validation: validates spec (evidence: `src/agent_generator/validators/pipeline.py`)
- Generated project → Project validation: validates files (evidence: `src/agent_generator/validators/pipeline.py`)
- Idea author → AgentGenerator engine: submits idea
- AgentGenerator engine → Blueprint design: generates candidates (evidence: `src/agent_generator/engine.py`)
- Blueprint design → Blueprint contract: forms blueprint
- AgentGenerator engine → Batch contract: plans batches (evidence: `src/agent_generator/engine.py`)
- Blueprint contract → AI coder: bounds work
- AI coder → Coder changes: produces changes
- Coder changes → Contract enforcement: submits patch
- Contract enforcement → Validation results: validates patch
- Contract enforcement → Repair guidance: requests repair (evidence: `src/agent_generator/control/__init__.py`)
- Contract enforcement → Version contract: records commit
- AgentGenerator engine → Release bundles: exports bundle (evidence: `src/agent_generator/engine.py`)
- Release bundles → Signed standards: locks standards
- CLI and mb → AgentGenerator engine: invokes engine
- Matrix HTTP API → AgentGenerator engine: calls SDK (evidence: `src/agent_generator/http/app.py`)
- Wizard service API → Application database: initializes database (evidence: `backend/app/main.py`)
- Wizard service API → Builder interface: serves wizard APIs (evidence: `backend/app/main.py`)
- Builder interface → Pipeline editor: opens editor
- Pipeline editor → Project pipeline loader: loads project graph (evidence: `frontend/src/pages/Pipeline.tsx`)
- Project pipeline loader → Wizard service API: fetches project (evidence: `frontend/src/pages/pipeline/usePipeline.ts`)
- Hosted demo API → Builder interface: serves demo SPA (evidence: `hf/space_app/main.py`)
