diff --git a/docs/README.md b/docs/README.md
index 831a7ac..f6e5055 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,13 +22,23 @@ started path; these documents explain the contracts behind it.
## C4 diagrams
The diagrams are editable in [diagrams.net/draw.io](https://app.diagrams.net/).
+Each has a Mermaid companion with matching nodes, relationships, and colors,
+plus a PDF exported directly from the draw.io source. Mermaid uses automatic
+layout, so its positioning may differ from the draw.io diagram.
-| C4 level | Diagram |
-|---|---|
-| Context | [c4-context.drawio](./diagrams/c4-context.drawio) |
-| Container | [c4-container.drawio](./diagrams/c4-container.drawio) |
-| Component | [c4-component.drawio](./diagrams/c4-component.drawio) |
-| Code | [c4-code.drawio](./diagrams/c4-code.drawio) |
+| C4 level | Draw.io source | Mermaid source | PDF |
+|---|---|---|---|
+| Context | [Draw.io](./diagrams/c4-context.drawio) | [Mermaid](./diagrams/c4-context.mmd) | [PDF](./diagrams/c4-context.pdf) |
+| Container | [Draw.io](./diagrams/c4-container.drawio) | [Mermaid](./diagrams/c4-container.mmd) | [PDF](./diagrams/c4-container.pdf) |
+| Component | [Draw.io](./diagrams/c4-component.drawio) | [Mermaid](./diagrams/c4-component.mmd) | [PDF](./diagrams/c4-component.pdf) |
+| Code | [Draw.io](./diagrams/c4-code.drawio) | [Mermaid](./diagrams/c4-code.mmd) | [PDF](./diagrams/c4-code.pdf) |
+
+After editing a draw.io source, update its Mermaid companion and regenerate its
+PDF with the draw.io desktop CLI. For example, from the repository root:
+
+```powershell
+drawio --export --format pdf --crop --output .\docs\diagrams\c4-context.pdf .\docs\diagrams\c4-context.drawio
+```
## Documentation scope
@@ -42,4 +52,3 @@ behavior rather than promising features that are not implemented. In particular:
- PostgreSQL with PgVector is the deployment target;
- SQLite is supported for isolated tests, not production retrieval;
- LLM output is schema-validated but not independently fact-checked.
-
diff --git a/docs/diagrams/c4-code.mmd b/docs/diagrams/c4-code.mmd
new file mode 100644
index 0000000..a25bccd
--- /dev/null
+++ b/docs/diagrams/c4-code.mmd
@@ -0,0 +1,20 @@
+flowchart LR
+ s1("01 normalize
raw + documents")
+ s2("02 clean/chunk
chunks")
+ s3("03 model
knowledge_models")
+ s4("04 extract
extractions")
+ s5("05 reconcile
resolved data")
+ s6("06 graph
nodes + edges")
+ s7("07 communities
summaries")
+ s8("08 index
search_items + HNSW")
+ s9("09 retrieve
vector + graph context")
+ s10("10 answer
cited response")
+
+ s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10
+
+ classDef preparation fill:#dae8fc,stroke:#6c8ebf,color:#000;
+ classDef indexing fill:#d5e8d4,stroke:#82b366,color:#000;
+ classDef querying fill:#fff2cc,stroke:#d6b656,color:#000;
+ class s1,s2,s3,s4,s5 preparation;
+ class s6,s7,s8 indexing;
+ class s9,s10 querying;
diff --git a/docs/diagrams/c4-code.pdf b/docs/diagrams/c4-code.pdf
new file mode 100644
index 0000000..5797b6d
Binary files /dev/null and b/docs/diagrams/c4-code.pdf differ
diff --git a/docs/diagrams/c4-component.mmd b/docs/diagrams/c4-component.mmd
new file mode 100644
index 0000000..b0d8484
--- /dev/null
+++ b/docs/diagrams/c4-component.mmd
@@ -0,0 +1,18 @@
+flowchart LR
+ api("api.py
Routes and request models")
+ auth("auth.py
JWT and permission checks")
+ orch("orchestrator.py
Durable runs and locks")
+ runtime("runtime.py + stage_loader.py
Context and stage dispatch")
+ storage("storage.py + models.py
SQLAlchemy and PgVector")
+ llm("llm.py
Provider client and retries")
+
+ api -->|"authorize"| auth
+ api -->|"queue"| orch
+ orch -->|"dispatch"| runtime
+ runtime -->|"persist"| storage
+ runtime -->|"complete"| llm
+
+ classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000;
+ classDef dependency fill:#d5e8d4,stroke:#82b366,color:#000;
+ class api,auth,orch,runtime application;
+ class storage,llm dependency;
diff --git a/docs/diagrams/c4-component.pdf b/docs/diagrams/c4-component.pdf
new file mode 100644
index 0000000..442ad18
Binary files /dev/null and b/docs/diagrams/c4-component.pdf differ
diff --git a/docs/diagrams/c4-container.mmd b/docs/diagrams/c4-container.mmd
new file mode 100644
index 0000000..2317a01
--- /dev/null
+++ b/docs/diagrams/c4-container.mmd
@@ -0,0 +1,19 @@
+flowchart LR
+ api("FastAPI API
Internal query, answer, and job routes")
+ worker("Worker
Claims and executes durable runs")
+ db[("PostgreSQL + PgVector
Checkpoints, graph, vectors, HNSW")]
+ stages("Numbered stage modules
Normalize through answer")
+ llm("OpenAI-compatible provider
Chat and embeddings")
+
+ api -->|"dispatch"| worker
+ worker -->|"execute"| stages
+ stages -->|"persist/retrieve"| db
+ stages -->|"prompts/vectors"| llm
+ api -->|"status and query"| db
+
+ classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000;
+ classDef storage fill:#d5e8d4,stroke:#82b366,color:#000;
+ classDef external fill:#fff2cc,stroke:#d6b656,color:#000;
+ class api,worker,stages application;
+ class db storage;
+ class llm external;
diff --git a/docs/diagrams/c4-container.pdf b/docs/diagrams/c4-container.pdf
new file mode 100644
index 0000000..0fa64b7
Binary files /dev/null and b/docs/diagrams/c4-container.pdf differ
diff --git a/docs/diagrams/c4-context.mmd b/docs/diagrams/c4-context.mmd
new file mode 100644
index 0000000..469d371
--- /dev/null
+++ b/docs/diagrams/c4-context.mmd
@@ -0,0 +1,14 @@
+flowchart LR
+ kg("KnowledgeGraph GraphRAG")
+ mcp("Web-Access MCP + Data-Store MCP
External source collection")
+ bff("Existing BFF
Authentication and policy")
+ llm("OpenAI-compatible provider
Chat and embeddings")
+
+ mcp -->|"Versioned source handoff"| kg
+ bff -->|"Signed internal JWT
and API calls"| kg
+ kg -->|"Prompts and embeddings"| llm
+
+ classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000;
+ classDef external fill:#fff2cc,stroke:#d6b656,color:#000;
+ class kg application;
+ class mcp,bff,llm external;
diff --git a/docs/diagrams/c4-context.pdf b/docs/diagrams/c4-context.pdf
new file mode 100644
index 0000000..dcf0460
Binary files /dev/null and b/docs/diagrams/c4-context.pdf differ