arqix Architecture (arc42)

This page assembles the arc42 architecture document from one unit per chapter (REQ-01-01-11-01). Until arqix assemble build exists, the directives below document the intended assembly; afterwards they drive it.

Introduction and Goals¶

arqix is a deterministic documentation-as-code toolchain: it creates, formats, lints, assembles, traces, and publishes modular Markdown documentation whose structure and relationships are machine-readable. Documentation is treated as a dataset with a contract, not as prose with goodwill.

The system exists because "related" links between artefacts are not enough (see the blog post why arqix had to exist): requirements, stories, code, and tests need verifiable, tool-enforced traceability that survives automation.

Top Quality Goals¶

Stakeholders¶

The four current personas under ../personas/ (six earlier ones retired in the 2026 merge) condense into four C4 roles: the Documentation Maintainer (PER-01, standards and governance), the Builder (PER-09, corpus alongside code, pipelines, and architecture), the Assessor (PER-10, evaluates and consumes the corpus), and the Coding Agent (PER-08, deterministic story-by-story automation; includes CI). Coverage per persona is tracked in the requirements review table.

Architecture Constraints¶

Context and Scope¶

arqix operates on a documentation corpus inside a git repository. Humans and coding agents drive it through the CLI; CI runs the same commands as a gate; MCP clients consume the corpus through the built-in server. Rendering is delegated to external tools that arqix orchestrates but never trusts with control flow.

External interfaces: the filesystem (bounded by REQ-00-00-00-13), the render toolchain contract (errors forwarded transparently, REQ-04-01-03-07), the exit-code contract towards CI (REQ-04-01-08-01), and MCP over stdio (REQ-05-01-12-*).

Solution Strategy¶

1. One deterministic CLI. Every capability is a subcommand of a single Rust binary; every command resolves against the effective configuration (REQ-00-00-00-06) and honours the shared exit-code and diagnostics contracts (REQ-00-00-00-02/03). Determinism (REQ-00-00-00-01) is an architectural property, not a per-feature promise: no wall-clock, no randomness, stable ordering everywhere.
2. Documents are data. Frontmatter plus a small ontology (docs/ontology/) make structure and relationships machine-readable; IDs and slugs derive deterministically from configured policy (REQ-00-00-00-04). The corpus in this repository is arqix's first real corpus.
3. Contracts first, implementation second. The 165 requirements, the requirements style guide, and the Python checker scripts (requirements, frontmatter, trace markers, and the trace oracle) define testable contracts before Rust code exists; the scripts are the reference specification for the Rust port and stay as oracles until the cross-check retires them (chapter 8).
4. Traceability as a graph. Trace markers in code and tests, frontmatter links, and the derived-from/has-requirement symmetry form one graph that scan, matrix, coverage, and evidence-bundle commands project into views (REQ-03-01-*).
5. One parser, two layers. Documents are parsed exactly once by a shared Document Parser: a lossless concrete-syntax layer that the formatter needs for meaning-preserving rewrites (REQ-01-01-03-03), and a semantic document model (frontmatter, sections and anchors, directives, trace markers) that store, linter, assembler, and trace engine consume (REQ-02-01-09-, REQ-05-01-10-). One grammar, one implementation — parser drift across components would silently break determinism.
6. Delegated rendering. Pandoc and site toolchains stay external processes behind an orchestrator; arqix owns inputs, artefact placement, and error transparency, never the renderer (REQ-04-01-03-*).

Building Block View¶

The binary decomposes into fifteen components: the CLI entrypoint as composition root, the document parser as shared reading layer, the verification orchestrator sequencing the quality gate, and twelve feature components cut along the requirement clusters:

Shared spine: the CLI Entrypoint invokes every feature component and is the only place that turns results into exit codes; every component reports through Diagnostics & Exit Codes, reads configuration through the Config Resolver, and reads documents through the Document Parser; the Verification Orchestrator sequences the quality-gate sub-steps through the same command interface the entrypoint uses (ADR-0003). These five are the components that make the cross-cutting contracts (chapter 8) enforceable in one place; beyond the shared reading path through the Document Store & Catalog (Template Engine, Linter, Assembler, and MCP Server all discover the corpus through it — the Trace Engine walks the filesystem itself, mirroring the Python oracle), lateral coupling between feature components is limited to the export and publish paths: the Publisher's edges (→ Assembler for staging, → Store and Trace Engine for the specification catalogue), the Reporter's edges (→ Trace Engine for evidence, → Store and Assembler for the knowledge bundle), the MCP Server's trace tool (→ Trace Engine), and the Assembler's reuse of the Linter's include-directive grammar — the orchestrators' edges are command-API orchestration, not implementation coupling. A complementary write-path invariant holds across the cut: existing source documents are mutated only by the Formatter & Finaliser; the Template Engine creates new files, and Assembler and Publisher write generated artefacts (ADR-0004).

Command ownership¶

