CodeCohesion

🚀 Live Demo | Explore React, Gource, cBioPortal, and more!

Interactive 3D timeline showing repository evolution with cohesion analysis

Open-source 3D visualization tool for analyzing code cohesion and architectural evolution. Explore your codebase as an interactive solar system and watch it evolve over time to understand structure, detect bounded contexts, and identify coupling patterns.

What makes CodeCohesion unique:

• 🌍 3D Spatial Visualization - Solar system metaphor for intuitive architecture understanding
• ⏱️ Live Timeline Playback - Watch your codebase evolve commit-by-commit
• 🔗 Cohesion Analysis - Detect bounded contexts through temporal coupling
• 🎯 DDD-Focused - Built for Domain-Driven Design and monolith decomposition
• 🚀 Open Source - Free, transparent, extensible
• 🌐 Browser-Based - No installation, runs anywhere

Inspired by: Gource for evolution visualization, CodeScene for behavioral code analysis.

---

📘 DDD & Bounded Context Detection Want to see how CodeCohesion can detect bounded contexts and analyze domain language? Check out our comprehensive vision document: DDD Vision

Covers: Temporal coupling analysis • Ubiquitous language detection • Vocabulary clustering • Connascence of name • AST-based semantic analysis

---

📋 Table of Contents

• Why Use This?
• Features
• Quick Start
• Requirements
• Project Structure
• Design Decisions
• Roadmap
• DDD Vision & Analysis Plans
• Development
• Troubleshooting
• Contributing
• License

🤔 Why CodeCohesion?

Problem: Understanding code architecture and cohesion is hard. Where are your bounded contexts? Which files are tightly coupled? How did your architecture evolve to its current state?

Solution: CodeCohesion turns git history into an interactive 3D visualization that reveals:

• 🔗 Cohesion Patterns - Which files belong together (bounded contexts)
• 🔥 Coupling Hotspots - Files that change together frequently
• 🏗️ Architecture - Hierarchical structure at a glance
• ⏳ Evolution - How your codebase grew and changed over time
• 👥 Ownership - Who works on what parts of the code

Use Cases:

• 📚 DDD & Bounded Contexts - Discover natural domain boundaries through cohesion
• 🔍 Monolith Decomposition - Identify where to split based on temporal coupling
• 🎓 Onboarding - Give new team members a visual architectural tour
• 📽️ Retrospectives - Watch timeline playback of how features evolved
• 💰 Technical Debt - Find legacy hotspots and coupling issues

🎯 Project Goals

Visualize code repositories to understand:

• Repository structure - Hierarchical organization at a glance
• File relationships - Parent-child connections and directory ownership
• Code distribution - File sizes mapped to lines of code
• Recent activity - See which files were recently modified
• Team ownership - Who last touched each file
• File coupling - Which files change together in commits

✨ Current Features

Core Visualization

• Solar System Layout - Directories as planets, files as moons orbiting in 360° rings
• Hierarchical Focus Mode - Drill down into directories while maintaining context
• Adaptive Sizing - File sphere size represents lines of code, directories sized by total LOC
• Smart Spacing - Automatic layout prevents overlap using square-root scaling

Interactive Exploration

• Orbit Controls - Left-click drag to rotate, right-click to pan, scroll to zoom
• Click Navigation - Click directories to focus, click again to navigate back up
• Hover Highlighting - Highlights files/directories and their ancestors on hover
• Smooth Camera - Stable camera framing without disorienting resets

Git Metadata Visualization

Multiple Color Modes

Visualize the same codebase through different analytical lenses:

1. File Type (default) - 50+ file extensions with semantic color grouping
2. Last Modified - Adaptive time buckets showing recent changes
   • Active repos: 7 time intervals (last week → 1-2 years)
   • Stale repos: Percentile-based intervals with year ranges
