domus-api

REST API that makes 3,486 AsciiDoc files across 5 Antora repositories programmable via HTTP.

Premise

The documentation system — 15 months of worklogs, incident reports, change requests, RCAs, project plans, CLI patterns, standards, and education materials — was readable but not programmable. Knowledge was trapped behind a browser. No machine, no script, no agent could interact with it.

domus-api solved that. Every document became a queryable JSON resource. Every standards-governed workflow became a POST endpoint. The filesystem remained the single source of truth — no database, no ORM, no copies that drift.

What I Built

44 REST endpoints across 25 route modules — every content category in domus-captures has a dedicated route
Filesystem-as-database architecture — Python dict as index, pathlib as query engine, AsciiDoc files as records
Standards-compliant scaffolding — POST endpoints create incidents (STD-011), change requests (STD-005), RCAs (STD-010), and projects (STD-001) with the same templates a human would use
Multi-spoke auto-discovery — SpokeConfig.discover() finds all Antora repos in _bibliotheca/ and indexes them at startup. 5 spokes, 1,935 pages, zero configuration
FastAPI dependency injection — Depends(get_cache) pattern across all route handlers, replacing module-level globals
Cache invalidation — add_page() / add_partial() methods called after every POST, so writes are immediately searchable
Comprehensive test suite — 55 async pytest tests with httpx + 48 bash validation checks including feature assertions (STD-NNN filter, cache invalidation, multi-spoke loading, component-scoped search)
Quantitative coverage tracking — measure-theoretic capacity analysis (κ = 0.620) with reproducible acquisition commands

Skills Demonstrated

Skill	Evidence
REST API design	44 endpoints, resource modeling, OpenAPI auto-documentation
Python async	FastAPI + uvicorn + httpx async test client
Architecture decisions	Filesystem-as-database with written justification for why no ORM/Postgres
Dependency injection	FastAPI Depends pattern replacing 20 module-level cache assignments
Testing strategy	Integration tests against real filesystem data, cleanup fixtures, parametrized endpoint coverage
Multi-tenancy	Multi-spoke auto-discovery, component tagging, scoped queries
Applied mathematics	Coverage analysis using measure theory and AHP weighting
CLI tooling	jq/curl/awk pipeline composition for API interaction (6-level curriculum)

Skill

Evidence

REST API design

44 endpoints, resource modeling, OpenAPI auto-documentation

Python async

FastAPI + uvicorn + httpx async test client

Architecture decisions

Filesystem-as-database with written justification for why no ORM/Postgres

Dependency injection

FastAPI Depends pattern replacing 20 module-level cache assignments

Testing strategy

Integration tests against real filesystem data, cleanup fixtures, parametrized endpoint coverage

Multi-tenancy

Multi-spoke auto-discovery, component tagging, scoped queries

Applied mathematics

Coverage analysis using measure theory and AHP weighting

CLI tooling

jq/curl/awk pipeline composition for API interaction (6-level curriculum)

Current State

v0.1.0 — Phase 1 (Read), Phase 2 (Write), Phase 4 (Multi-Spoke) complete
5 Antora spokes indexed automatically
D2 architecture diagram created

Next Steps

Phase 3: Ollama RAG — GET /ask?q=… with local inference (RTX 5090 + qwen3:30b)
Phase 5: Filesystem watcher + webhook automation
Write expansion: POST for worklogs, patterns, codex entries
Full CRUD: PUT, DELETE across all resource types
systemd service + Tailscale ACL for persistent deployment

Architecture Notes

Terminal (curl/jq) → domus-api (FastAPI) → Filesystem (AsciiDoc across 5 spokes)

No database. Python dict = index. Filesystem = storage. Writes go to disk, cache invalidates, GET reflects immediately.