RAG-POC/docs
GAJ3T 193ca094b5 added mmd and pdf 2026-10-15 10:38:33 -04:00
..
diagrams added mmd and pdf 2026-10-15 10:38:33 -04:00
README.md added mmd and pdf 2026-10-15 10:38:33 -04:00
api.md docs updated 2026-10-15 10:20:38 -04:00
architecture.md docs updated 2026-10-15 10:20:38 -04:00
configuration.md docs updated 2026-10-15 10:20:38 -04:00
data-model.md docs updated 2026-10-15 10:20:38 -04:00
module-reference.md docs updated 2026-10-15 10:20:38 -04:00
operations.md docs updated 2026-10-15 10:20:38 -04:00
overview.md docs updated 2026-10-15 10:20:38 -04:00
runbook.md docs updated 2026-10-15 10:20:38 -04:00
source-contract.md docs updated 2026-10-15 10:20:38 -04:00
testing.md docs updated 2026-10-15 10:20:38 -04:00

README.md

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 Scope, boundaries, stage flow, and key design decisions
Architecture Runtime topology, stage contracts, persistence, and retrieval
Runbook Step-by-step local setup, ingestion, rebuilds, recovery, and shutdown
Configuration Environment variables, defaults, and production guidance
Source contract JSONL and PostgreSQL handoff schemas
API reference Internal endpoints, JWT claims, permissions, and examples
Data model Checkpoint tables and stage ownership
Testing Test commands, prerequisites, and performance checks
Operations and troubleshooting Logs, health checks, failures, retries, and known limitations
Module reference Python modules, stage entry points, and responsibilities

C4 diagrams

The diagrams are editable in diagrams.net/draw.io. 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 Mermaid PDF
Container Draw.io Mermaid PDF
Component Draw.io Mermaid PDF
Code Draw.io Mermaid 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:

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.