3. Author - Consistent hash-based colors per contributor
4. Churn (Lifetime Commits) - Heatmap showing frequently modified files
5. Contributors (Lifetime) - Number of unique contributors per file
6. File Age - When files were first created (new → legacy)
7. Recent Activity (90 days) - Lines changed in recent window
8. Code Stability - Average lines changed per commit (stable → volatile)
9. Recency - Days since last modification (hot → cold)
10. Lines of Code - File size distribution with percentile-based buckets (small → large)
11. Coupling Clusters - Files grouped by temporal coupling (change together)

React repository (6,784 files) colored by commit frequency - red spheres indicate high-churn hotspots that may need refactoring

<details> <summary>📸 More Color Mode Examples</summary>

cBioPortal repository with Recent Activity (90 days) coloring - shows which files have been actively developed

Same cBioPortal repository with Last Modified (Relative) coloring - reveals code age distribution from newest (green) to legacy (red)

</details>

Intelligent Directory Coloring

• Directories show the dominant color of their files based on file count
• Works for all color modes (not just file type)
• Recursive aggregation - includes all nested files
• Updates when switching color modes

Commit Siblings Highlighting

• Click any file with "Highlight Commit" enabled
• See all files changed in the same commit (at HEAD)
• Dramatic visual highlighting with bright yellow glow
• Connection lines from highlighted files to parent directories
• Toggle to clear highlighting

Coupling Cluster Analysis

• Temporal coupling detection - Files that frequently change together
• 3D floating cards - Hover over clustered files to see cluster details
• Scrollable file lists - View all files in each coupling cluster
• Color-coded visualization - Each cluster gets a unique color

Timeline V2 - Repository Evolution Playback

Watch your repository evolve commit-by-commit:

• Full commit history - Process all commits, not just HEAD
• VCR controls - Play, pause, step forward/backward through history
• Live metrics - Repository stats update as you navigate commits
• Commit details - See file changes (Files: +N ~N -N), LOC changes, merge commits
• Color-coded highlights - Green connection lines for additions, orange for modifications
• Adaptive speed - Playback from 1x to 1000x speed
• Delta reconstruction - Gource-style visualization rebuilding the tree at each commit

UI Features

• Live Repository Stats Panel - File count, LOC, directory count, max depth, top 5 languages (updates in Timeline V2)
• Dynamic Legend - Updates based on color mode (file types, time ranges, or authors)
• Info Panel - Click files/directories to see detailed metadata
• Repository Switcher - Load different analyzed repos without page reload
• Label Toggle - "Always On" or "Hover Only" for directory labels
• Tooltips - Quick stats on hover
• Collapsible Panels - Click headers to expand/collapse

📋 Requirements

• Node.js ≥ 18.0
• npm ≥ 9.0
• Git (for repository analysis)
• Modern browser with WebGL support (Chrome, Firefox, Safari, Edge)

Tested On:

• macOS 13+ (Apple Silicon & Intel)
• Linux (Ubuntu 22.04+)
• Windows 10/11 (WSL2 recommended)

🚀 Quick Start

1. Install

npm install        # Installs all packages via npm workspaces

2. Start the App

npm run dev        # Starts viewer + API in parallel via Turborepo

Open http://localhost:3000

3. Analyze a Repository

Use the Analyze panel in the viewer UI:

1. Enter a local path (/path/to/your/repo) or a GitHub URL
2. Select a processing mode (HEAD snapshot, Timeline V1/V2, or Coupling)
3. Click Analyze — progress streams in real-time via SSE
4. When complete, the visualization loads automatically

The API runs the processor as a library and writes output directly to the viewer's data directory — no manual file copying needed.

Alternatively, you can use the CLI:

cd processor && npm run dev -- /path/to/your/repo           # HEAD snapshot
cd processor && npm run dev -- /path/to/your/repo --timeline    # Timeline V1
cd processor && npm run dev -- /path/to/your/repo --full-delta  # Timeline V2
cd processor && npm run coupling -- /path/to/your/repo          # Coupling analysis
cp processor/output/*.json viewer/public/data/                  # Copy to viewer

Example repositories tested:

• Gource (120 files, 28K LOC)
• React (6,784 files, 918K LOC)

4. Explore Your Codebase

Mouse Controls:

• Left-click + drag - Rotate camera around the visualization
• Right-click + drag - Pan the