# Architecture
<!-- generated by `orchestrator understand`; the PKG is source of truth, edits here are advisory -->

**Graph size:** 13586 nodes · 37532 edges — 7229 functions · 2824 fields · 1505 docs · 1059 modules · 891 types · 71 endpoints · 7 entitys.

## Areas
The coarse components — start here, then drill into a module. An area is a module's first two path or namespace segments.

| Area | Zone | Modules | Types | Functions |
|---|---|---|---|---|
| [`orchestrator.sdlc`](areas/orchestrator.sdlc.md) | orchestrator | 47 | 117 | 361 |
| [`orchestrator.pkg`](areas/orchestrator.pkg.md) | orchestrator | 43 | 99 | 333 |
| [`orchestrator.registry`](areas/orchestrator.registry.md) | orchestrator | 50 | 94 | 170 |
| [`orchestrator.knowledge`](areas/orchestrator.knowledge.md) | orchestrator | 14 | 13 | 142 |
| [`orchestrator.intake`](areas/orchestrator.intake.md) | orchestrator | 22 | 43 | 100 |
| [`orchestrator.runtime`](areas/orchestrator.runtime.md) | orchestrator | 20 | 52 | 45 |
| [`orchestrator.cli`](areas/orchestrator.cli.md) | orchestrator | 1 | 0 | 92 |
| [`orchestrator.codereview`](areas/orchestrator.codereview.md) | orchestrator | 11 | 32 | 22 |
| [`orchestrator.core`](areas/orchestrator.core.md) | orchestrator | 14 | 29 | 24 |
| [`orchestrator.spine`](areas/orchestrator.spine.md) | orchestrator | 14 | 33 | 19 |
| [`orchestrator.plugin`](areas/orchestrator.plugin.md) | orchestrator | 4 | 3 | 41 |
| [`orchestrator.gateway`](areas/orchestrator.gateway.md) | orchestrator | 19 | 25 | 14 |
| [`orchestrator.catalog`](areas/orchestrator.catalog.md) | orchestrator | 8 | 13 | 25 |
| [`orchestrator.evals`](areas/orchestrator.evals.md) | orchestrator | 8 | 11 | 26 |
| [`orchestrator.mcp`](areas/orchestrator.mcp.md) | orchestrator | 10 | 11 | 25 |
| [`orchestrator.agentic`](areas/orchestrator.agentic.md) | orchestrator | 8 | 13 | 16 |
| [`orchestrator.launch`](areas/orchestrator.launch.md) | orchestrator | 1 | 2 | 17 |
| [`orchestrator.planner`](areas/orchestrator.planner.md) | orchestrator | 3 | 8 | 10 |
| [`orchestrator.temporal`](areas/orchestrator.temporal.md) | orchestrator | 6 | 7 | 11 |
| [`scripts.render_knowledge_foundation_svg`](areas/scripts.render_knowledge_foundation_svg.md) | scripts | 1 | 2 | 14 |
| [`orchestrator.personas`](areas/orchestrator.personas.md) | orchestrator | 5 | 5 | 10 |
| [`scripts.codegen_benchmark`](areas/scripts.codegen_benchmark.md) | scripts | 1 | 1 | 14 |
| [`migrations.versions`](areas/migrations.versions.md) | migrations | 6 | 0 | 14 |
| [`orchestrator.ir`](areas/orchestrator.ir.md) | orchestrator | 3 | 12 | 2 |
| [`orchestrator.obs`](areas/orchestrator.obs.md) | orchestrator | 2 | 2 | 11 |

## Public surface
_Split by each language's own rule — a leading underscore._

**2105 public** symbols · **1435 internal**, of 3540. Most of this codebase is machinery you don't need to read to use it.

