Orchestrata Ultimate / Architecture

Orchestrata-Ultimate Architecture

Orchestrata is a single Python package, orchestrata_ultimate, ported from the former 26-package orchestrata monorepo and organized as a modular monolith. It runs on free-threaded Python 3.14 with uv. The same code is now being re-cut into ten component packages under packages/, which has not cut over (component DAG). This page is the architecture in one place; Orchestrata, explained walks a request through it, and the architecture diagram is the full-size picture.

Sources, all read on 2026-10-23: architecture-standards.md and docs/CODEBASE_MAP.md in the worktree wt-MAP-PRECOMMIT (8a2cb42ad), the generated code reference, the component DAG and the runtime services page.

The six layers

The single rule is down only: a module may import orchestrata_ultimate code from its own layer or a lower one, never a higher one. Same-layer concrete imports between Layer-3 domain services are not allowed; they talk through Layer-0 protocols injected by the DI container or through Layer 4. The table mirrors LAYER_ASSIGNMENTS in scripts/architecture_checker.py, the source of truth, which validates import rules, module boundaries and layering; scripts/architecture_static_check.py is its static import-graph complement.

Module counts are from the code reference at 8a2cb42ad; core (92 modules) spans Layers 0 and 1.

The packages

src/orchestrata_ultimate/ holds 30 packages (docs/CODEBASE_MAP.md). Twelve are not in the layer table above: context (11 modules), domaingen (7), factory (74), gates (5), harness (20), integrations (4), openspec (7), planning (2), promotion (23), refactor (50), semantic_graph (20) and tools (20). Their layer was not measured for this page. Two sibling roots sit beside the package: src/orchestrata_ast (7 modules, the AST analyzer used by the graph sync) and src/orchestrata_tools (60 modules). The hub's code reference table gives each package a one-line description and links its reference and curated pages.

Two packages are easy to conflate. knowledge_graph talks to the operational KG, the orchkg database: sessions, audit, code intelligence, specs, requirements and traces. semantic_graph talks to the semantic / RAG database, memgraph: embeddings, chunks and GraphRAG (semantic graph). Both databases live on the same orchgraph cluster.

The runtime pieces

Underneath: Redis (one per fleet) for queues, event streams, ring buffers, hot memory and the conversation queue; the orchgraph Memgraph-fork HA cluster with its orchkg and memgraph databases; and SWI-Prolog, embedded in the kernel through the free-threaded janus-swi fork, with no Prolog service of its own (ADR-0110). On the prod host the kernel and gateway are systemd user units run from /opt/orchestrata; in the test fleet they run in the app container. See runtime services for every unit.

The component DAG (packages refactor)

ADR-0112, ADR-0113, ADR-0114 and ADR-0115 rule the ten components and their 30 dependency edges (component DAG). plugin is a packaging track, not a lifted component, and integration (import name orchestrata) is the composed release. Arrows point from a component to what it depends on.

tools deliberately has no edge to kernel: it reaches Redis and embeddings through contracts protocols (ADR-0112). The cut-over, its INT increments and its open questions are in Orchestrata, explained §10.

AST statistics

At 8a2cb42ad the code reference counts 902 modules and 242,957 lines in orchestrata_ultimate, 1,790 modules in the eight lifted component packages, and 3,508 classes and 6,162 functions across everything it covers (code reference). The table below is the earlier measurement from plans/ast-ultimate.json, kept for comparison.

Earlier measurement (2026-07-22, plans/ast-ultimate.json)

Package dependency graph (2026-07-22)

Edge labels are import counts. The heaviest edges confirm the layering: agents → core (82), cxp → core (34), gateway → core (32) — plus session → core (62), kernel → core (54), orchestrator → core (53), verification → core (46).

Source diagrams: docs/diagrams/architecture-packages.mmd in the repo.

Persistence layer (D12) — as of 2026-07-08

All Neo4j/Redis client construction goes through core/neo4j_factory.py and core/redis_factory.py (see ADR-010 on the decisions page); a blocking architecture_checker rule prevents regressions. Memgraph connections use the NO_AUTH sentinel (ADR-011).

Since the 2026-07-26 cut-over the graph those clients reach is the orchgraph cluster (KG_ENGINE=memgraph, KG_DATABASE=orchkg in all three env/*.env profiles), while the factory module keeps its Neo4j-era name. The Bolt protocol is shared, which is why the prod routing URI is neo4j://10.53.1.160:7691 (KG migration).

Related

• Orchestrata, explained
• Architecture diagram
• Component DAG
• Runtime services
• Architecture ontology
• AST diagram: package dependencies
• Code reference
• Project hub