added mmd and pdf

This commit is contained in:
GAJ3T 2026-10-15 10:38:33 -04:00
parent 82a5a0e557
commit 193ca094b5
9 changed files with 87 additions and 7 deletions

View File

@ -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.

20
docs/diagrams/c4-code.mmd Normal file
View File

@ -0,0 +1,20 @@
flowchart LR
s1("01 normalize<br/>raw + documents")
s2("02 clean/chunk<br/>chunks")
s3("03 model<br/>knowledge_models")
s4("04 extract<br/>extractions")
s5("05 reconcile<br/>resolved data")
s6("06 graph<br/>nodes + edges")
s7("07 communities<br/>summaries")
s8("08 index<br/>search_items + HNSW")
s9("09 retrieve<br/>vector + graph context")
s10("10 answer<br/>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;

BIN
docs/diagrams/c4-code.pdf Normal file

Binary file not shown.

View File

@ -0,0 +1,18 @@
flowchart LR
api("api.py<br/>Routes and request models")
auth("auth.py<br/>JWT and permission checks")
orch("orchestrator.py<br/>Durable runs and locks")
runtime("runtime.py + stage_loader.py<br/>Context and stage dispatch")
storage("storage.py + models.py<br/>SQLAlchemy and PgVector")
llm("llm.py<br/>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;

Binary file not shown.

View File

@ -0,0 +1,19 @@
flowchart LR
api("FastAPI API<br/>Internal query, answer, and job routes")
worker("Worker<br/>Claims and executes durable runs")
db[("PostgreSQL + PgVector<br/>Checkpoints, graph, vectors, HNSW")]
stages("Numbered stage modules<br/>Normalize through answer")
llm("OpenAI-compatible provider<br/>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;

Binary file not shown.

View File

@ -0,0 +1,14 @@
flowchart LR
kg("KnowledgeGraph GraphRAG")
mcp("Web-Access MCP + Data-Store MCP<br/>External source collection")
bff("Existing BFF<br/>Authentication and policy")
llm("OpenAI-compatible provider<br/>Chat and embeddings")
mcp -->|"Versioned source handoff"| kg
bff -->|"Signed internal JWT<br/>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;

Binary file not shown.