<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/diagrams/">
  <id>https://docs.spec-kitty.ai/architecture/diagrams/</id>
  <title>Architecture Diagrams (living C4)</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/diagrams/"/>
  <summary>The living C4 model for the current architecture, carried forward from the 2.x snapshot and refreshed in place against the ratified domain model.</summary>
  <content type="html">&lt;span id=&quot;architecture-diagrams-living-c4&quot;&gt;&lt;/span&gt;
&lt;p&gt;This directory holds the &lt;strong&gt;living C4 model&lt;/strong&gt; for the &lt;strong&gt;current architecture&lt;/strong&gt;.
It is not era-stamped: it was carried forward from the 2.x snapshot and is refreshed
in place against the ratified domain model. It is one of the living surfaces
described in &lt;a href=&quot;/architecture/&quot;&gt;architecture index&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The numbered C4 levels are kept stable so navigation and tooling stay predictable:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Level&lt;/th&gt;&lt;th&gt;Directory&lt;/th&gt;&lt;th&gt;Scope&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;C4 L1 — Context&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/architecture/diagrams/01_context/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;01_context/&lt;/code&gt;&lt;/a&gt;&lt;/td&gt;&lt;td&gt;System boundary, actors, external interactions&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;C4 L2 — Containers&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/architecture/diagrams/02_containers/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;02_containers/&lt;/code&gt;&lt;/a&gt;&lt;/td&gt;&lt;td&gt;The four bounded modules + the Op execution tier&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;C4 L3 — Components&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/architecture/diagrams/03_components/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;03_components/&lt;/code&gt;&lt;/a&gt;&lt;/td&gt;&lt;td&gt;Component-level behavior sequences&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;the-domain-model-these-diagrams-depict&quot;&gt;The domain model these diagrams depict&lt;/h2&gt;
&lt;p&gt;The model is the &lt;strong&gt;four bounded modules&lt;/strong&gt; ratified in
&lt;a href=&quot;/adr/3.x/2026-06-03-1-execution-state-domain-model/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-03-1-execution-state-domain-model.md&lt;/code&gt;&lt;/a&gt;:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Domain responsibility&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Governance&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Charter and Doctrine artifacts — what the project is allowed to do and how&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Mission Management&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Mission lifecycle, WP status/kanban, status events, planning artifacts&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Execution / Runtime&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Workspace resolution, branch state, mission-run lifecycle, CWD-invariant context&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Shared Kernel&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Value types, identifiers, and utilities shared across modules — no domain logic&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Modules communicate via &lt;strong&gt;Open Host Service (OHS) facades&lt;/strong&gt; only; direct
cross-module imports of internal submodules are prohibited by architectural tests.
Status and kanban are owned &lt;strong&gt;exclusively by Mission Management&lt;/strong&gt; (the &lt;code dir=&quot;auto&quot;&gt;status/&lt;/code&gt;
OHS facade). The canonical execution-state surface is the top-level
&lt;a href=&quot;/adr/3.x/2026-06-07-1-execution-state-canonical-surface/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;&lt;/a&gt;
package. The &lt;strong&gt;Op execution tier&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;spec-kitty dispatch&lt;/code&gt; plus
&lt;code dir=&quot;auto&quot;&gt;profile-invocation complete&lt;/code&gt; and the pre/post-mission lifecycle) sits across
the modules as the shared Op shape.&lt;/p&gt;
&lt;h3 id=&quot;how-the-modules-map-onto-the-enforced-layer-packages&quot;&gt;How the modules map onto the enforced layer packages&lt;/h3&gt;
&lt;p&gt;The four modules are &lt;em&gt;domain&lt;/em&gt; boundaries. The &lt;em&gt;import&lt;/em&gt; boundaries CI enforces are
the wheel packages in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; and the layer chain in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_layer_rules.py&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {glossary, runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt;.
The two views line up like this:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Main packages&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Shared Kernel&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/&lt;/code&gt; (root layer)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Governance&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/&lt;/code&gt; (including &lt;code dir=&quot;auto&quot;&gt;charter/offering/&lt;/code&gt;, the charter offering package that absorbed the former &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; package) and &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Execution / Runtime&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/&lt;/code&gt; (execution-state surface) and &lt;code dir=&quot;auto&quot;&gt;src/runtime/&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; control loop); workspace resolution under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Mission Management&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/&lt;/code&gt; (status, lanes, consolidation, coordination, the CLI)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;When a diagram and the enforced pair disagree, the enforced pair wins and the
diagram is the thing to fix.&lt;/p&gt;
&lt;h2 id=&quot;convention&quot;&gt;Convention&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Hand-authored Markdown + Mermaid&lt;/strong&gt; (renders on GitHub, no build tooling) — R-04.&lt;/li&gt;
&lt;li&gt;Each level uses a single canonical &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; entrypoint; additional detail
pages may live beside it.&lt;/li&gt;
&lt;li&gt;The 2.x snapshot under &lt;code dir=&quot;auto&quot;&gt;docs/architecture/{01_context,02_containers,03_components}/&lt;/code&gt;
is frozen as history; this living copy is the one refreshed against the
current domain model.&lt;/li&gt;
&lt;/ul&gt;
&lt;blockquote&gt;
&lt;p&gt;Deterministic diagram &lt;strong&gt;generation&lt;/strong&gt; (Structurizr/PlantUML) is deliberately out
of scope here — see upstream &lt;code dir=&quot;auto&quot;&gt;#1839&lt;/code&gt; (deduped vs &lt;code dir=&quot;auto&quot;&gt;#1812&lt;/code&gt;). This living C4 stays
hand-authored per R-04; the generated-C4 swap is cross-referenced only.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;R-04 carve-out (2026-08-12) — a separate lane, not a reversal.&lt;/strong&gt; R-04 is
&lt;strong&gt;unchanged for the hand-authored C4 architecture diagrams&lt;/strong&gt; in this directory:
they stay hand-authored Markdown + Mermaid so they render on GitHub, and
deterministic &lt;em&gt;generation of the C4 model&lt;/em&gt; remains out of scope. A &lt;strong&gt;new,
narrowly-scoped lane&lt;/strong&gt; now covers a different genre — &lt;strong&gt;generated,
docsite-only schema diagrams of code models&lt;/strong&gt; (the doctrine artefact schemas:
agent-profile, mission-type/step, DRG, artefact-kind vocabulary). Those are
&lt;code dir=&quot;auto&quot;&gt;@startyaml&lt;/code&gt; diagrams generated from the frozen models, rendered at docs-build
time and drift-guarded, and they render &lt;strong&gt;only on the built docsite&lt;/strong&gt;, not on
github.com source view. This lane does &lt;strong&gt;not&lt;/strong&gt; touch the C4 diagrams here. See
&lt;a href=&quot;/adr/3.x/2026-08-12-1-plantuml-schema-diagram-rendering/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;../../adr/3.x/2026-08-12-1-plantuml-schema-diagram-rendering.md&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;</content>
</entry>
