IntentGuard

Review path · architecture

Architecture and engineering decisions

For hiring managers who want the shape of the system and the reasoning behind it: the authoritative specification, the recorded decisions with their alternatives, and the scope discipline that kept a weekend project a weekend project.

One authoritative specification, declared precedence

docs/specification/ declares itself the sole authoritative design source, with an explicit precedence order inside it (REQUIREMENTS first). The README and backlog summarize and link — they never replace it. Divergences that survived implementation are documented as numbered divergences (D1, D2) rather than silently reconciled. Specification home · AGENTS.md § Authority

Module boundaries that mirror the lifecycle

src/intentguard/ separates data, baseline, training, threshold, evaluation, artifacts, schemas, logging, API, and predictor into typed modules with focused responsibilities (NFR-007), validated by Ruff, strict mypy, and a repository-foundation checker on every make lint. Architecture

Decisions recorded with alternatives, not just outcomes

4 system ADRs cover the model and framework, dataset strategy, inference interface, and local packaging. Each records context, rejected alternatives, negative consequences, and a reconsideration trigger — the conditions under which the decision should be revisited.

Open the ADR Explorer for context, consequences, and affected nodes.

A typed serving boundary with honest failure modes

The FastAPI boundary validates input hard (empty text, oversized text, malformed JSON, unknown fields → stable 4xx without invoking inference), logs without raw request text, and reports readiness only after model, tokenizer, 77-label mapping, threshold, and metadata pass consistency checks. Interface contract · NFR-004/NFR-005

Scope control as an engineering feature

Docker, cloud, GPU CI, auth, dashboards, and every platform temptation are explicitly out of scope, parked in a reviewable parking lot. The specification freezes a vertical slice and the backlog enforces it — the strict demonstration must load the real transformer artifact, and degraded stand-ins are named degraded. Scope control · Parking lot

Production readiness, assessed rather than claimed

The specification includes a production-readiness assessment that says plainly what this system is not: no authentication, no horizontal scaling story, no monitoring stack. The README repeats it in the second paragraph. What production thinking looks like here is the checksum-verified artifact load, the typed error surface, and the privacy-conscious logging — not a claimed SLA. Production readiness

Trace any of it

The decision graph connects each ADR to the requirements and capabilities it names; requirement traceability continues to tests and validation commands. Use Compare Nodes to find the shortest source-grounded path between any two — for example FR-004 to its evaluation evidence.