Agent Skills

analyze-yii2-project

CodeCompass - Enterprise-grade code intelligence platform (public filtered version)

Installation
CLI
npx skills add https://github.com/pearlthoughts/codecompass --skill analyze-yii2-project

Install this skill with the CLI and start using the SKILL.md workflow in your workspace.

Last updated 4/23/2026

CodeCompass

Enterprise-grade code intelligence platform for understanding, modernizing, and evolving legacy systems

NestJS
TypeScript
PostgreSQL
Weaviate
License

What is CodeCompass?

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.

The Problem

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.

The Solution

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

Impact & Outcomes

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

Quick Start

Prerequisites

  • Node.js 18+
  • Docker & Docker Compose
  • pnpm (or npm/yarn)

Installation

# 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

Running Your First Analysis

1. Analyze a Legacy Codebase

# 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

2. Extract Business Capabilities from Database

# 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

3. Integrate Runtime Data

# 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

4. Generate Requirements Documentation

# 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)

5. Query and Explore

# 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

Use Cases

✅ 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

⚠️ Also useful for:

  • Technical debt assessment
  • Architecture documentation
  • Developer onboarding

❌ Not for:

  • Daily development tasks (use Claude Code, Cursor, Copilot)
  • New project development
  • Small refactoring (<30 files)

Architecture

┌─────────────────────────────────────────────────┐
│  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.

Documentation

📚 Getting Started

🎯 Understanding Value

🏗️ Architecture & Implementation

🧪 Development

Testing

# Run tests
pnpm test

# Test with coverage
pnpm test:coverage

# Integration tests
pnpm test:integration

# Type checking
pnpm typecheck

Configuration

# 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)

Integration with AI Editors

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.

FAQ

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.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# 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

Support & Community

License

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

⚠️ Only Restriction:
Cannot repackage and sell as a competing SaaS product (e.g., offering "CodeCompass-as-a-Service"). Use it, don't resell it.

See LICENSE for complete terms. Learn more about FSL at fsl.software.

Acknowledgments

Built with insights from:

  • Continue.dev - Multi-source retrieval patterns
  • Aider - PageRank code relevance
  • Plandex - Multi-tier context management
Built with ❤️ by PearlThoughts PearlThoughts