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