Knowledge Graph RAG System for ToPWR
Intelligent assistant for Wrocław University of Science and Technology
Quick Start • Architecture • Features • API
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Frontend │────▶│ ToPWR API │────▶│ MCP Server │────▶│ Neo4j │
│ :80 │ │ :8000 │ │ :8005 │ │ :7687 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
React + Nginx FastAPI FastMCP Knowledge Graph
- PWrChat UI - React chatbot (session sidebar, dark/light mode toggle, persistent theme)
- Intelligent Query Routing - Guardrails system determines query relevance
- Natural Language to Cypher - Converts questions to graph queries
- Knowledge Graph RAG - Retrieval-Augmented Generation with Neo4j
- MCP Protocol - Standard Model Context Protocol interface
- Observability - Optional Langfuse tracing integration
- Docker Ready - One command deployment
# Setup
just setup
cp .env.example .env # Edit with your API keys
# Run with Docker
just up # Start Neo4j + MCP Server + API
just logs # View logs
just down # Stop services┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Frontend │────▶│ ToPWR API │────▶│ MCP Server │────▶│ Neo4j │
│ :80 │ │ :8000 │ │ :8005 │ │ :7687 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
React + Nginx FastAPI FastMCP Knowledge Graph
| Service | Port | Description |
|---|---|---|
frontend |
80 | PWrChat — React chatbot UI served by Nginx |
topwr-api |
8000 | FastAPI backend for ToPWR app |
mcp-server |
8005 | MCP server with RAG pipeline |
neo4j |
7474/7687 | Knowledge graph database |
The heart of the system is a LangGraph-based RAG pipeline that intelligently processes user queries:
Pipeline Flow:
- Guardrails - Fast LLM determines if query is relevant to knowledge base
- Cypher Generation - Accurate LLM converts natural language to Cypher query
- Retrieval - Execute query against Neo4j knowledge graph
- Response - Return structured context data
Separate ETL pipeline for ingesting documents into the knowledge graph:
Pipeline Steps:
- Document Loading - PDF and text document ingestion
- Text Extraction - OCR and content extraction
- LLM Processing - Generate Cypher queries from content
- Graph Population - Execute queries to build knowledge graph
Copy .env.example to .env and configure:
########################################
# LLM / AI Provider Keys
########################################
# OpenAI API key (optional)
OPENAI_API_KEY=
# DeepSeek API key (optional)
DEEPSEEK_API_KEY=
# Google Generative AI / PaLM API key (optional)
GOOGLE_API_KEY=
# CLARIN LLM API key (optional, used by API & client)
CLARIN_API_KEY=
########################################
# Langfuse Observability
########################################
LANGFUSE_SECRET_KEY=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_HOST=https://cloud.langfuse.com
########################################
# Neo4j Database
########################################
# URI used by data pipeline, MCP server and graph config
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=
########################################
# MCP Server Networking
########################################
# Bind host for the MCP server process
MCP_BIND_HOST=0.0.0.0
# Host/port used by API and MCP client to reach the MCP server
MCP_HOST=127.0.0.1
MCP_PORT=8005# Docker Stack
just up # Start all services (including frontend at :80)
just down # Stop services
just logs # View logs
just ps # Service status
just nuke # Remove everything
# Local Development
just mcp-server # Run MCP server
just api # Run FastAPI
just kg "query" # Query knowledge graph
# Frontend
just frontend-install # Install npm dependencies
just frontend-dev # Start dev server at :3000 (requires running API)
just frontend-build # Build for production
# Quality
just lint # Format & lint
just test # Run tests
just ci # Full CI pipeline
# Data Pipeline
just prefect-up # Start Prefect
just pipeline # Run ETLsrc/
├── mcp_server/ # MCP server + RAG pipeline
├── mcp_client/ # CLI client
├── topwr_api/ # FastAPI backend
├── config/ # Configuration
└── data_pipeline/ # Prefect ETL flows
frontend/
├── src/
│ ├── api/ # API client
│ ├── hooks/ # useUserId, useSessions, useChat, useTheme
│ ├── components/ # Sidebar, Chat, shared UI
│ └── types/ # TypeScript mirrors of backend models
└── package.json # React + Vite + TailwindCSS
docker/
├── compose.stack.yml # Main stack (Neo4j + MCP + API + Frontend)
├── compose.prefect.yml # Data pipeline
├── Dockerfile.mcp # MCP server image
├── Dockerfile.api # FastAPI image
├── Dockerfile.frontend # React + Nginx image
└── nginx.conf # SPA fallback + API proxy
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"user_id": "user1", "message": "Czym jest nagroda dziekana?"}'Response:
{
"session_id": "abc123",
"message": "Nagroda dziekana to wyróżnienie przyznawane...",
"metadata": {
"source": "mcp_knowledge_graph",
"trace_id": "xyz789"
}
}# Get session history
curl http://localhost:8000/api/sessions/{session_id}/history
# List user sessions
curl http://localhost:8000/api/users/{user_id}/sessions| Technology | Purpose |
|---|---|
| React 18 + TypeScript | Frontend chat UI |
| Vite + TailwindCSS v3 | Build tooling & styling |
| Nginx | Frontend serving + API proxy |
| FastMCP | Model Context Protocol server |
| LangGraph | RAG state machine |
| LangChain | LLM orchestration |
| Neo4j | Knowledge graph database |
| FastAPI | REST API backend |
| Langfuse | Observability (optional) |
| Prefect | Data pipeline orchestration |
| Docker | Containerization |
MIT © Solvro