Most-depended-upon public symbols: [`Provenance`](../src/orchestrator/pkg/facts.py#L81), [`Edge`](../src/orchestrator/pkg/facts.py#L137), [`Node`](../src/orchestrator/pkg/facts.py#L121), [`LLMCodegenAdapter`](../src/orchestrator/sdlc/codegen.py#L826), [`TargetLayout`](../src/orchestrator/sdlc/layout.py#L79), [`FactBatch`](../src/orchestrator/pkg/facts.py#L150), [`load_local_env`](../src/orchestrator/core/env.py#L20), [`RepoCodeExtractor`](../src/orchestrator/pkg/extractor.py#L577), [`RunContext`](../src/orchestrator/sdlc/autorun.py#L65), [`TestRunResult`](../src/orchestrator/sdlc/testrunner.py#L78), [`FactStore`](../src/orchestrator/pkg/store.py#L25), [`CodegenError`](../src/orchestrator/sdlc/codegen.py#L283), [`CurrentState`](../src/orchestrator/knowledge/current_state.py#L118), [`AuditLogRepo`](../src/orchestrator/registry/repositories.py#L161), [`GroundingVerifier`](../src/orchestrator/pkg/verifier.py#L42), +2090 more

## Import cycles
_Groups of modules that depend on each other, directly or through a chain. Each is a place the layering doesn't hold — and a hazard for import order._

- 7 modules: `orchestrator.pkg.c_extractor` ↔ `orchestrator.pkg.cpp_extractor` ↔ `orchestrator.pkg.csharp_extractor` ↔ `orchestrator.pkg.extractor` ↔ `orchestrator.pkg.java_extractor` ↔ `orchestrator.pkg.sql_extractor`, +1 more
- 4 modules: `orchestrator.knowledge.analysis` ↔ `orchestrator.knowledge.current_state` ↔ `orchestrator.knowledge.insights` ↔ `orchestrator.knowledge.renderers`
- 2 modules: `orchestrator.agentic.codegen_tools` ↔ `orchestrator.sdlc.codegen`

## System architecture
The top components grouped by zone; arrows run in the direction of the dependency, weighted by how many imports back them.

```mermaid
flowchart LR
  subgraph c_1["sdlc · pkg (10)"]
    aorchestratoragentic["orchestrator.agentic<br/>13 types · 46 fns"]
    aorchestratorcli["orchestrator.cli<br/>0 types · 97 fns"]
    aorchestratorcodereview["orchestrator.codereview<br/>32 types · 79 fns"]
    aorchestratorcore["orchestrator.core<br/>29 types · 57 fns"]
    aorchestratorintake["orchestrator.intake<br/>43 types · 206 fns"]
    aorchestratorknowledge["orchestrator.knowledge<br/>13 types · 174 fns"]
    aorchestratorpkg["orchestrator.pkg<br/>99 types · 575 fns"]
    aorchestratorplugin["orchestrator.plugin<br/>3 types · 55 fns"]
    aorchestratorsdlc["orchestrator.sdlc<br/>117 types · 658 fns"]
    ascriptscodegenbenchmark["scripts.codegen_benchmark<br/>1 types · 14 fns"]
  end
  subgraph c_3["registry · runtime (4)"]
    aorchestratorcatalog["orchestrator.catalog<br/>13 types · 37 fns"]
    aorchestratorgateway["orchestrator.gateway<br/>25 types · 56 fns"]
    aorchestratorregistry["orchestrator.registry<br/>94 types · 223 fns"]
    aorchestratorruntime["orchestrator.runtime<br/>52 types · 127 fns"]
  end
  subgraph c_5["evals (1)"]
    aorchestratorevals["orchestrator.evals<br/>11 types · 53 fns"]
  end
  subgraph c_7["ir · planner (2)"]
    aorchestratorir["orchestrator.ir<br/>12 types · 23 fns"]
    aorchestratorplanner["orchestrator.planner<br/>8 types · 21 fns"]
  end
  subgraph c_10["spine (1)"]
    aorchestratorspine["orchestrator.spine<br/>33 types · 87 fns"]
  end
  aorchestratorcli -->|63| aorchestratorsdlc
  aorchestratorcli -->|54| aorchestratorpkg
  aorchestratorsdlc -->|49| aorchestratorpkg
  aorchestratorcli -->|36| aorchestratorintake
  aorchestratorknowledge -->|34| aorchestratorpkg
  aorchestratorplugin -->|30| aorchestratorsdlc
  aorchestratorsdlc -->|28| aorchestratorintake
  aorchestratorsdlc -->|26| aorchestratorcore
  aorchestratorcli -->|22| aorchestratorcore
  aorchestratorplanner -->|14| aorchestratorir
  aorchestratorsdlc -->|14| aorchestratorcodereview
  aorchestratorplugin -->|13| aorchestratorpkg
  aorchestratorruntime -->|12| aorchestratorregistry
  ascriptscodegenbenchmark -->|11| aorchestratorsdlc
```

### Strongest component dependencies

| From | → | To | Strength |
|---|---|---|---|
| `tests.sdlc` | → | `orchestrator.sdlc` | 445 |
| `tests.pkg` | → | `orchestrator.pkg` | 257 |
| `tests.intake` | → | `orchestrator.intake` | 148 |
| `tests.registry` | → | `orchestrator.registry` | 119 |
| `tests.sdlc` | → | `orchestrator.pkg` | 82 |
| `tests.knowledge` | → | `orchestrator.knowledge` | 77 |
| `orchestrator.cli` | → | `orchestrator.sdlc` | 63 |
| `tests.runtime` | → | `orchestrator.runtime` | 55 |
| `orchestrator.cli` | → | `orchestrator.pkg` | 54 |
| `tests.integration` | → | `orchestrator.registry` | 54 |

## Layers
Types bucketed by role, inferred from naming conventions — a rough shape of the codebase, not a declared architecture.

| Layer | Types |
|---|---|
| Other | 804 |
| Data shapes (VM/DTO/model) | 44 |
| Business logic | 27 |
| Data access | 6 |
| Interfaces / contracts | 3 |
| App wiring / infra | 1 |

## Complexity
_How big the types are, and which are biggest._

Size distribution: **768** 1-10 · **61** >10 · **50** marker · **5** >25 · **1** god (>40)

| Largest type | Members | Defined at |
|---|---|---|
| `LLMCodegenAdapter` | 53 | `src/orchestrator/sdlc/codegen.py:826` |
| `CurrentState` | 36 | `src/orchestrator/knowledge/current_state.py:118` |
| `RunContext` | 33 | `src/orchestrator/sdlc/autorun.py:65` |
| `SDLCActivities` | 30 | `src/orchestrator/sdlc/activities.py:44` |
| `PythonExtractor` | 26 | `src/orchestrator/pkg/extractor.py:151` |
| `FactStore` | 26 | `src/orchestrator/pkg/store.py:25` |
| `ApprovalRequestRow` | 22 | `src/orchestrator/registry/db/models.py:127` |
| `LineageIndex` | 22 | `src/orchestrator/spine/lineage.py:95` |
| `AgentLoop` | 21 | `src/orchestrator/agentic/loop.py:197` |
| `ApprovalRequest` | 21 | `src/orchestrator/approval/models.py:71` |

## Test coverage
_Which components the test suite reaches, by test→source imports. Presence, not line coverage._

**28 of 48 components** are imported by at least one test.

Largest components no test imports: `scripts.render_knowledge_foundation_svg` (2 types), `scripts.codegen_benchmark` (1 type), `scripts.render_architecture_svg` (1 type).

## Documentation
_The repo's own prose folded into the graph (`Doc` nodes + `MENTIONS` edges). A mention counts only when it binds to exactly one symbol, so this under-counts rather than guesses._

**1505 docs** ingested, naming **636 of 8559 symbols** (7% doc coverage).

**872 potential drift** — the docs name code the graph doesn't have (renamed or removed symbols, or prose the binder can't resolve).

