# Code Graph Knowledge System
Enterprise knowledge management platform with Neo4j graph database, multi-interface architecture (MCP/Web/REST), and intelligent code analysis for modern software development teams.
## Overview
Code Graph Knowledge System is a production-ready platform that transforms code repositories and development documentation into a queryable knowledge graph. Built on Neo4j's graph database technology and powered by large language models, the system provides three distinct interfaces for different use cases: MCP protocol for AI assistants, Web UI for human users, and REST API for programmatic access.
The platform combines vector search, graph traversal, and LLM-driven analysis to deliver intelligent code intelligence capabilities including repository analysis, dependency mapping, impact assessment, and automated documentation generation.
## Core Capabilities
### Multi-Interface Architecture
**MCP Protocol (Port 8000)** - Model Context Protocol server for AI assistant integration
- Direct integration with Claude Desktop, Cursor, and other MCP-compatible tools
- 25+ specialized tools for code analysis and knowledge management
- Real-time task monitoring via Server-Sent Events
- Supports stdio and SSE transport modes
**Web UI (Port 8080)** - Browser-based interface for team collaboration
- Real-time task monitoring dashboard
- Repository ingestion and management
- Metrics visualization with interactive charts
- Built with React 18, TypeScript, and shadcn/ui components
**REST API (Ports 8000, 8080)** - HTTP endpoints for system integration
- Document ingestion and knowledge querying
- Task management and monitoring
- Prometheus metrics export
- OpenAPI/Swagger documentation
### Knowledge Graph Engine
**Code Intelligence** - Graph-based code analysis without requiring LLMs
- Repository structure mapping and dependency tracking
- Function and class relationship analysis
- Impact analysis for code changes
- Context pack generation for AI assistants
- Support for 15+ programming languages
**Memory Store** - Project knowledge tracking with temporal awareness
- Fact, decision, pattern, and insight recording
- Memory evolution with superseding relationships
- Automatic extraction from conversations, commits, and code
- Vector search with embedding-based retrieval
**Knowledge RAG** - Document processing with hybrid search
- Multi-format document ingestion (Markdown, PDF, code files)
- Neo4j native vector indexing
- Hybrid search combining vector similarity and graph traversal
- Configurable chunking and embedding strategies
**SQL Schema Parser** - Database schema analysis with business domain classification
- Multi-dialect support (Oracle, MySQL, PostgreSQL, SQL Server)
- Configurable business domain templates (Insurance, E-commerce, Banking, Healthcare)
- Automated relationship detection and documentation generation
- Integration with knowledge graph for cross-referencing
## Technology Stack
**Backend Infrastructure**
- FastAPI - High-performance async web framework
- Neo4j 5.x - Graph database with native vector indexing
- Python 3.13+ - Modern Python with type hints
- Uvicorn - ASGI server with WebSocket support
**AI and ML Integration**
- LlamaIndex - Document processing and retrieval pipeline
- Multiple LLM providers (Ollama, OpenAI, Gemini, OpenRouter)
- Flexible embedding models (HuggingFace, Ollama, OpenAI)
- Model Context Protocol (MCP) for AI assistant integration
**Frontend Technology**
- React 18 - Modern UI library with concurrent features
- TypeScript - Type-safe development
- TanStack Router - Type-safe routing
- shadcn/ui - Accessible component library
- Vite - Fast build tooling
## Quick Start
### Prerequisites
- Python 3.13 or higher
- Neo4j 5.0 or higher
- Docker (optional, for containerized deployment)
- Node.js 18+ (for frontend development)
### Querying Knowledge
```python
# Query the knowledge base
response = httpx.post("http://localhost:8000/api/v1/knowledge/query", json={
"question": "How does the authentication system work?",
"mode": "hybrid", # or "graph_only", "vector_only"
"use_tools": False,
"top_k": 5
})
# Search similar documents
response = httpx.post("http://localhost:8000/api/v1/knowledge/search", json={
"query": "user authentication",
"top_k": 10
})
```
### Installation
Clone the repository and install dependencies:
```bash
git clone https://github.com/royisme/codebase-rag.git
cd codebase-rag
pip install -r requirements.txt
# or using uv (recommended)
uv pip install -e .
```
Configure environment variables:
```bash
cp env.example .env
# Edit .env with your Neo4j credentials and LLM provider settings
```
Start Neo4j database:
```bash
docker run --name neo4j-code-graph \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/password \
-e NEO4J_PLUGINS='["apoc"]' \
neo4j:5.15
```
### Running the System
**Complete System (MCP + Web UI + REST API)**
```bash
python start.py
```
Access points:
- MCP SSE Service: `http://localhost:8000/sse`
- Web UI: `http://localhost:8080`
- REST API Documentation: `http://localhost:8080/docs`
- Prometheus Metrics: `http://localhost:8080/metrics`
**MCP Server Only**
```bash
python start_mcp.py
```
### Docker Deployment
Three deployment modes available:
**Minimal Mode** - Code Graph only (no LLM required)
```bash
make docker-minimal
```
**Standard Mode** - Code Graph + Memory Store (embedding model required)
```bash
make docker-standard
```
**Full Mode** - All features (LLM + embedding required)
```bash
make docker-full
```
## Usage Examples
### MCP Integration
Configure in Claude Desktop or compatible MCP client:
```json
{
"mcpServers": {
"code-graph": {
"command": "python",
"args": ["/path/to/start_mcp.py"],
"cwd": "/path/to/codebase-rag"
}
}
}
```
Available MCP tools include:
- `code_graph_ingest_repo` - Ingest code repository
- `code_graph_related` - Find related code elements
- `code_graph_impact` - Analyze change impact
- `query_knowledge` - Query knowledge base
- `add_memory` - Store project knowledge
- `extract_from_conversation` - Extract insights from chat
- `watch_task` - Monitor task progress
### REST API
**Ingest a repository:**
```bash
curl -X POST http://localhost:8080/api/v1/repositories/ingest \
-H "Content-Type: application/json" \
-d '{
"url": "https://github.com/user/repo.git",
"mode": "incremental",
"languages": ["python", "typescript"]
}'
```
**Query knowledge base:**
```bash
curl -X POST http://localhost:8080/api/v1/knowledge/query \
-H "Content-Type: application/json" \
-d '{
"question": "How does authentication work in this codebase?",
"mode": "hybrid",
"top_k": 5
}'
```
**Monitor tasks:**
```bash
curl http://localhost:8080/api/v1/tasks?status=processing
```
### Web UI
Navigate to `http://localhost:8080` to access:
- **Dashboard** - System health and quick actions
- **Tasks** - Real-time task monitoring with progress indicators
- **Repositories** - Repository management and ingestion
- **Metrics** - System performance and usage metrics
## Configuration
Key environment variables:
```bash
# Server Ports
MCP_PORT=8000 # MCP SSE service
WEB_UI_PORT=8080 # Web UI and REST API
# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j
# LLM Provider (ollama, openai, gemini, openrouter)
LLM_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2
# Embedding Provider (ollama, openai, gemini, openrouter)
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
# Processing Configuration
CHUNK_SIZE=512
CHUNK_OVERLAP=50
TOP_K=5
VECTOR_DIMENSION=384
```
For complete configuration options, see [Configuration Guide](https://vantagecraft.dev/docs/code-graph/getting-started/configuration).
## Architecture
### Dual-Server Design
The system employs a dual-server architecture optimized for different access patterns:
**Port 8000 (Primary)** - MCP SSE Service
- Server-Sent Events endpoint for real-time communication
- Optimized for AI assistant integration
- Handles long-running task monitoring
- WebSocket support for bidirectional communication
**Port 8080 (Secondary)** - Web UI + REST API
- React-based monitoring interface
- RESTful API for external integrations
- Prometheus metrics endpoint
- Static file serving for frontend
Both servers share the same backend services and Neo4j database, ensuring consistency across all interfaces.
### Component Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Client Interfaces │
├──────────────┬──────────────┬──────────────────────────┤
│ MCP Client │ Web UI │ REST API │
│ (AI Tools) │ (Browser) │ (External Systems) │
└──────┬───────┴──────┬───────┴──────────┬───────────────┘
│ │ │
└──────────────┼──────────────────┘
│
┌──────────────▼──────────────┐
│ FastAPI Application │
├──────────────┬──────────────┤
│ Services │ Task Queue │
└──────┬───────┴──────┬───────┘
│ │
┌──────▼──────┐ ┌───▼────┐
│ Neo4j │ │ LLM │
│ Database │ │Provider│
└─────────────┘ └────────┘
```
## Development
### Project Structure
```
codebase-rag/
├── src/codebase_rag/
│ ├── api/ # FastAPI routes
│ ├── core/ # Application core
│ ├── services/ # Business logic
│ │ ├── code_ingestor.py # Code repository processing
│ │ ├── graph_service.py # Graph operations
│ │ ├── memory_store.py # Project memory management
│ │ ├── neo4j_knowledge_service.py # Knowledge base
│ │ ├── task_queue.py # Async task processing
│ │ └── sql/ # SQL parsing services
│ └── mcp/ # MCP protocol handlers
├── frontend/ # React Web UI
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── routes/ # Page routes
│ │ └── lib/ # API client
│ └── package.json
├── tests/ # Test suite
├── docs/ # Documentation
└── scripts/ # Utility scripts
```
### Running Tests
```bash
# Backend tests
pytest tests/ -v
# Frontend tests
cd frontend && npm test
# Integration tests (requires Neo4j)
pytest tests/ -m integration
# Coverage report
pytest tests/ --cov=src --cov-report=html
```
### Code Quality
```bash
# Format code
black .
isort .
# Linting
ruff check .
ruff check . --fix
# Type checking
mypy src/
```
### Frontend Development
```bash
cd frontend
npm install
npm run dev # Start dev server at http://localhost:3000
npm run build # Build for production
npm run lint # Check for issues
npm test # Run tests
```
## Deployment
### Production Deployment
See [Docker Deployment Guide](https://vantagecraft.dev/docs/code-graph/deployment/docker) for production deployment configurations including:
- Multi-stage Docker builds
- Environment-specific configurations
- Scaling and load balancing
- Security best practices
- Monitoring and logging setup
### System Requirements
**Minimum Configuration**
- CPU: 2 cores
- RAM: 4 GB
- Storage: 10 GB
**Recommended Configuration**
- CPU: 4+ cores
- RAM: 8+ GB
- Storage: 50+ GB SSD
- Network: 100 Mbps+
## Documentation
Complete documentation available at [https://vantagecraft.dev/docs/code-graph](https://vantagecraft.dev/docs/code-graph)
### Key Documentation Sections
- [Quick Start Guide](https://vantagecraft.dev/docs/code-graph/getting-started/quickstart) - Get up and running in 5 minutes
- [Architecture Overview](https://vantagecraft.dev/docs/code-graph/architecture/overview) - System design and components
- [MCP Integration](https://vantagecraft.dev/docs/code-graph/guide/mcp/overview) - AI assistant integration
- [REST API Reference](https://vantagecraft.dev/docs/code-graph/api/rest) - Complete API documentation
- [Deployment Guide](https://vantagecraft.dev/docs/code-graph/deployment/overview) - Production deployment
- [Development Guide](https://vantagecraft.dev/docs/code-graph/development/setup) - Contributing and development
## Community and Support
- **Documentation**: [Complete Documentation](https://vantagecraft.dev/docs/code-graph)
- **Neo4j Guide**: [README_Neo4j.md](README_Neo4j.md)
- **Issues**: [GitHub Issues](https://github.com/royisme/codebase-rag/issues)
- **Discussions**: [GitHub Discussions](https://github.com/royisme/codebase-rag/discussions)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
Built with excellent open source technologies:
- [Neo4j](https://neo4j.com/) - Graph database platform
- [LlamaIndex](https://llamaindex.ai/) - Data framework for LLM applications
- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework for Python
- [React](https://react.dev/) - Library for building user interfaces
- [Model Context Protocol](https://github.com/anthropics/mcp) - AI assistant integration standard
