# rbkmen/qa-orchestrator architecture

> Architecture diagram of the GitHub repository rbkmen/qa-orchestrator, 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/rbkmen/qa-orchestrator
- Repository: https://github.com/rbkmen/qa-orchestrator

## Overview

QA Orchestrator is a deterministic MCP service that tracks bounded, content-free QA review sessions; the host agent retains evidence gathering, model execution, findings, and final decisions. The principal flow is host-selected triage and review routing, ordered primary-review transitions, optional risk-triggered deep review, and final synthesis/outcome recording. The server exposes tools through a service layer, which delegates workflow state to the orchestrator and loads policy, profiles, and optional persistence. README-documented host instruction templates are included. Relationships follow excerpts, the source index, or README; unsampled implementation details are not inferred.

Main entry points: [`src/qa_orchestrator/service.py`](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/service.py) (Orchestrator Service), [`src/qa_orchestrator/orchestration.py`](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/orchestration.py) (Session Workflow), [`src/qa_orchestrator/server.py`](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/server.py) (MCP Tools), [`src/qa_orchestrator/cli.py`](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/cli.py) (CLI Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_mcp_server["MCP Tools<br/>[server.py]"]
  node_service["Orchestrator Service<br/>[service.py]"]
  node_cli["CLI Setup<br/>[cli.py]"]
  node_launcher["MCP Launcher<br/>[mcp_launcher.py]"]
end

subgraph group_workflow["Review Workflow"]
  node_contracts["Workflow Contracts<br/>[contracts.py]"]
  node_orchestrator["Session Workflow<br/>[orchestration.py]"]
end

subgraph group_policy["Policy And Profiles"]
  node_config["Settings<br/>[config.py]"]
  node_model_policy["Model Policy<br/>[model_policy.py]"]
  node_profiles["Review Profiles<br/>[review_profiles.py]"]
end

subgraph group_state["Session State"]
  node_session_store[("SQLite Session Store<br/>[session_store.py]")]
end

subgraph group_host["Host Guidance"]
  node_host_rules["Host Rule Templates"]
end

node_host_agent(("Host Agent"))

node_host_agent -->|"calls tools"| node_mcp_server
node_mcp_server -->|"routes requests"| node_service
node_service -->|"delegates workflow"| node_orchestrator
node_service -->|"loads policy"| node_model_policy
node_service -->|"builds catalog"| node_profiles
node_service -->|"configures persistence"| node_session_store
node_service -->|"reads settings"| node_config
node_orchestrator -->|"persists sessions"| node_session_store
node_orchestrator -->|"uses types"| node_contracts
node_orchestrator -->|"uses selection"| node_model_policy
node_orchestrator -->|"uses profiles"| node_profiles
node_profiles -->|"defines catalog"| node_contracts
node_cli -->|"reads settings"| node_config
node_cli -->|"configures models"| node_model_policy
node_cli -->|"starts service"| node_mcp_server
node_launcher -->|"starts server"| node_mcp_server
node_host_rules -->|"guides reviews"| node_host_agent

click node_mcp_server "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/server.py"
click node_service "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/service.py"
click node_cli "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/cli.py"
click node_launcher "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/mcp_launcher.py"
click node_config "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/config.py"
click node_model_policy "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/model_policy.py"
click node_profiles "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/review_profiles.py"
click node_contracts "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/contracts.py"
click node_orchestrator "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/orchestration.py"
click node_session_store "https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/session_store.py"
click node_host_rules "https://github.com/rbkmen/qa-orchestrator/tree/main/client-rules"

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_mcp_server,node_service,node_cli,node_launcher toneBlue
class node_contracts,node_orchestrator toneAmber
class node_config,node_model_policy,node_profiles toneMint
class node_session_store toneRose
class node_host_rules,node_host_agent toneIndigo
```

## Components

### MCP Interface

- [MCP Tools](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/server.py): `src/qa_orchestrator/server.py`
- [Orchestrator Service](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/service.py): `src/qa_orchestrator/service.py`
- [CLI Setup](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/cli.py): `src/qa_orchestrator/cli.py`
- [MCP Launcher](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/mcp_launcher.py): `src/qa_orchestrator/mcp_launcher.py`

### Review Workflow

- [Workflow Contracts](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/contracts.py): `src/qa_orchestrator/contracts.py`
- [Session Workflow](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/orchestration.py): `src/qa_orchestrator/orchestration.py`

### Policy And Profiles

- [Settings](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/config.py): `src/qa_orchestrator/config.py`
- [Model Policy](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/model_policy.py): `src/qa_orchestrator/model_policy.py`
- [Review Profiles](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/review_profiles.py): `src/qa_orchestrator/review_profiles.py`

### Session State

- [SQLite Session Store](https://github.com/rbkmen/qa-orchestrator/blob/main/src/qa_orchestrator/session_store.py): `src/qa_orchestrator/session_store.py`

### Host Guidance

- [Host Rule Templates](https://github.com/rbkmen/qa-orchestrator/tree/main/client-rules): `client-rules`

### Other components

- **Host Agent**

## Connections

- Host Agent → MCP Tools: calls tools (evidence: `README.md`)
- MCP Tools → Orchestrator Service: routes requests (evidence: `src/qa_orchestrator/server.py`)
- Orchestrator Service → Session Workflow: delegates workflow (evidence: `src/qa_orchestrator/service.py`)
- Orchestrator Service → Model Policy: loads policy (evidence: `src/qa_orchestrator/service.py`)
- Orchestrator Service → Review Profiles: builds catalog (evidence: `src/qa_orchestrator/service.py`)
- Orchestrator Service → SQLite Session Store: configures persistence (evidence: `src/qa_orchestrator/service.py`)
- Orchestrator Service → Settings: reads settings (evidence: `src/qa_orchestrator/service.py`)
- Session Workflow → SQLite Session Store: persists sessions (evidence: `src/qa_orchestrator/orchestration.py`)
- Session Workflow → Workflow Contracts: uses types (evidence: `src/qa_orchestrator/orchestration.py`)
- Session Workflow → Model Policy: uses selection (evidence: `src/qa_orchestrator/orchestration.py`)
- Session Workflow → Review Profiles: uses profiles (evidence: `src/qa_orchestrator/orchestration.py`)
- Review Profiles → Workflow Contracts: defines catalog (evidence: `src/qa_orchestrator/review_profiles.py`)
- CLI Setup → Settings: reads settings (evidence: `src/qa_orchestrator/cli.py`)
- CLI Setup → Model Policy: configures models (evidence: `src/qa_orchestrator/cli.py`)
- CLI Setup → MCP Tools: starts service (evidence: `src/qa_orchestrator/cli.py`)
- MCP Launcher → MCP Tools: starts server (evidence: `src/qa_orchestrator/mcp_launcher.py`)
- Host Rule Templates → Host Agent: guides reviews (evidence: `README.md`)
