Codebase Map

The Codebase Map provides a bird's-eye view of your repository, showing communities, their relationships, and overall statistics.

URI Pattern

map://{repository}

Response Format

interface CodebaseMapResponse {
  repository: string;
  stats: MapStats;
  communities: CommunityListItem[];
  cross_flows: CrossFlowItem[];
}

interface MapStats {
  communities: number;
  symbols: number;
  processes: number;
}

interface CommunityListItem {
  id: string;
  label: string;
  symbols: number;
  cohesion: number;          // 0-1, higher is more cohesive
  key_symbols: string[];     // Most important symbols
  entry_points: string[];    // Entry point function names
}

interface CrossFlowItem {
  from: string;             // Source community label
  to: string;               // Destination community label
  calls: number;            // Number of cross-community calls
}

Example Response

{
  "repository": "my-app",
  "stats": {
    "communities": 42,
    "symbols": 1337,
    "processes": 156
  },
  "communities": [
    {
      "id": "comm_1",
      "label": "Authentication",
      "symbols": 85,
      "cohesion": 0.92,
      "key_symbols": ["authenticateUser", "validateToken", "createSession"],
      "entry_points": ["login", "signup", "refreshToken"]
    },
    {
      "id": "comm_2",
      "label": "DataAccess",
      "symbols": 120,
      "cohesion": 0.88,
      "key_symbols": ["queryDatabase", "executeTransaction", "cacheResults"],
      "entry_points": ["getUserById", "saveUser", "deleteUser"]
    }
  ],
  "cross_flows": [
    {
      "from": "Authentication",
      "to": "DataAccess",
      "calls": 47
    },
    {
      "from": "API",
      "to": "Authentication",
      "calls": 89
    }
  ]
}

Understanding the Map

Stats

Overall repository metrics:

communities: Total code communities detected
symbols: Total code symbols (functions, classes, etc.)
processes: Total execution flows identified

Communities

Each community represents a cohesive group of related code.

Key fields:

cohesion: Higher values (0.8+) indicate tightly related code
key_symbols: Most central/important symbols in the community
entry_points: Functions that serve as entry points from other communities

Cross-Flows

Show how communities interact:

from -> to: Direction of calls
calls: Number of cross-community function calls

High call counts indicate strong dependencies between communities.

Use Cases

1. Initial Exploration

Get oriented in a new codebase:

GET map://my-app

Identify:

Main communities
Highly cohesive areas
Cross-community dependencies

2. Find Relevant Communities

Locate communities by name:

const map = await getResource('map://my-app');
const authCommunity = map.communities.find(c =>
  c.label.toLowerCase().includes('auth')
);

3. Analyze Architecture

Understand system structure:

const map = await getResource('map://my-app');

// Find highly connected communities
const connections = map.cross_flows
  .reduce((acc, flow) => {
    acc[flow.from] = (acc[flow.from] || 0) + 1;
    return acc;
  }, {});

// Communities with many outgoing connections
console.log(Object.entries(connections).sort((a, b) => b[1] - a[1]));

4. Identify Architectural Issues

Find potential problems:

const map = await getResource('map://my-app');

// Low cohesion communities (may need refactoring)
const lowCohesion = map.communities.filter(c => c.cohesion < 0.5);

// Highly coupled communities (many cross-flows)
const coupledPairs = map.cross_flows.filter(f => f.calls > 100);

Best Practices

1. Start Here

Always begin exploration with the map:

GET map://my-app

2. Look for High Cohesion

Communities with cohesion > 0.8 are well-designed:

const wellDesigned = map.communities.filter(c => c.cohesion > 0.8);

3. Use Entry Points

Entry points are the best place to start understanding a community:

const community = map.communities.find(c => c.label === "Authentication");
console.log("Start with:", community.entry_points);

4. Follow Cross-Flows

Understand dependencies by following cross-flows:

// What does Authentication depend on?
const authDeps = map.cross_flows
  .filter(f => f.from === "Authentication")
  .map(f => f.to);

Community Detail - Deep dive into communities
Process Trace - Follow execution flows
Code Exploration - Full workflow

On this page