| The docs claim… | …in |
|---|---|
| `profile_select` | CHANGELOG.md |
| `Bug` | CHANGELOG.md |
| `rule_compiler` | CHANGELOG.md |
| `n_rca` | CHANGELOG.md |
| `n_churn` | CHANGELOG.md |
| `repo_path` | CHANGELOG.md |
| `multi_repo_available` | CHANGELOG.md |
| `create_order` | CHANGELOG.md |
| … | _+864 more_ |

## Possibly unused
_**146 of 1265 internal symbols** have no caller, subclass or doc reference in the graph. **Candidates, not verdicts**: calls through an attribute chain are skipped rather than guessed at, and dynamic dispatch, registries and reflection are invisible. Public symbols are excluded — having no in-repo caller is what being an API looks like._

[`Status`](../src/orchestrator/registry/_common.py#L42), [`_CFamily`](../src/orchestrator/pkg/scope.py#L410), [`_CSharp`](../src/orchestrator/pkg/scope.py#L318), [`_Choice`](../src/orchestrator/planner/v0.py#L42), [`_Go`](../src/orchestrator/pkg/scope.py#L287), [`_InferredGlossaryEntry`](../src/orchestrator/planner/v1.py#L53), [`_Lang`](../src/orchestrator/pkg/scope.py#L121), [`_ManagerSpecialistChoice`](../src/orchestrator/planner/v1.py#L47), [`_Plan`](../src/orchestrator/planner/v1.py#L60), [`_State`](../src/orchestrator/obs/tracing.py#L40), [`_StepChoice`](../src/orchestrator/planner/v1.py#L40), [`_TypeScript`](../src/orchestrator/pkg/scope.py#L239), [`_Wrapped`](../src/orchestrator/gateway/handlers.py#L62), [`_add`](../src/orchestrator/pkg/docs.py#L108), [`_add`](../src/orchestrator/pkg/media_extract.py#L224), [`_api_surface`](../src/orchestrator/agentic/tools.py#L34), [`_approval_points_reference_known_nodes`](../src/orchestrator/ir/graph.py#L145), [`_audit`](../src/orchestrator/codereview/webhook.py#L197), [`_audit_is_mandatory`](../src/orchestrator/registry/tool_contract.py#L73), [`_blast_radius`](../src/orchestrator/agentic/tools.py#L49), +126 more

## Module map (top 25 by members)
The biggest first-party modules — where the code lives. Tests are excluded; each opens its page (or its source, if it has no page).

- [`orchestrator.cli`](modules/orchestrator.cli.md) — 0 types, 92 functions
- [`orchestrator.knowledge.renderers`](modules/orchestrator.knowledge.renderers.md) — 4 types, 52 functions
- [`orchestrator.plugin.server`](modules/orchestrator.plugin.server.md) — 1 types, 37 functions
- [`orchestrator.sdlc.codegen`](modules/orchestrator.sdlc.codegen.md) — 8 types, 30 functions
- [`orchestrator.sdlc.layout`](modules/orchestrator.sdlc.layout.md) — 1 types, 35 functions
- [`orchestrator.sdlc.builddoc`](modules/orchestrator.sdlc.builddoc.md) — 3 types, 31 functions
- [`orchestrator.sdlc.testenv`](modules/orchestrator.sdlc.testenv.md) — 9 types, 22 functions
- [`orchestrator.pkg.csharp_extractor`](modules/orchestrator.pkg.csharp_extractor.md) — 2 types, 26 functions
- [`orchestrator.knowledge.current_state`](modules/orchestrator.knowledge.current_state.md) — 1 types, 26 functions
- [`orchestrator.pkg.accuracy`](modules/orchestrator.pkg.accuracy.md) — 6 types, 17 functions
- [`orchestrator.sdlc.autorun`](modules/orchestrator.sdlc.autorun.md) — 3 types, 20 functions
- [`orchestrator.sdlc.feature_runner`](modules/orchestrator.sdlc.feature_runner.md) — 2 types, 21 functions
- [`orchestrator.registry.api.capabilities`](modules/orchestrator.registry.api.capabilities.md) — 11 types, 11 functions
- [`orchestrator.knowledge.report_html`](modules/orchestrator.knowledge.report_html.md) — 0 types, 20 functions
- [`orchestrator.launch`](modules/orchestrator.launch.md) — 2 types, 17 functions
- [`orchestrator.pkg.c_extractor`](modules/orchestrator.pkg.c_extractor.md) — 1 types, 18 functions
- [`orchestrator.pkg.persistence`](modules/orchestrator.pkg.persistence.md) — 3 types, 16 functions
- [`orchestrator.pkg.scope`](modules/orchestrator.pkg.scope.md) — 10 types, 9 functions
- [`orchestrator.sdlc.testrunner`](modules/orchestrator.sdlc.testrunner.md) — 12 types, 6 functions
- [`orchestrator.pkg.doc_source`](modules/orchestrator.pkg.doc_source.md) — 2 types, 15 functions
- [`orchestrator.pkg.typescript_extractor`](modules/orchestrator.pkg.typescript_extractor.md) — 1 types, 16 functions
- [`orchestrator.pkg.verify`](modules/orchestrator.pkg.verify.md) — 3 types, 14 functions
- [`orchestrator.sdlc.evidence`](modules/orchestrator.sdlc.evidence.md) — 2 types, 15 functions
- [`orchestrator.sdlc.validity`](modules/orchestrator.sdlc.validity.md) — 3 types, 14 functions
- [`orchestrator.pkg.java_extractor`](modules/orchestrator.pkg.java_extractor.md) — 2 types, 14 functions

_Showing the 25 biggest of 319 first-party modules._

## Call hotspots (most-called functions)
The most-depended-on functions: what breaks the most if you change it. Each links to its definition and to its direct callers; **reaches** is the transitive blast radius — every symbol a change here can touch.

- [`_print`](../src/orchestrator/cli.py#L79) — 31 production call-sites · **reaches 44 symbols** (≤2 hops)
  - called by [`_deprecate`](../src/orchestrator/cli.py#L173), [`_invention_oracle`](../src/orchestrator/cli.py#L3205), [`_joins_check`](../src/orchestrator/cli.py#L2958), [`_joins_propose`](../src/orchestrator/cli.py#L2930), [`_list`](../src/orchestrator/cli.py#L152), +23 more
- [`load_local_env`](../src/orchestrator/core/env.py#L20) — 30 production · 6 test call-sites · **reaches 155 symbols** (≤4 hops)
  - called by [`_go`](../src/orchestrator/cli.py#L1210), [`_lifespan`](../src/orchestrator/intake/web/app.py#L127), [`_main`](../scripts/intents_to_confluence.py#L102), [`_main`](../scripts/live_github_auth.py#L21), [`_main`](../scripts/live_review.py#L32), +30 more
- [`_e`](../src/orchestrator/knowledge/report_html.py#L44) — 26 production call-sites · **reaches 33 symbols** (≤3 hops)
  - called by [`_activity_section`](../src/orchestrator/knowledge/report_html.py#L327), [`_architecture_section`](../src/orchestrator/knowledge/report_html.py#L100), [`_blast_coverage`](../src/orchestrator/knowledge/report_html.py#L220), [`_blast_radius_section`](../src/orchestrator/knowledge/report_html.py#L166), [`_coverage_section`](../src/orchestrator/knowledge/report_html.py#L257), +10 more
- [`_audit`](../src/orchestrator/sdlc/workflows.py#L911) — 21 production call-sites · **reaches 1 symbols** (≤1 hop)
  - called by [`run`](../src/orchestrator/sdlc/workflows.py#L516)
- [`_text`](../src/orchestrator/pkg/c_extractor.py#L491) — 19 production call-sites · **reaches 33 symbols** (≤3 hops)
  - called by [`_calls`](../src/orchestrator/pkg/cpp_extractor.py#L287), [`_calls_in`](../src/orchestrator/pkg/c_extractor.py#L392), [`_declarator_name`](../src/orchestrator/pkg/c_extractor.py#L418), [`_declared_name`](../src/orchestrator/pkg/cpp_extractor.py#L364), [`_declared_names`](../src/orchestrator/pkg/c_extractor.py#L432), +11 more
- [`_doc`](../src/orchestrator/knowledge/renderers.py#L114) — 17 production call-sites · **reaches 98 symbols** (≤4 hops)
  - called by [`_core_types_page`](../src/orchestrator/knowledge/renderers.py#L1050), [`render_api_surface`](../src/orchestrator/knowledge/renderers.py#L1681), [`render_architecture`](../src/orchestrator/knowledge/renderers.py#L1256), [`render_area_page`](../src/orchestrator/knowledge/renderers.py#L837), [`render_conventions`](../src/orchestrator/knowledge/renderers.py#L1541), +8 more
- [`_link`](../src/orchestrator/knowledge/renderers.py#L179) — 17 production call-sites · **reaches 101 symbols** (≤4 hops)
  - called by [`_api_split_block`](../src/orchestrator/knowledge/renderers.py#L1119), [`_caller_line`](../src/orchestrator/knowledge/renderers.py#L198), [`_core_types_page`](../src/orchestrator/knowledge/renderers.py#L1050), [`_dead_code_block`](../src/orchestrator/knowledge/renderers.py#L1193), [`_map_link`](../src/orchestrator/knowledge/renderers.py#L1312), +11 more
- [`page_shell`](../src/orchestrator/registry/api/web/shell.py#L84) — 16 production · 3 test call-sites · **reaches 62 symbols** (≤3 hops)
  - called by [`_html_page`](../src/orchestrator/registry/api/trace.py#L228), [`_page`](../src/orchestrator/registry/api/web/intelligence.py#L50), [`advanced_page`](../src/orchestrator/registry/api/web/advanced.py#L22), [`audit_page`](../src/orchestrator/registry/api/web/governance.py#L21), [`backlog_page`](../src/orchestrator/registry/api/backlog.py#L43), +14 more
- [`_repo_arg`](../src/orchestrator/cli.py#L105) — 15 production · 1 test call-sites · **reaches 14 symbols** (≤1 hop)
  - called by [`catalog_plan`](../src/orchestrator/cli.py#L2755), [`design`](../src/orchestrator/cli.py#L2306), [`investigate`](../src/orchestrator/cli.py#L2417), [`localize`](../src/orchestrator/cli.py#L2524), [`pkg_docs`](../src/orchestrator/cli.py#L3620), +9 more
- [`_under_tests`](../src/orchestrator/knowledge/renderers.py#L173) — 15 production · 1 test call-sites · **reaches 100 symbols** (≤4 hops)
  - called by [`__init__`](../src/orchestrator/knowledge/renderers.py#L232), [`_caller_line`](../src/orchestrator/knowledge/renderers.py#L198), [`_core_types_page`](../src/orchestrator/knowledge/renderers.py#L1050), [`_error_idiom_block`](../src/orchestrator/knowledge/renderers.py#L1503), [`_naming_block`](../src/orchestrator/knowledge/renderers.py#L1439), +8 more
