Enterprise-grade code intelligence platform for understanding, modernizing, and evolving legacy systems
CodeCompass is a knowledge synthesis platform that transforms how you understand legacy systems. It analyzes code, databases, runtime behavior, and (planned) documentation sources to provide comprehensive system intelligence. Unlike AI code editors that assist with daily development, CodeCompass solves the strategic challenge of understanding and modernizing large-scale systems.
Think of it as: Archaeological intelligence for your codebase—revealing what the system does, why it was built that way, and how to evolve it safely.
Legacy systems are knowledge vaults locked by time:
- Lost tribal knowledge: Original developers gone, decisions undocumented
- Scattered information: Business logic buried across code, emails, wikis, tickets, and meeting notes
- Manual archaeology: 2-3 months to reverse engineer requirements
- High-risk migrations: Unknown dependencies and missing requirements lead to failure
- Innovation blocked: Can't add features to fragile, undocumented systems
The real cost: Not maintenance—it's the opportunity cost of blocked innovation.
CodeCompass provides systematic analysis and intelligence:
- Deep code analysis: AST parsing, dependency graphs, complexity metrics
- Multi-source synthesis: Correlate code with databases, runtime profilers, and (planned) documentation sources
- Automated requirements extraction: Generate comprehensive documentation in weeks instead of months
- Migration intelligence: Data-driven roadmaps with pattern libraries (Yii2→NestJS, extensible to other frameworks)
- Runtime correlation: Prioritize by actual usage—migrate critical paths first, skip dead code
- Enterprise governance: Multi-project workspaces with shared knowledge and audit trails
Time savings:
- Requirements extraction: Weeks instead of 2-3 months manual archaeology
- System analysis: Days instead of weeks of exploration
- Migration planning: Data-driven roadmaps vs. guesswork
Risk reduction:
- Identify dependencies before migration starts
- Discover critical business logic that would otherwise be missed
- Prioritize by actual production usage, not assumptions
Cost impact (conservative):
- Analysis phase: $30k-$60k saved in archaeology time
- Migration efficiency: 30-40% faster through knowledge sharing
- Total project: 8-10 months vs. 12-18 months traditional approach
Strategic value:
- Build institutional knowledge that persists beyond individual developers
- Unlock innovation by making systems understandable and evolvable
- Compound learning: Pattern library grows with each project
- Node.js 18+
- Docker & Docker Compose
- pnpm (or npm/yarn)
# Clone repository
git clone https://github.com/senguttuvang/codecompass-public.git
cd codecompass-public
# Start infrastructure (PostgreSQL, Weaviate, Redis)
docker-compose up -d
# Install dependencies
pnpm install
# Run database migrations
pnpm run migration:run
# Start application
pnpm start:dev
# Application running at http://localhost:3002
# API Docs: http://localhost:3002/api# Comprehensive Yii2 framework analysis
pnpm run cli -- analyze:yii2 /path/to/legacy-app
# Extracts:
# - Dependency graphs
# - Business domains
# - Code complexity
# - Architecture patterns
# - Dead code identification# Analyze database schema to understand business model
pnpm run cli -- analyze-capabilities \
--database production_db \
--project-name "Legacy System"
# Outputs:
# - Business capabilities (User management, Payment processing, etc.)
# - Table relationships and dependencies
# - Data model documentation# Import production profiler data to identify hot paths
pnpm run cli -- profiler:import yii2-debug-export.json
# Then query usage statistics
pnpm run cli -- query:hot-paths --threshold 1000
# Prioritize migration by ACTUAL usage, not guesswork# Automated requirements extraction
pnpm run cli -- requirements:extract \
--source /path/to/legacy-app \
--output requirements.md
# Generates comprehensive doc with:
# - Business workflows
# - Business rules and validation
# - Dependencies (internal + external)
# - Domain boundaries (DDD)# Natural language queries
pnpm run cli -- nl-query "How does authentication work?"
# Semantic search
pnpm run cli -- search:semantic "user authentication flow"
# Analyze specific patterns
pnpm run cli -- analyze:yii2 /path/to/legacy-app✅ Perfect for:
- Legacy system archaeology: Reverse engineer undocumented systems
- Framework migrations: Yii2→NestJS (others extensible via adapters)
- M&A due diligence: Rapid codebase assessment
- Microservices decomposition: DDD boundary detection (planned)
- Knowledge synthesis: Multi-source system understanding
- Enterprise governance: Multi-project code intelligence
- Technical debt assessment
- Architecture documentation
- Developer onboarding
❌ Not for:
- Daily development tasks (use Claude Code, Cursor, Copilot)
- New project development
- Small refactoring (<30 files)
┌─────────────────────────────────────────────────┐
│ NestJS Application (TypeScript) │
│ ├─ Framework Adapters (Yii2, Laravel, etc.) │
│ ├─ AST Analyzers (ts-morph + tree-sitter) │
│ ├─ Dependency Analyzer │
│ ├─ Business Domain Extractor │
│ └─ Migration Orchestrator │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Storage Layer │
│ ├─ PostgreSQL (structured data) │
│ ├─ Weaviate (semantic vectors & embeddings) │
│ └─ Redis (job queue) │
└─────────────────────────────────────────────────┘
Key principles:
- Plugin architecture (framework-agnostic core)
- Multi-source synthesis by design
- API-first (RESTful + planned MCP server)
- Type-safe (TypeScript strict mode)
- Extensible (custom analyzers, frameworks, data sources)
See Architecture & AI Context Integration for details.
- Quick Start Guide - Get running in 1 hour
- 1 Week POC Guide - Prove value quickly
- Example Analysis - Real-world Yii2 project
- vs AI Editors ⭐ Start here!
- Executive Summary - High-level overview
- Technical Deep Dive - Comprehensive technical overview
- Architecture & AI Context - System design & integration
- DDD Architecture Review - Domain-driven design improvements
- Framework Metamodel Design - Pattern language architecture
- Semantic Search - Vector search implementation
- PageRank Implementation - Code relevance ranking
- AI Codebase Understanding - AI-powered analysis strategies
- Bootstrapping Guide - Develop CodeCompass with CodeCompass
- Bootstrap Quick Reference - Daily workflow cheatsheet
- Contributing
- FAQ
# Run tests
pnpm test
# Test with coverage
pnpm test:coverage
# Integration tests
pnpm test:integration
# Type checking
pnpm typecheck# Copy environment template
cp .env.example .env
# Key settings
CODECOMPASS_WEAVIATE_URL=http://localhost:8081
CODECOMPASS_POSTGRES_URL=postgresql://user:pass@localhost:5432/compass
CODECOMPASS_REDIS_URL=redis://localhost:6379
PORT=3002
# Embedding model (local or API)
EMBEDDING_MODEL=mxbai-embed-large # Local via Ollama (recommended)CodeCompass complements (doesn't replace) AI code editors:
Workflow:
1. CodeCompass analyzes codebase (strategic intelligence)
2. Developer codes in Cursor/Claude Code (tactical execution)
3. AI editor queries CodeCompass API for enriched context
4. CodeCompass tracks progress and validates changes
Result: Strategic intelligence + tactical execution
See AI Context Integration for API details.
Q: Why not just use Claude Code or Cursor? A: They're excellent for daily development. CodeCompass solves a different problem: enterprise knowledge synthesis requiring multi-source analysis, system archaeology, and strategic planning. See detailed comparison.
Q: What frameworks are supported? A: Currently specialized for Yii2→NestJS with framework-agnostic core. Add Laravel, Spring Boot, Django via plugin adapters.
Q: Can I use it for non-migration projects? A: Absolutely! CodeCompass excels at legacy reverse engineering, technical debt assessment, M&A due diligence, architecture documentation, and knowledge transfer.
Q: What's the cost? A: Open source (MIT). Infrastructure: $500-1000/month cloud hosting. ROI: 6-40x over 12 months (typical savings: $150-300k per project).
See Full FAQ for more questions.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
# Clone repo
git clone https://github.com/senguttuvang/codecompass-public.git
cd codecompass-public
# Install dependencies
pnpm install
# Start infrastructure
docker-compose up -d
# Run in watch mode
pnpm start:dev
# Run tests
pnpm test- Documentation: /docs
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Functional Source License (FSL) 1.1 - Converts to MIT License on November 25, 2026
This project is licensed under the Functional Source License (FSL) 1.1, which converts to MIT on November 25, 2026.
✅ Unlimited Commercial Use Allowed:
- Use in production environments without restrictions
- Consulting firms can use freely for client projects
- Modify, fork, and redistribute the codebase
- No usage fees or attribution requirements
- Deploy at any scale for internal or client purposes
See LICENSE for complete terms. Learn more about FSL at fsl.software.
Built with insights from:
- Continue.dev - Multi-source retrieval patterns
- Aider - PageRank code relevance
- Plandex - Multi-tier context management
