# miladsrc/ai-swe-engine architecture

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

- Interactive diagram: https://gitdiagram.com/miladsrc/ai-swe-engine
- Repository: https://github.com/miladsrc/ai-swe-engine

## Overview

SASE Engine is an offline AI-assisted software-development platform with a governed, auditable lifecycle. Humans initiate projects and make required approval decisions; agents draft requirements and specifications, then generate code and real test evidence. The orchestrator coordinates these stages through the traceability API, which enforces identity and merge gates and records artifacts. The README documents the broad workflow and capabilities; source excerpts show selected agent, API, and persistence details, so some subsystem links below reflect documented behavior rather than inspected implementations.

Main entry points: [`api/main.py`](https://github.com/miladsrc/ai-swe-engine/blob/main/api/main.py) (FastAPI application), [`api/audit.py`](https://github.com/miladsrc/ai-swe-engine/blob/main/api/audit.py) (Audit log), [`agents/orchestrator.py`](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/orchestrator.py) (Pipeline orchestrator), [`agents/coder_agent.py`](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/coder_agent.py) (Coder agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Development workflow"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
  node_product["Product agent<br/>[product_agent.py]"]
  node_spec["Spec agent<br/>[spec_agent.py]"]
  node_coder["Coder agent<br/>[coder_agent.py]"]
end

subgraph group_agents["Agent runtime"]
  node_reviewer["Reviewer agent<br/>[reviewer.py]"]
  node_verifier["Verifier<br/>[verifier.py]"]
  node_llm["LLM backends<br/>[llm.py]"]
  node_engine_client["Engine client<br/>[engine_client.py]"]
  node_verification["Evidence checks<br/>[verification.py]"]
  node_scanner["Security scanner<br/>[scanner.py]"]
end

subgraph group_governance["Traceability and governance"]
  node_api["FastAPI application<br/>[main.py]"]
  node_requirements["Project requirements<br/>[requirements.py]"]
  node_agent_runs["Agent run records<br/>[agent_runs.py]"]
  node_blueprints["Blueprints<br/>[blueprints.py]"]
  node_crp["Change requests<br/>[crp.py]"]
  node_mrp["Merge requests<br/>[mrp.py]"]
  node_vcr["Decision records<br/>[vcr.py]"]
  node_evidence["CI evidence<br/>[evidence.py]"]
  node_verification_requests["Verification requests"]
  node_traceability["Traceability views<br/>[traceability.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_review_api["Advisory review API<br/>[review.py]"]
  node_gates["Governance gates<br/>[gates.py]"]
  node_security["Identity enforcement<br/>[security.py]"]
  node_audit["Audit log<br/>[audit.py]"]
end

subgraph group_infra["Interfaces and state"]
  node_ui["Web dashboard<br/>[app.js]"]
  node_models["Artifact models<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
end

node_human(("Human"))
node_ollama["Local Ollama"]

node_human -.->|"uses"| node_ui
node_human -->|"submits decisions"| node_api
node_ui -.->|"calls"| node_api
node_orchestrator -->|"runs"| node_product
node_orchestrator -->|"runs"| node_spec
node_orchestrator -->|"runs"| node_coder
node_orchestrator -->|"spawns"| node_reviewer
node_orchestrator -->|"spawns"| node_verifier
node_product -->|"drafts with"| node_llm
node_spec -->|"generates with"| node_llm
node_coder -->|"generates with"| node_llm
node_coder -->|"scans code"| node_scanner
node_coder -->|"runs checks"| node_verification
node_llm -->|"requests inference"| node_ollama
node_product -->|"calls API"| node_engine_client
node_spec -->|"calls API"| node_engine_client
node_coder -->|"records artifacts"| node_engine_client
node_reviewer -.->|"submits review"| node_engine_client
node_verifier -->|"checks commit"| node_verification
node_engine_client -->|"sends requests"| node_api
node_api -->|"registers routes"| node_requirements
node_api -->|"registers routes"| node_agent_runs
node_api -->|"registers routes"| node_blueprints
node_api -->|"registers routes"| node_crp
node_api -->|"registers routes"| node_mrp
node_api -->|"registers routes"| node_vcr
node_api -->|"registers routes"| node_evidence
node_api -->|"registers routes"| node_verification_requests
node_api -->|"registers routes"| node_traceability
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_review_api
node_requirements -->|"enforces"| node_gates
node_mrp -->|"checks readiness"| node_gates
node_review_api -->|"requires reviewer identity"| node_security
node_auth -->|"records actions"| node_audit
node_agent_runs -->|"records actions"| node_audit
node_crp -->|"checks blockers"| node_gates
node_requirements -->|"records actions"| node_audit
node_mrp -->|"records actions"| node_audit
node_vcr -->|"records decisions"| node_audit
node_evidence -->|"records actions"| node_audit
node_verification_requests -->|"records actions"| node_audit
node_review_api -->|"records review"| node_audit
node_agent_runs -->|"persists records"| node_models
node_mrp -->|"reads and writes"| node_models
node_audit -->|"creates entries"| node_models
node_models -->|"uses ORM base"| node_database
node_api -->|"opens sessions"| node_database

click node_ui "https://github.com/miladsrc/ai-swe-engine/blob/main/static/ui/app.js"
click node_orchestrator "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/orchestrator.py"
click node_product "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/product_agent.py"
click node_spec "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/spec_agent.py"
click node_coder "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/coder_agent.py"
click node_reviewer "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/reviewer.py"
click node_verifier "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/verifier.py"
click node_llm "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/llm.py"
click node_engine_client "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/engine_client.py"
click node_verification "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/verification.py"
click node_scanner "https://github.com/miladsrc/ai-swe-engine/blob/main/agents/scanner.py"
click node_api "https://github.com/miladsrc/ai-swe-engine/blob/main/api/main.py"
click node_requirements "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/requirements.py"
click node_agent_runs "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/agent_runs.py"
click node_blueprints "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/blueprints.py"
click node_crp "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/crp.py"
click node_mrp "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/mrp.py"
click node_vcr "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/vcr.py"
click node_evidence "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/evidence.py"
click node_verification_requests "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/verification_requests.py"
click node_traceability "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/traceability.py"
click node_auth "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/auth.py"
click node_review_api "https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/review.py"
click node_gates "https://github.com/miladsrc/ai-swe-engine/blob/main/api/gates.py"
click node_security "https://github.com/miladsrc/ai-swe-engine/blob/main/api/security.py"
click node_audit "https://github.com/miladsrc/ai-swe-engine/blob/main/api/audit.py"
click node_models "https://github.com/miladsrc/ai-swe-engine/blob/main/api/models.py"
click node_database "https://github.com/miladsrc/ai-swe-engine/blob/main/api/database.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_orchestrator,node_product,node_spec,node_coder toneBlue
class node_reviewer,node_verifier,node_llm,node_engine_client,node_verification,node_scanner toneAmber
class node_api,node_requirements,node_agent_runs,node_blueprints,node_crp,node_mrp,node_vcr,node_evidence,node_verification_requests,node_traceability,node_auth,node_review_api,node_gates,node_security,node_audit toneMint
class node_ui,node_models,node_database toneRose
class node_human,node_ollama toneIndigo
```

## Components

### Development workflow

- [Pipeline orchestrator](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/orchestrator.py): `agents/orchestrator.py`
- [Product agent](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/product_agent.py): `agents/product_agent.py`
- [Spec agent](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/spec_agent.py): `agents/spec_agent.py`
- [Coder agent](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/coder_agent.py): `agents/coder_agent.py`

### Agent runtime

- [Reviewer agent](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/reviewer.py): `agents/reviewer.py`
- [Verifier](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/verifier.py): `agents/verifier.py`
- [LLM backends](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/llm.py): `agents/llm.py`
- [Engine client](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/engine_client.py): `agents/engine_client.py`
- [Evidence checks](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/verification.py): `agents/verification.py`
- [Security scanner](https://github.com/miladsrc/ai-swe-engine/blob/main/agents/scanner.py): `agents/scanner.py`

### Traceability and governance

- [FastAPI application](https://github.com/miladsrc/ai-swe-engine/blob/main/api/main.py): `api/main.py`
- [Project requirements](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/requirements.py): `api/routers/requirements.py`
- [Agent run records](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/agent_runs.py): `api/routers/agent_runs.py`
- [Blueprints](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/blueprints.py): `api/routers/blueprints.py`
- [Change requests](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/crp.py): `api/routers/crp.py`
- [Merge requests](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/mrp.py): `api/routers/mrp.py`
- [Decision records](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/vcr.py): `api/routers/vcr.py`
- [CI evidence](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/evidence.py): `api/routers/evidence.py`
- [Verification requests](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/verification_requests.py): `api/routers/verification_requests.py`
- [Traceability views](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/traceability.py): `api/routers/traceability.py`
- [Authentication](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/auth.py): `api/routers/auth.py`
- [Advisory review API](https://github.com/miladsrc/ai-swe-engine/blob/main/api/routers/review.py): `api/routers/review.py`
- [Governance gates](https://github.com/miladsrc/ai-swe-engine/blob/main/api/gates.py): `api/gates.py`
- [Identity enforcement](https://github.com/miladsrc/ai-swe-engine/blob/main/api/security.py): `api/security.py`
- [Audit log](https://github.com/miladsrc/ai-swe-engine/blob/main/api/audit.py): `api/audit.py`

### Interfaces and state

- [Web dashboard](https://github.com/miladsrc/ai-swe-engine/blob/main/static/ui/app.js): `static/ui/app.js`
- [Artifact models](https://github.com/miladsrc/ai-swe-engine/blob/main/api/models.py): `api/models.py`
- [PostgreSQL](https://github.com/miladsrc/ai-swe-engine/blob/main/api/database.py): `api/database.py`

### Other components

- **Human**
- **Local Ollama**

## Connections

- Human → Web dashboard: uses
- Human → FastAPI application: submits decisions (evidence: `README.md`)
- Web dashboard → FastAPI application: calls
- Pipeline orchestrator → Product agent: runs (evidence: `agents/orchestrator.py`)
- Pipeline orchestrator → Spec agent: runs (evidence: `agents/orchestrator.py`)
- Pipeline orchestrator → Coder agent: runs (evidence: `agents/orchestrator.py`)
- Pipeline orchestrator → Reviewer agent: spawns (evidence: `agents/orchestrator.py`)
- Pipeline orchestrator → Verifier: spawns (evidence: `agents/orchestrator.py`)
- Product agent → LLM backends: drafts with (evidence: `agents/product_agent.py`)
- Spec agent → LLM backends: generates with (evidence: `agents/spec_agent.py`)
- Coder agent → LLM backends: generates with (evidence: `agents/coder_agent.py`)
- Coder agent → Security scanner: scans code (evidence: `agents/coder_agent.py`)
- Coder agent → Evidence checks: runs checks (evidence: `README.md`)
- LLM backends → Local Ollama: requests inference (evidence: `agents/llm.py`)
- Product agent → Engine client: calls API (evidence: `agents/product_agent.py`)
- Spec agent → Engine client: calls API (evidence: `agents/spec_agent.py`)
- Coder agent → Engine client: records artifacts (evidence: `agents/coder_agent.py`)
- Reviewer agent → Engine client: submits review (evidence: `agents/reviewer.py`)
- Verifier → Evidence checks: checks commit (evidence: `agents/verifier.py`)
- Engine client → FastAPI application: sends requests (evidence: `README.md`)
- FastAPI application → Project requirements: registers routes (evidence: `api/main.py`)
- FastAPI application → Agent run records: registers routes (evidence: `api/main.py`)
- FastAPI application → Blueprints: registers routes (evidence: `api/main.py`)
- FastAPI application → Change requests: registers routes (evidence: `api/main.py`)
- FastAPI application → Merge requests: registers routes (evidence: `api/main.py`)
- FastAPI application → Decision records: registers routes (evidence: `api/main.py`)
- FastAPI application → CI evidence: registers routes (evidence: `api/main.py`)
- FastAPI application → Verification requests: registers routes (evidence: `api/main.py`)
- FastAPI application → Traceability views: registers routes (evidence: `api/main.py`)
- FastAPI application → Authentication: registers routes (evidence: `api/main.py`)
- FastAPI application → Advisory review API: registers routes (evidence: `api/main.py`)
- Project requirements → Governance gates: enforces (evidence: `api/routers/requirements.py`)
- Merge requests → Governance gates: checks readiness (evidence: `api/routers/mrp.py`)
- Advisory review API → Identity enforcement: requires reviewer identity (evidence: `api/routers/review.py`)
- Authentication → Audit log: records actions (evidence: `api/routers/auth.py`)
- Agent run records → Audit log: records actions (evidence: `api/routers/agent_runs.py`)
- Change requests → Governance gates: checks blockers (evidence: `api/routers/crp.py`)
- Project requirements → Audit log: records actions (evidence: `api/routers/requirements.py`)
- Merge requests → Audit log: records actions (evidence: `api/routers/mrp.py`)
- Decision records → Audit log: records decisions (evidence: `api/routers/vcr.py`)
- CI evidence → Audit log: records actions (evidence: `api/routers/evidence.py`)
- Verification requests → Audit log: records actions (evidence: `api/routers/verification_requests.py`)
- Advisory review API → Audit log: records review (evidence: `api/routers/review.py`)
- Agent run records → Artifact models: persists records (evidence: `api/routers/agent_runs.py`)
- Merge requests → Artifact models: reads and writes (evidence: `api/routers/mrp.py`)
- Audit log → Artifact models: creates entries (evidence: `api/audit.py`)
- Artifact models → PostgreSQL: uses ORM base (evidence: `api/models.py`)
- FastAPI application → PostgreSQL: opens sessions (evidence: `api/main.py`)