Architecture diagrams · FastRAG Docs

Interactive diagrams of FastRAG, generated with the archify diagram tool (v3.0.1) from the code at commit 41815d0. Every node cites the lines it is drawn from, and in the HTML viewer each SRC badge links to those lines on GitHub. Open the .html files in a browser; each one is a self-contained file.

On the website this page is /docs/diagrams, and each diagram is served at /diagrams/<folder>/<name>.html; website/scripts/copy-diagrams.mjs copies them into the site at build time. GitHub shows the .html files as source, so use the website or a local checkout to view them.

#	Diagram	Type	What it documents
1	System context	architecture	FastRAG as one system, with its users, CI, model providers, data stores and GitHub
2	Containers (C4 level 2)	architecture	website and console proxies, the API, the RQ worker, offline scripts, stores, providers
3	API components	architecture	routes, `QueryPipeline`, its collaborators and the `ports.py` adapters
4a	Streamed query	sequence	`/v1/query/stream` from the browser through guard, caches, retrieval, rerank, CRAG and the LLM
4b	Uploaded document	sequence	ingest, document-scoped query and delete for a session upload
5	Data model · ERD	architecture + Mermaid	`index_manifests`, Qdrant collections and chunk points, Redis cache keys, calibration and eval files
6	Data flow	dataflow	offline indexing and eval-set generation, the online query path, what leaves the system
7	Hosted deployment	architecture	three Vercel projects, managed data services and model APIs (cloud profile)
8a	Index lifecycle	lifecycle	`index_manifests.state`: building → validated → active → retired / failed
8b	Query lifecycle	lifecycle	how one request ends: answered, cached, no_answer, refused or unavailable
9	Release runbook	workflow	ingest → calibrate → activate → deploy → golden and bench gates, with failure exits
10	Compose network	architecture	the self-hosted stack: Caddy ingress, one bridge network, ports, egress

Archify has no ER notation, so the data model is drawn two ways: as an interactive entity map, and as a Mermaid erDiagram with typed attributes and cardinalities in erd.md, which GitHub renders inline. The hosted deployment (7) and the compose network (10) show the two topologies FastRAG actually runs in; neither uses VPCs or subnets.

Findings recorded on the diagrams

The analysis behind these diagrams turned up the following. They are recorded in the diagrams' cards and have not been changed in code:

/metrics, /docs and /openapi.json need no authentication, and nothing rate-limits inbound requests.
IndexBuilder flips the Qdrant alias before registry.activate() runs.
register() is an UPSERT, so rebuilding an existing version resets its row, even the active one, to building.
mark_failed has no state guard.
cache_namespace() does not include the reranker fingerprint or the calibration thresholds, so requests that override those without skip_cache share cache entries with default requests.
QueryTimings.cache_ms is never set, and the log_level setting is never read.
Guardrails.check_safety_model exists but nothing calls it.
compose.yaml reads LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY, while .env.local.example defines them with a FASTRAG_ prefix.

Regenerating

Each folder holds the archify source (candidate.json) next to its rendered HTML. After editing a candidate, re-render it from the repository root; the .evidence/ output is gitignored:

node <archify>/bin/archify.mjs finalize <type> docs/diagrams/<folder>/candidate.json \
  docs/diagrams/<folder>/<name>.html --repo-root . --quality showcase \
  --out-dir docs/diagrams/<folder>/.evidence/<run> --json

When the code changes, update meta.repository.revision and recheck the cited line ranges; the check gate verifies every citation against that commit.