55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# KnowledgeGraph GraphRAG documentation
|
|
|
|
This folder is the operational and technical reference for the KnowledgeGraph
|
|
GraphRAG proof of concept. The repository README remains the shortest getting
|
|
started path; these documents explain the contracts behind it.
|
|
|
|
## Read this first
|
|
|
|
| Document | Use it for |
|
|
|---|---|
|
|
| [System overview](./overview.md) | Scope, boundaries, stage flow, and key design decisions |
|
|
| [Architecture](./architecture.md) | Runtime topology, stage contracts, persistence, and retrieval |
|
|
| [Runbook](./runbook.md) | Step-by-step local setup, ingestion, rebuilds, recovery, and shutdown |
|
|
| [Configuration](./configuration.md) | Environment variables, defaults, and production guidance |
|
|
| [Source contract](./source-contract.md) | JSONL and PostgreSQL handoff schemas |
|
|
| [API reference](./api.md) | Internal endpoints, JWT claims, permissions, and examples |
|
|
| [Data model](./data-model.md) | Checkpoint tables and stage ownership |
|
|
| [Testing](./testing.md) | Test commands, prerequisites, and performance checks |
|
|
| [Operations and troubleshooting](./operations.md) | Logs, health checks, failures, retries, and known limitations |
|
|
| [Module reference](./module-reference.md) | Python modules, stage entry points, and responsibilities |
|
|
|
|
## 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 | 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
|
|
|
|
The documentation is based on the implementation, tests, migration, Compose
|
|
definition, CI workflow, templates, and repository README. It documents current
|
|
behavior rather than promising features that are not implemented. In particular:
|
|
|
|
- source collection is external to this repository;
|
|
- stages 1-8 are durable worker jobs;
|
|
- query and answer are synchronous API/stage operations;
|
|
- 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.
|