> For the complete documentation index, see [llms.txt](https://stemma.sh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stemma.sh/docs/evidence-and-internals/architecture.md).

# Architecture

A codemap for contributors. One engine pipeline, with comparison downstream:

```
DOCX bytes -> import -> CanonDoc -> explicit edit -> serialize -> DOCX bytes
             (stemma-engine)                         ^ linker gates output

accepted base + accepted target -> stemma-diff -> engine operations -> redline
```

* **`stemma-engine`** owns the typed document model and transformation pipeline.
* **`stemma-diff`** owns comparison inference and Stemma's one review presentation, then lowers through the engine.
* **`stemma-artifacts`** owns shared file identity and create-new persistence.
* **`stemma-cli`** exposes local command-line workflows.
* **`stemma-mcp`** exposes the engine to agents over stdio.
* **`stemma-api`** is the local HTTP demonstration transport.

The CLI, MCP, and HTTP crates are adapters over the engine's `api::Document` facade (plus `SimpleRuntime` for session management). A new consumer, a viewer, a renderer, a hosted service, depends on the facade the same way, not on a transport's JSON: see [Embed the engine](/docs/reference/embedding.md); the shapes it reads from are the [read model reference](/docs/reference/read-model.md).

The browser review editor lives under `stemma-examples` and uses the HTTP API.

Inside the engine, the load-bearing ideas:

* **`CanonDoc`** (`domain/`): ordered `TrackedBlock`s (paragraph / table / opaque), each block a tree of tracked segments and inline nodes with stable ids. Non-body stories (footnotes, headers, comments) are parallel collections on the same document.
* **Preserved remainder**: any pPr/rPr/inner-XML child the IR has no typed field for is captured verbatim (`PreservedProp`) and re-emitted at its schema position. Unmodeled content is not dropped. The typed fields and the preserved bag partition each property space; growing the model means moving an element from the bag to a field on both the parse and serialize sides.
* **Revision model** (`tracked_model.rs`): every tracked-change kind carries what reject must restore (formatting changes snapshot the complete prior properties). `enumerate_revisions` is the single source both reads and selective resolution address. A revision that it cannot see cannot be resolved.
* **Edit layer** (`edit/`, `edit_v4.rs`): the v4 wire grammar parses at the edge into typed `EditStep`s; verbs validate preconditions (expect / `semantic_hash` guards), apply in canonical space, and are proven by the per-verb fidelity gate (reversibility, accept==direct, opaque inventory never shrinks).
* **Serializer + linker** (`serialize/`, `docx_validate*`): rebuilds parts from the IR, then a post-serialization OOXML linker (content types, ordering, annotation pairing, cross-refs) gates the bytes. Byte identity is explicitly not a goal. See the [fidelity contract](/docs/understand-the-model/fidelity.md).
* **Comparison subsystem** (`stemma-diff` crate): consumes two accepted readings and chooses Stemma's review presentation. It depends on the engine's native edit, package, serialization, and verification operations; the engine has no dependency back to comparison. Product callers use the single opinionated `stemma_diff::diff` surface. See the [comparison boundary](/docs/evidence-and-internals/comparison-boundary.md).

Deeper dives live next to the code: `stemma-engine/docs/` (invariants catalog, testing strategy) and per-module `AGENTS.md` files.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://stemma.sh/docs/evidence-and-internals/architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.