added mmd and pdf
This commit is contained in:
parent
82a5a0e557
commit
193ca094b5
|
|
@ -22,13 +22,23 @@ started path; these documents explain the contracts behind it.
|
||||||
## C4 diagrams
|
## C4 diagrams
|
||||||
|
|
||||||
The diagrams are editable in [diagrams.net/draw.io](https://app.diagrams.net/).
|
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 |
|
| C4 level | Draw.io source | Mermaid source | PDF |
|
||||||
|---|---|
|
|---|---|---|---|
|
||||||
| Context | [c4-context.drawio](./diagrams/c4-context.drawio) |
|
| Context | [Draw.io](./diagrams/c4-context.drawio) | [Mermaid](./diagrams/c4-context.mmd) | [PDF](./diagrams/c4-context.pdf) |
|
||||||
| Container | [c4-container.drawio](./diagrams/c4-container.drawio) |
|
| Container | [Draw.io](./diagrams/c4-container.drawio) | [Mermaid](./diagrams/c4-container.mmd) | [PDF](./diagrams/c4-container.pdf) |
|
||||||
| Component | [c4-component.drawio](./diagrams/c4-component.drawio) |
|
| Component | [Draw.io](./diagrams/c4-component.drawio) | [Mermaid](./diagrams/c4-component.mmd) | [PDF](./diagrams/c4-component.pdf) |
|
||||||
| Code | [c4-code.drawio](./diagrams/c4-code.drawio) |
|
| 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
|
## Documentation scope
|
||||||
|
|
||||||
|
|
@ -42,4 +52,3 @@ behavior rather than promising features that are not implemented. In particular:
|
||||||
- PostgreSQL with PgVector is the deployment target;
|
- PostgreSQL with PgVector is the deployment target;
|
||||||
- SQLite is supported for isolated tests, not production retrieval;
|
- SQLite is supported for isolated tests, not production retrieval;
|
||||||
- LLM output is schema-validated but not independently fact-checked.
|
- LLM output is schema-validated but not independently fact-checked.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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;
|
||||||
Binary file not shown.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
Loading…
Reference in New Issue