Each command has exactly one owning component — the component whose tests own the command's behaviour. The spine (Entrypoint → Config Resolver → … → Diagnostics & Exit Codes) is implicit in every flow; write flows additionally pass the containment, overwrite, and dry-run guards.

This table is the seed for the component test contracts: every row becomes the owning component's command-level test suite, and every flow becomes an integration-test skeleton.

The command taxonomy behind this table — noun–verb scheme, every analysis exists exactly once (coverage is trace coverage), report reserved for export products, verify as the deliberate top-level exception — is fixed in ADR-0005; this table is the normative command map.

Runtime View¶

Every scenario walks the shared spine — entrypoint → config resolution → feature component → diagnostics → exit code — so only the component-specific middle is described per scenario. Scenarios are documented once their commands ship; the publish scenario follows with its story.

arqix verify — the one-command loop¶

The Verification Orchestrator sequences the configured sub-steps as child invocations of the same binary — it never implements a check itself (ADR-0003, REQ-04-01-05-*).

1. Resolve the effective configuration (REQ-00-00-00-06).
2. Run fmt --check, lint run, trace scan, and trace coverage through the stable command interface; --fail-fast stops at the first failing step, the default aggregates all of them.
3. Collect each step's exit code into the per-step report (the verify wire schema in the ICD).
4. Exit with the worst channel observed: 0 clean, 1 findings, 2 when any sub-step ended outside the findings channel.

arqix assemble build — deterministic assembly¶

1. Discover the corpus through the Document Store (skip-dirs applied, directory symlinks never followed).
2. Map every source document to its output under pages/; a second source claiming an already-owned output is a structural error (ASM-003).
3. Expand <!-- arqix:include … --> depth-first, with the DFS stack as cycle detector (ASM-001) and repository containment enforced on every target (ASM-004, REQ-00-00-00-13).
4. Write the pages plus one JSONL record per assembly step — doc, chapter_id, out, include, sha256, bytes, at_line (REQ-04-01-01-04/-05).

arqix doc new — template instantiation¶

1. Validate the kind as a lowercase slug so it can never escape the configured root as a path component (REQ-00-00-00-13).
2. Scan the existing document IDs and derive the next counter deterministically (REQ-00-00-00-04, REQ-01-01-13-01).
3. Instantiate the kind's template into the configured location, never overwriting (TPL-001, REQ-00-00-00-08); dates stay TODO for finalise (ADR-0004: no ambient clock).
4. Report id, kind, and path as the creation result (REQ-01-01-13-02).

Planned¶

• arqix publish site --lang — per-language root resolution and toolchain orchestration with error forwarding (REQ-04-01-07-*); documented with its story.

Deployment View¶

TODO — to be filled when distribution is set up.

Intended shape: a single statically-built binary installed via cargo install (later: release artefacts per platform); no runtime dependencies except the optional external render toolchain; CI consumes the same binary as developers (REQ-00-00-00-02 keeps behaviour identical across environments).

Crosscutting Concepts¶

Each concept below is a system-wide contract with its own cross-cutting requirement; components implement them via the shared spine (chapter 5).

• Determinism — byte-identical outputs for identical inputs and configuration; stable ordering, no ambient state (REQ-00-00-00-01).
• Corpus traversal — the markdown corpus walk reproduces Python sorted(dir.rglob('*.md')) byte for byte: each directory level is sorted, directory symlinks are never followed, and *.tpl.md templates are excluded. It is one shared internal helper (src/util.rs collect_markdown, consumed by the store and the publisher); the trace engine and the checkers keep their own walks, and consolidating them is planned refactor work. walkdir is deliberately not adopted (ADR-0014 dependency posture): it would still need the same manual sort, skip-directory, and extension filtering wrapped around it to match the oracle, so it removes almost no code while adding a supply-chain dependency and a silent ordering- or symlink-drift risk.
• Diagnostics contract — every diagnostic is available as documented JSON with severity, stable code, message, and source location (REQ-00-00-00-03, REQ-04-01-10-*); coverage gaps use the same shape, and trace outputs are layered with per-layer stability promises (ADR-0006).
• Exit codes — 0 success, 1 findings or gate failure, 2 usage error; stable across releases (REQ-00-00-00-02, REQ-04-01-08-01).
• Effective configuration — one resolution path from arqix.toml through defaults and overrides; config show renders exactly what commands act on (REQ-00-00-00-06).
• ID and slug policy — deterministic derivation from configured policy, global duplicate detection, stable anchors (REQ-00-00-00-04).
• i18n model — source documents with linked translations; missing, unresolved, and outdated translations are lint findings and CI gates (REQ-00-00-00-10).
• Guardrails — declared change scope via policy files, no overwrites without approval, filesystem containment, no content execution (REQ-00-00-00-07/08/13/14).
• Performance budgets — sub-second search/read and a ten-second verification loop on a 1000-document corpus as calibratable budgets (REQ-00-00-00-11/12).
• Line splitting and frontmatter parsing — four deliberately separate splitter contracts, not one shared splitter (REQ-00-00-00-01, ADR-0004). The parser's semantic split (parser::py_splitlines) mirrors Python str.splitlines over its full boundary set (form feed, NEL, the Unicode line and paragraph separators), so every body_offset, trace, and lint line number is indexed in that one line space. The rewriter's frontmatter split (rewriter::split_frontmatter) is byte-lossless instead: it breaks only on \n and preserves the exact fence bytes and terminator, so fmt leaves an already-conforming document byte-identical (ADR-0004). The checkers read through their own reference-faithful reader (checkers::shared::read_universal, one shared copy since refactor slice R5), pinned by the mirrored selftest cases now that the Python reference implementations are retired. The assembler's frontmatter_line_count stays a fourth local counter over str::lines(): folding it into the parser's body_offset would mix two line-index spaces and force a re-parse of the fragment. Consolidating these contracts is deliberately unplanned work: they differ in meaning, not by accident, and a shared splitter would have to serve all four meanings at once.
• Checker contract ownership — the Rust engine owns every corpus check: the frontmatter and requirements checkers (lint frontmatter / lint requirements), the trace engine, the marker gate, and the report units. The executable specification is the test suite: each contract's reference fixtures are mirrored case by case in its test module (selftest_cases_match_the_oracle and its siblings), so a regression against a pinned behaviour fails cargo test. The dogfooded arqix verify is the authoritative corpus gate: format, lint including the frontmatter/requirements checkers, trace-scan, coverage/ratchet/freshness per the configured [policies.verify], the marker gate, and the strategy-aware report-freshness check. The provenance of each port (the retired Python reference implementations and their conformance suites) is recorded in chapter 11 and the refactor-program plan package.

