ascii-diagrams.md•56 kB
# CodeGraph ASCII Architecture Diagrams
## System Architecture Overview
```ascii
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ CodeGraph System Architecture ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ Client Layer │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ Web UI │ │ CLI Client │ │ SDK Client │ │ MCP Client │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────▼─────┐ ║
║ │ API │ ║
║ │ Load │ ║
║ │ Balancer │ ║
║ └─────┬─────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────────────▼─────────────────────────────────────────────────────────┐ ║
║ │ API Gateway Layer │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ REST API │ │ GraphQL API │ │ WebSocket │ │ MCP Server │ │ ║
║ │ │ Server │ │ Server │ │ Server │ │ Handler │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────────────▼─────────────────────────────────────────────────────────┐ ║
║ │ Core Processing Layer │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ Code │ │ Vector │ │ Graph │ │ Cache │ │ ║
║ │ │ Parser │ │ Engine │ │ Processor │ │ Manager │ │ ║
║ │ │ (Tree-sit) │ │ (FAISS) │ │ (RocksDB) │ │ (Memory) │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────────────▼─────────────────────────────────────────────────────────┐ ║
║ │ Storage & Infrastructure │ ║
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ║
║ │ │ RocksDB │ │FAISS Indices│ │Memory Cache │ │ Git Repos │ │ ║
║ │ │(Persistent) │ │ (Vector) │ │ (In-Memory) │ │ (External) │ │ ║
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ ║
║ └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
```
## Component Dependency Tree
```ascii
codegraph-core
│
▼
┌─────────────┬──────────────┼──────────────┬─────────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
codegraph- codegraph- codegraph- codegraph- codegraph-
zerocopy concurrent git queue parser
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
codegraph- codegraph- codegraph- codegraph- codegraph- codegraph-
graph vector cache mcp lb api
│ │ │ │ │ │
└─────────────┼─────────────┼─────────────┼─────────────┴─────────────┘
│ │ │
└─────────────┼─────────────┘
│
▼
core-rag-mcp-server
```
## Data Flow Architecture (Sequence)
```ascii
Client API Auth Parser Vector Graph Cache External
│ │ │ │ │ │ │ │
│─────→ Request ──→│ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │←─── Validate ─────│ │ │ │ │
│ │ │ │ │ │ │ │
│ │──── Check Cache ───────────────────────────────→│ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ Cache Miss │ │ │ │ │
│ │─────→ Parse ──────│ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │─────→ Fetch Git ──────────────────────│
│ │ │ │ │ │ │ │
│ │ │ │←──── Source Code ─────────────────────│
│ │ │ │ │ │ │ │
│ │ │ │─────→ Embed ────→─│ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │─── OpenAI API ─────────────→│
│ │ │ │ │ │ │ │
│ │ │ │ │←─── Embeddings ─────────────│
│ │ │ │ │ │ │ │
│ │ │ │←─── Store Graph ←──────────→│ │
│ │ │ │ │ │ │ │
│ │←─── Store Cache ──────────────────────────────────────────│
│ │ │ │ │ │ │ │
│ │←─── Response ─────│ │ │ │ │
│ │ │ │ │ │ │ │
```
## Performance Optimization Layers
```ascii
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ Performance Optimization Stack ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌───────────── Request Level Optimizations ──────────────┐ ║
║ │ │ ║
║ │ HTTP Request → Load Balancer → Rate Limiting → │ ║
║ │ │ ║
║ │ Request Router → Response Compression → Streaming │ ║
║ │ │ ║
║ └────────────────────────┬───────────────────────────────┘ ║
║ │ ║
║ ┌───────────── Application Level Optimizations ────────────┐ ║
║ │ │ │ ║
║ │ ┌──── Memory Cache ──▼── Zero-Copy Serialization ─────┐ │ ║
║ │ │ │ │ ║
║ │ │ ┌── Memory Pooling ── Parallel Processing ─────┤ │ ║
║ │ │ │ │ │ ║
║ │ │ └── Object Reuse ── Work Distribution ─────────┤ │ ║
║ │ │ │ │ ║
║ │ └─────────────────────────────────────────────────────┘ │ ║
║ │ │ │ ║
║ └───────────────────────┼──────────────────────────────────┘ ║
║ │ ║
║ ┌───────────── Database Level Optimizations ───────────────┐ ║
║ │ │ │ ║
║ │ ┌── RocksDB Tuning ─▼─ FAISS Index Optimization ──────┐ │ ║
║ │ │ │ │ ║
║ │ │ • Column Families • IVF Quantization │ │ ║
║ │ │ • Bloom Filters • Product Quantization │ │ ║
║ │ │ • Batch Operations • Memory Mapping │ │ ║
║ │ │ • Compression • GPU Acceleration │ │ ║
║ │ │ │ │ ║
║ │ └─────────────────────────────────────────────────────┘ │ ║
║ │ │ │ ║
║ └──────────────────────┼───────────────────────────────────┘ ║
║ │ ║
║ ┌───────────── System Level Optimizations ──────────────────┐ ║
║ │ │ │ ║
║ │ • Tokio Async I/O ─▼─ Lock-Free Data Structures │ ║
║ │ • NUMA Awareness • DashMap, Arc-Swap │ ║
║ │ • Thread Pinning • Memory Leak Detection │ ║
║ │ • CPU Cache Opt. • Continuous Profiling │ ║
║ │ │ ║
║ └───────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
```
## Crate Dependency Matrix
```ascii
╔═════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ CodeGraph Crate Dependency Matrix ║
╠═════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Crate │ core │ zero │ graph│ vect │ cache│ parse│ queue│ git │ conc │ api │ mcp │ lb │ rag ║
╠════════════════════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼══════┼════════╣
║ codegraph-core │ ● │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - ║
║ codegraph-zerocopy │ ● │ ● │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - ║
║ codegraph-graph │ ● │ ● │ ● │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - ║
║ codegraph-vector │ ● │ ● │ ○ │ ● │ - │ - │ - │ - │ - │ - │ - │ - │ - ║
║ codegraph-cache │ ● │ ● │ ○ │ - │ ● │ - │ - │ - │ - │ - │ - │ - │ - ║
║ codegraph-parser │ ● │ - │ - │ - │ - │ ● │ - │ ○ │ ○ │ - │ - │ - │ - ║
║ codegraph-queue │ ● │ - │ - │ - │ - │ - │ ● │ - │ ● │ - │ - │ - │ - ║
║ codegraph-git │ ● │ - │ - │ - │ - │ ○ │ - │ ● │ - │ - │ - │ - │ - ║
║ codegraph-concurrent│ ● │ - │ - │ - │ - │ ○ │ ● │ - │ ● │ - │ - │ - │ - ║
║ codegraph-api │ ● │ - │ ● │ ● │ ● │ ● │ ● │ ○ │ ○ │ ● │ - │ - │ - ║
║ codegraph-mcp │ ● │ - │ ● │ ● │ - │ ● │ - │ - │ - │ - │ ● │ - │ - ║
║ codegraph-lb │ ● │ - │ - │ - │ - │ - │ - │ - │ - │ ● │ - │ ● │ - ║
║ core-rag-mcp-server│ ● │ - │ - │ ● │ - │ ● │ - │ - │ - │ - │ ● │ - │ ● ║
╚════════════════════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴══════┴════════╝
Legend:
● Direct dependency (required)
○ Optional dependency (feature-gated or weak)
- No dependency
Critical Paths:
1. API → Core → Graph → RocksDB (Data persistence)
2. API → Vector → FAISS (Similarity search)
3. Parser → Core → Concurrent (Code analysis)
4. MCP → API → All services (Protocol integration)
```
## Memory Layout Architecture
```ascii
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ CodeGraph Memory Architecture ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ Process Memory Space │ ║
║ └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
║ ┌───────────────┐ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────────────────┐ ║
║ │ Stack │ │ Heap │ │ Memory Mapped │ │ Zero-Copy Archives │ ║
║ │ │ │ │ │ Files │ │ │ ║
║ │ - Tokio │ │ - AST Nodes │ │ │ │ - rkyv Serialized │ ║
║ │ Tasks │ │ - Hash Maps │ │ - Large RocksDB │ │ Data Structures │ ║
║ │ - Function │ │ - Vector Data │ │ Files │ │ - Immutable Archives │ ║
║ │ Calls │ │ - Cache Entries│ │ - FAISS Indices │ │ - Direct Memory Access │ ║
║ │ - Local Vars │ │ - Buffers │ │ - Log Files │ │ - No Serialization Cost │ ║
║ └───────────────┘ └─────────────────┘ └──────────────────┘ └─────────────────────────────────────┘ ║
║ ↕ ↕ ↕ ↕ ║
║ 8-16 MB Dynamic Growth File-backed Controlled Layout ║
║ (GC via Rust) Virtual Memory (rkyv format) ║
║ ║
║ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
║ │ Optimization Strategies │ ║
║ ├─────────────────────────────────────────────────────────────────────────────────────────────────────┤ ║
║ │ 1. Arena Allocation │ Use bumpalo for temporary allocations during parsing │ ║
║ │ 2. Object Pooling │ Reuse expensive objects (parsers, buffers) │ ║
║ │ 3. Lock-Free Structs │ DashMap, ArcSwap for concurrent access without locks │ ║
║ │ 4. Memory Mapping │ Direct file access for large datasets │ ║
║ │ 5. Zero-Copy Serde │ rkyv for serialization without intermediate allocations │ ║
║ │ 6. Compression │ LZ4/Zstd for reducing memory footprint │ ║
║ │ 7. Lazy Loading │ Load AST nodes on-demand from storage │ ║
║ │ 8. Memory Profiling │ memscope-rs for leak detection in development │ ║
║ └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
```
## Technology Stack Layers
```ascii
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ CodeGraph Technology Stack ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌──────────────────────── Programming Language ──────────────────────────┐ ║
║ │ │ ║
║ │ Rust 2021 Edition │ ║
║ │ (MSRV 1.70, Current) │ ║
║ │ │ ║
║ └────────────────────────────────┬───────────────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Async Runtime ─────────────────────────┐ ║
║ │ │ │ ║
║ │ Tokio 1.39+ │ Futures 0.3 │ ║
║ │ (Task Scheduling, │ (Stream Processing, │ ║
║ │ I/O Operations) │ Async Combinators) │ ║
║ │ │ │ ║
║ └────────────────────────────────┼───────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Web Framework Stack ──────────────────────────┐ ║
║ │ │ │ ║
║ │ ┌─── Axum 0.7 ────┐ ┌─── Tower 0.4 ─────┐ ┌─── GraphQL ────┐ │ ║
║ │ │ Web Framework │ │ Middleware │ │ async-graphql │ │ ║
║ │ │ HTTP Routing │ │ Service Layer │ │ 7.0+ │ │ ║
║ │ └─────────────────┘ └───────────────────┘ └────────────────┘ │ ║
║ │ │ │ ║
║ └────────────────────────────────┼──────────────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Storage Layer ────────────────────────┐ ║
║ │ │ │ ║
║ │ ┌───── RocksDB 0.22 ──────┐ │ ┌───── FAISS 0.12 ──────┐ │ ║
║ │ │ Embedded Database │ │ │ Vector Similarity │ │ ║
║ │ │ Key-Value Storage │ │ │ Search Library │ │ ║
║ │ │ Column Families │ │ │ GPU Acceleration │ │ ║
║ │ └─────────────────────────┘ │ └───────────────────────┘ │ ║
║ │ │ │ ║
║ └────────────────────────────────┼──────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Language Parsing ─────────────────────────┐ ║
║ │ │ │ ║
║ │ Tree-sitter 0.25+ │ ║
║ │ │ │ ║
║ │ Rust │ Python │ JavaScript │ TypeScript │ Go │ Java │ C++ │ ║
║ │ 0.24 │ 0.23 │ 0.25 │ 0.23 │0.23│ 0.23 │0.23 │ ║
║ │ │ │ ║
║ └────────────────────────────────┼──────────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Observability ─────────────────────────┐ ║
║ │ │ │ ║
║ │ ┌─── Tracing 0.1+ ────┐ ┌─── Prometheus ──┐ ┌── Serde ─┐ │ ║
║ │ │ Structured Logging │ │ Metrics │ │JSON/TOML │ │ ║
║ │ │ Performance │ │ Collection │ │YAML/rkyv │ │ ║
║ │ └─────────────────────┘ └─────────────────┘ └──────────┘ │ ║
║ │ │ │ ║
║ └────────────────────────────────┼───────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── Concurrency ──────────────────────────┐ ║
║ │ │ │ ║
║ │ Rayon │ Crossbeam │ Parking Lot │ DashMap │ Arc-Swap │ ║
║ │ 1.8+ │ 0.8+ │ 0.12+ │ 6.0+ │ 1.7+ │ ║
║ │ │ │ ║
║ └────────────────────────────────┼──────────────────────────────┘ ║
║ │ ║
║ ┌──────────────────────── External APIs ───────────────────────┐ ║
║ │ │ │ ║
║ │ OpenAI API │ Git2 0.20+ │ ║
║ │ (Embeddings) │ (Repository Access) │ ║
║ │ │ │ ║
║ └────────────────────────────────┴─────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
```
## Deployment Architecture
```ascii
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ Production Deployment Topology ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌─────────────────┐ ║
║ │ Internet │ ║
║ │ Traffic │ ║
║ └─────────┬───────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────── Load Balancer Tier ───────────────────────────────────────────┐ ║
║ │ │ │ ║
║ │ ┌─────────────────────▼───────────────────┐ │ ║
║ │ │ Load Balancer (codegraph-lb) │ │ ║
║ │ │ Health Checks & Failover │ │ ║
║ │ └─────────────────────┬───────────────────┘ │ ║
║ └─────────────────────────────────────────── │ ────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────── Application Tier ─────────────────────────────────────────────┐ ║
║ │ ┌─────────────────────▼───────────────────┐ │ ║
║ │ │ │ │ │ ║
║ │ ┌─────────────▼──────────┐ ┌──────▼──────┐ ┌─────────▼──────────┐ │ ║
║ │ │ API Instance 1 │ │ Instance 2 │ │ API Instance N │ │ ║
║ │ │ (codegraph-api) │ │ │ │ (codegraph-api) │ │ ║
║ │ │ REST + GraphQL │ │ │ │ REST + GraphQL │ │ ║
║ │ └─────────────┬──────────┘ └──────┬──────┘ └─────────┬──────────┘ │ ║
║ └─────────────────────────────────────────── │ ────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────── Processing Tier ──────────────────────────────────────────────┐ ║
║ │ ┌─────────────────────▼───────────────────┐ │ ║
║ │ │ Message Queue (Redis) │ │ ║
║ │ │ Task Distribution │ │ ║
║ │ └─────────────────────┬───────────────────┘ │ ║
║ │ │ │ ║
║ │ ┌─────────────▼──────────┐ ┌──────▼──────┐ ┌─────────▼──────────┐ │ ║
║ │ │ Worker Node 1 │ │ Worker N 2 │ │ Worker Node N │ │ ║
║ │ │ Parser + Vector │ │ │ │ Parser + Vector │ │ ║
║ │ │ Processing │ │ │ │ Processing │ │ ║
║ │ └─────────────┬──────────┘ └──────┬──────┘ └─────────┬──────────┘ │ ║
║ └─────────────────────────────────────────── │ ────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────── Storage Tier ────────────────────────────────────────────────┐ ║
║ │ ┌─────────────────────▼───────────────────┐ │ ║
║ │ │ │ │ │ ║
║ │ ┌─────────────▼──────────┐ ┌──────▼──────┐ ┌─────────▼──────────┐ │ ║
║ │ │ RocksDB Cluster │ │FAISS Cluster│ │ Cache Cluster │ │ ║
║ │ │ (Sharded) │ │(Distributed)│ │ (Redis/Memcached) │ │ ║
║ │ │ Graph Storage │ │Vector Search│ │ Hot Data Cache │ │ ║
║ │ └────────────────────────┘ └─────────────┘ └────────────────────┘ │ ║
║ └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────────────── Monitoring Tier ─────────────────────────────────────────────┐ ║
║ │ ┌─────────────────────▼───────────────────┐ │ ║
║ │ │ │ │ │ ║
║ │ ┌─────────────▼──────────┐ ┌──────▼──────┐ ┌─────────▼──────────┐ │ ║
║ │ │ Prometheus │ │ Grafana │ │ Jaeger │ │ ║
║ │ │ (Metrics) │ │(Dashboards) │ │ (Tracing) │ │ ║
║ │ └────────────────────────┘ └─────────────┘ └────────────────────┘ │ ║
║ └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
```
---
*Generated by CodeGraph Documentation Specialist - ASCII Architecture Diagrams*