Documentation

atif-sql · Documentation

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.

Citations come as full paths or as shorthands, and each one resolves into a source file. The docs site build turns each one into a link and fails on the first citation naming a file that does not exist at the commit it links to, or a shorthand with no resolvable antecedent. mise run docs:citations also fails on a line outside its file and, against the base commit, on a citation whose cited lines a change moved or removed without editing the citation, so a citation here resolves to the code it names 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 short version, the stack, and one diagram of the workspace members.
• Module map: one section per member, with the files in each that carry the weight.
• Data flow: the flows (materialize, query, analyze) traced end to end, each as a sequence diagram.

Reference

• CLI: every command 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: the processes with numbered, cited steps, plus the minor flows.
• State machines: the 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 populated tables record instead is export declarations with no consumer.

Diagrams

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

Insights

• Impact analysis: the 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: the 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 no TODO/HACK/FIXME markers, so the register is built from version ceilings, justified lint suppressions, install weight, and platform gaps instead.

Documents this tree deliberately omits

• analysis/ownership.md: every commit in the history names either the one maintainer or a GitHub bot account. 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 locked dev 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.