Architecture Decisions¶

Decisions are kept as ADRs under ../adr/, maintained per the path model with a canonical governance language (REQ-01-01-11-02).

Decision records predating the ADR directory live in the planning packages under docs/en/plans/ (ID scheme, canonical-owner model, atomicity, subject conventions).

Quality Requirements¶

TODO — quality tree and concrete scenarios to be elaborated.

Seed: the quality goals of chapter 1 refine into the cross-cutting requirements REQ-00-00-00-01..14; the two measurable performance budgets are REQ-00-00-00-11 (search/read ≤ 1 s @ 1000 documents) and REQ-00-00-00-12 (verify ≤ 10 s @ 1000 documents), both marked calibratable.

Risks and Technical Debt¶

Maintained as implementation proceeds. The Rust core landed in Phase 4 (parser, store, linter, rewriter, trace engine, verify, templates, assembler); the items below track what that left open.

Known at specification time:

• Python/Rust checker drift: closed (chapter 8 — the oracle policy ran its course: oracle until conformance, then retirement). Every family passed conformance — trace (cli_trace green with the Rust binary, value-equal output on the real corpus), the marker gate, the report units, and the frontmatter/requirements checkers (JSON value-equal) — and the owner retired all five Python scripts directly on 2026-07-15 (task #78), closing the grace period. The drift risk is gone with the second implementation; what guards the contracts now is the Rust test suite, which mirrors the retired oracles' selftest fixtures (selftest_cases_match_the_oracle and siblings), so a regression against the pinned behaviours fails the gate.
• Performance budgets have their first real measurements: at ~480 corpus documents (roughly half the 1000-document reference corpus), arqix verify completes in ~5.5s warm against the ten-second budget (REQ-00-00-00-12; the git-history marker-freshness sub-step dominates at ~2.7s) and doc search in ~0.15s against the one-second budget (REQ-00-00-00-11). Revisit when the corpus approaches 1000 documents or a budget is exceeded; the freshness sub-step is the first optimization candidate.
• The C4 views are rendered from workspace.dsl via the digest-pinned Kroki image (ADR-0016) and committed under model/generated/. Remaining debt: the freshness gate (just render-views-check, the architecture-diagrams workflow) is manual-dispatch only and not yet part of the blocking CI gate; promoting it once the Kroki invocation is confirmed on a runner is open.
• doc search is a linear full-text scan in v1 (src/store.rs); no index yet. The one-second budget (REQ-00-00-00-11) may later force an index, which brings state and invalidation questions. Decide with a dedicated search story, after measuring the linear scan on the real corpus.
• The assembly log path is a fixed v1 default (pages/assembly.jsonl); REQ-04-01-01-03 asks for it to be configurable, which lands with the render/publish configuration story in Phase 5. A missing include target is currently left verbatim by the assembler (the linter's LNT-001 is the tool that flags it); folding that signal into assemble build is a later refinement.
• A future documentation consistency check (drift between the C4 model, the Mermaid views, and the prose) is recorded as an extension path of the verification pipeline (REQ-01-01-11-05); no story schedules it yet.

Glossary¶

First project-specific terms; the full glossary will be scaffolded via arqix doc new glossary with stable IDs (REQ-01-01-12-*) once the tool exists. For domain vocabulary, the ontology labels under docs/ontology/ remain the controlled vocabulary.