A self-hosted research workspace that turns private documents into grounded answers, inspectable source passages, and provenance-aware knowledge graphs.
Note
Hosted live deployment: coming soon. The complete application is available for local self-hosting today.
Conventional RAG often retrieves isolated snippets and leaves the user to trust the result. GraphRAG keeps the retrieval path visible:
- small child chunks provide precise vector matches;
- larger parent chunks restore the surrounding context;
- a bounded Neo4j traversal adds supported relationships; and
- every answer can open the exact evidence registered as
[S#]citations.
The ingestion router keeps machine-readable text deterministic and uses OpenRouter document OCR or vision models only for scanned pages and meaningful visual regions.
| Area | Current capability |
|---|---|
| Documents | PDF, DOCX, TXT, and Markdown; 50 MB and 500-page owner defaults |
| Extraction | Native parsing plus selective PDF OCR and visual understanding |
| Retrieval | Qdrant child vectors expanded to structural parent context |
| Graph | Grounded Neo4j entities and assertions with chunk provenance |
| Answers | LangGraph orchestration, streamed output, citations, and answer-path graph |
| Access | Isolated owner and demo workspaces with signed eight-hour sessions |
| Funding | Server-funded demo allowance plus encrypted, session-scoped OpenRouter BYOK |
| Interface | Responsive Next.js workspace with light, dark, and system themes |
flowchart LR
B[Browser] --> W[Next.js web and BFF]
W --> A[FastAPI API]
A --> L[LangGraph query workflow]
A --> R[(Redis)]
R --> K[Taskiq worker]
K --> O[(MinIO)]
K --> Q[(Qdrant)]
K --> N[(Neo4j)]
L --> Q
L --> N
K --> OR[OpenRouter]
L --> OR
Only the Next.js service should be public in production. FastAPI, the worker, Redis, Neo4j, Qdrant, and object storage belong on a private network.
- Docker Desktop or Docker Engine with Compose 2.24 or newer.
- An OpenRouter API key with credit for the configured models.
- Git.
git clone https://github.com/PB811/GraphRAG.git
cd GraphRAG
cp .env.example .envOpen .env and set:
OPENROUTER_API_KEY=your-openrouter-keyThe local .env file is ignored by Git. When DEMO_OPENROUTER_API_KEY is blank in development, sponsored demo requests use OPENROUTER_API_KEY; use a separately capped key before exposing a deployment.
docker compose up --build --detach
docker compose psThe first build downloads the application and database images and can take several minutes. Open http://localhost:3000 after the services are running and their dependencies report healthy.
| Account | Username | Development password | Purpose |
|---|---|---|---|
| Owner | owner |
graphrag-local |
Unrestricted private workspace |
| Demo | demo |
graphrag-demo |
Two documents and five sponsored questions |
These credentials are development defaults only. Production refuses placeholder hashes, weak session secrets, and plaintext account passwords.
- Open Documents and upload a supported file.
- Wait until its status becomes Ready.
- Return to Ask, select the source, and submit a question.
- Open an
[S#]citation or the Graph page to inspect the retrieved evidence.
Follow logs:
docker compose logs --followCheck the API and its dependencies:
curl http://localhost:8000/health/live
curl http://localhost:8000/health/readyStop the stack while preserving uploaded data and indexes:
docker compose downTo deliberately remove every local Redis, Neo4j, Qdrant, and MinIO volume:
docker compose down --volumesWarning
docker compose down --volumes permanently deletes the local corpus, graph, vectors, quotas, and uploaded originals.
If port 3000 is already in use, change WEB_BIND_PORT and WEB_ORIGIN together in .env.
.env.example documents every setting. The most important groups are:
- Model roles: embedding, document extraction, graph extraction, answer, utility, and fallback model lists.
- Retrieval: parent and child sizes, overlap, result limits, graph hops, and context budget.
- Access: account names, password hashes, workspace IDs, session lifetime, and encryption key.
- Demo safety: document, page, token, ingestion, and question limits.
- Storage: Redis, Neo4j, Qdrant, and S3-compatible endpoints and credentials.
Changing to an embedding model with different dimensions requires a new Qdrant collection and a complete re-index.
Self-hosting keeps originals, graph data, vectors, and application services under your control. It does not make model inference local. Depending on the document and question, extracted text, rendered PDF pages, image regions, graph context, and answer context are sent to the OpenRouter models configured in .env.
- Review the selected providers' data policies before using confidential material.
- OpenRouter requests can consume paid credit; OCR and vision-heavy PDFs generally cost more than native TXT or Markdown.
- Never commit
.env, API keys, cookies, production logs, or private documents. - Treat generated answers as model output and verify important claims through the included citations.
- Use a separately capped
DEMO_OPENROUTER_API_KEYfor any shared deployment.
Temporary user keys are validated, encrypted with AES-256-GCM, stored only as TTL-bound Redis ciphertext, and removed on disconnect, logout, expiry, or demo reset. See the access model and security policy.
Native development requires Python 3.12, uv, and Node.js 24.
make setup
make test
make lint
make typecheck
npm --prefix frontend run build
docker compose config --quietThe opt-in integration suite targets a running deployment. The evaluation harness uploads a fixture, asks fixed questions, checks facts and evidence, and then cleans up; it makes real OpenRouter requests and consumes credit. See Operations for both workflows.
The repository includes Dockerfiles and Railway configuration for one public web service and six private application/data services. Follow Deploy GraphRAG to Railway for service roots, private domains, volumes, secrets, migration, and verification.
A maintained public live deployment is planned but is not available yet. No production URL or uptime guarantee is implied by this repository.
backend/app/ FastAPI, extraction, retrieval, graph, access, and worker code
frontend/app/ Next.js routes and product screens
frontend/components/ Application shell and Cytoscape answer-path map
tests/ Backend, frontend, integration, and evaluation coverage
scripts/ Operational evaluation tools
docs/ Product, architecture, access, deployment, and operations docs
docker-compose.yml Complete local seven-service stack
- Product overview
- Architecture
- Access and funding model
- Design system
- Railway deployment
- Operations
- Roadmap
- Security policy
GraphRAG is available under the MIT License.