duocthu/docs-legacy/DOCUMENTATION_PLAN.md

Documentation plan

How the docs/ set in this directory was produced, what was inspected, what was executed, and what is deliberately left unverified. Kept so a later reader can judge how much weight each page carries.

Source-of-truth order

1. Production code (apps/ai-service/, apps/web/, ingestion/, packages/)
2. Runtime configuration (apps/ai-service/config.py, .env, Helm values, Compose files)
3. Tests (apps/ai-service/tests/, ingestion/tests/)
4. Deployment manifests (infra/, .github/workflows/)
5. Database migrations (apps/ai-service/migrations/)
6. CI/CD (.github/workflows/deploy.yml)
7. Scripts (ingestion/ingestion/cli.py, ingestion/ingestion/load/run.py, apps/ai-service/scripts/)
8. Pre-existing documentation — read for context, never used as evidence that the system behaves a certain way

Where a pre-existing document and the code disagree, the code wins and the disagreement is recorded in 26-known-limitations.md.

State vocabulary used throughout

Label	Meaning
Implemented	Code exists and is reachable from a runtime entrypoint
Partially implemented	Reachable, but with a named gap
Configured, not verified	Config/manifest exists; no evidence it runs
Test-only	Code exists and is tested but no runtime caller reaches it
Planned / TODO	Explicit TODO, placeholder, or NotImplementedError
Not found	Searched for, does not exist
Unable to verify	Would require access this session did not have

Phases

Phase	Scope	Output
1	Repository inventory: git ls-files, per-file line counts, entrypoint identification	01-repository-structure.md
2	Runtime architecture: main.py, bootstrap.py, config.py, routers/rag.py, import-graph checks for dead code	00, 02, 03
3	Ingestion: ingestion/ingestion/**, CLI subcommands, gates, artifacts on disk	04, 05, 06, 07
4	RAG: understanding, retrieval, orchestration, generation, grounding, prompts	08, 09, 10, 11
5	API + frontend: FastAPI routes, Next.js BFF routes, middleware, shared DTOs	12, 13
6	Infrastructure: Compose, Caddy, Helm, ArgoCD, CI, config/secret surface, security	14, 15, 16-security.md, 17, 20, 21, 22
7	Testing + evaluation: both suites executed, eval datasets and metric code read	18, 19
8	Operations: local dev, production runbook, troubleshooting	23, 24, 25
9	Consistency review: gaps, debt, code-derived roadmap, glossary	26, 27, 28, 29

Verification actually executed

Command	Result
cd ingestion && python -m pytest tests -q	277 passed, 12 skipped (32.9s)
cd apps/ai-service && python -m pytest tests -q	Collection error — tests/test_api.py imports main, which builds the runtime at import time and tries to reach Qdrant
cd apps/ai-service && EMBEDDING_PROVIDER=disabled python -m pytest tests -q	278 passed, 6 skipped (2.6s)
Corpus census over ingestion/data/processed/chunks.jsonl	15,100 chunks; 14,949 prose + 151 block_descriptor; 684 distinct drug_id; 19 distinct section_key; all schema_version=4
Census over ingestion/data/verified/drug_entities.json	684 entities, 10,164 aliases
Line count over ingestion/data/processed/monographs.jsonl	684 monographs
Import-graph grep for every rag/ module	Identified three test-only modules (see 27-technical-debt.md)

Not verified in this pass

• Live behaviour of https://realvuxbaro.me (no request was sent to production).
• Contents of apps/ai-service/.env.prod — gitignored, lives on the EC2 host. Every production-only configuration claim is marked accordingly.
• Qdrant/PostgreSQL round-trips: tests/test_live_datastores.py is gated behind RUN_INTEGRATION=1 and was not run (no local datastores).
• Any AWS Bedrock call (costs money on a personal account).
• Helm chart rendering and the ArgoCD Application manifests: never applied to a cluster from this repository.
• Frontend behaviour: there is no frontend test suite to run.

Historical documents retained

These predate this set and are retained for decision history or empirical measurements, not as current-state references: architecture.md, progress-log.md, document-profile.md, pdf-parsing-outlier-catalog.md, and the ADRs. Completed plans and superseded audits were removed. The canonical current end-to-end reference is pipeline-tu-pdf-den-chatbot-production.md.