Documentation

atif-sql · Documentation

Seventeen documents covering the architecture, reference surface, runtime behavior, and the things this codebase quietly assumes. Every factual claim carries a path:LOC citation into source.

Prose is generated; structure is mechanical. Cross-references are deterministic.

Measured 2026-08-28: 1,768 full-path citations plus 314 shorthands, resolving into 136 distinct source files. A validator rejects any citation naming a file that does not exist, a line outside that file’s range, or a shorthand with no resolvable antecedent, and it exits non-zero on the first one — so a citation here resolves or the tree does not ship.

Start here

If you want to	Read
Understand what this is and how it fits together	System overview
Run it	CLI
Know what happens when a command runs	Processes
Change something without breaking it	Impact analysis
Debug a failure	Debugging guide

Architecture

• System overview — the two-paragraph version, the stack, and one diagram of the seven workspace members.
• Module map — one section per member, ordered by source size, with the eight files in each that carry the weight.
• Data flow — three flows (materialize, query, analyze) traced end to end, each as a sequence diagram.

Reference

• CLI — all ten commands with verbatim usage, every flag, and the exit-code taxonomy. This is the public contract: atif-sql ships one installable distribution and the command is its supported entry point.
• Public API — the internal module surface, ranked by the enforced inter-package seam. No symbol here is a supported import path or carries a compatibility promise.

Behavior

• Processes — eight processes with numbered, cited steps, plus six minor flows.
• State machines — the three genuine multi-state lifecycles: corpus session materialization, embed-store schema version, and the retry-queue row.

Analysis

• Risk hotspots — ranked by type-checker defects, scanner findings, complexity ratchets, unguarded IO windows, and uncovered units. Commit churn is deliberately excluded and the document says why.
• Dead code — nothing in this workspace is deletable code. What the two populated tables record instead is export declarations with no consumer.

Diagrams

• Components — one class diagram over the seven members.
• Dependency graph — internal members and external distributions on one page, with the enforced direction stated.
• Sequences — call order for the top three processes.

Insights

• Impact analysis — eight high-impact surfaces, each with the downstream effects and the gate that catches you for missing one.
• Debugging guide — a failure-mode index, the log and error surfaces, and a first-checks ladder ordered cheapest first.
• Contract map — eleven contracts with producer, consumer, and shape, including the units, base, and scope of every numeric field crossing a seam.
• Business logic — the domain rules: validations, invariants, calculations, and policies, with the test that pins each one where a test exists.
• Tech debt — a ranked register with cost of removal. The workspace carries zero TODO/HACK/FIXME markers, so the register is built from version ceilings, justified lint suppressions, install weight, and platform gaps instead.

Two documents this tree deliberately omits

• analysis/ownership.md — the history is 97 commits over six days under a single bot identity, with zero human authors. A per-person ranked table and a bus-factor list would be noise dressed as analysis.
• reference/rpc-tools.md — there is no RPC, MCP, or HTTP surface. fastapi, uvicorn, starlette, and the supabase client stack do appear in the installed dependency closure, arriving transitively through harbor, and no first-party module imports any of them.

An empty file in either slot would imply absence by omission rather than by silence, which is why neither exists.

Hand-written documents that outrank inference

CONTRACT.md and CONTRACT-V2.md are authored, not generated. Where a generated document disagrees with one of them, the generated document cites source and flags the disagreement rather than picking a side.