RAG-POC/docs/README.md

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.