CodeAtlas — Architecture Diagrams for Any Codebase

A zoomable structural map of your codebase — like Google Maps for code. Auto-generated architecture diagrams, API sequence flows, dependency graphs, and code health reports for 30+ frameworks across 13 languages.

Navigate from service topology down to a single function. Live differential rendering highlights exactly what changed and where it ripples — across every layer, automatically.

Works with: Express, NestJS, Next.js, React, Django, FastAPI, Flask, Spring Boot, Laravel, Rails, Gin, Actix, ASP.NET, and 20+ more frameworks. Supports JavaScript, TypeScript, Python, Java, Kotlin, Go, Rust, C#, PHP, Ruby, Swift, C/C++.

How It Works

Install the extension. CodeAtlas auto-scans your workspace on launch and builds interactive architecture diagrams — no setup required.

View diagrams in your browser at http://localhost:7742 for the best experience — full screen, multi-monitor, DevTools access.

Getting Started

1. Install from the VS Code Marketplace
2. Diagrams build automatically on extension launch — no manual step needed
3. Click "Open in Browser" in the welcome panel or run CodeAtlas: Open in Browser
4. Sign in (free account) to view diagrams in the browser UI
5. Navigate: click any node to drill deeper through all 6 layers

Diagrams are built and synced without authentication. Sign-in is only required to view them.

Browser UI

CodeAtlas runs a local server at http://localhost:7742 that serves the full diagram viewer:

• Home page — workspace stats, quick-nav buttons, commands, sign-in
• Floating explorer sidebar — Services, Feature Areas, APIs, Files, Functions (toggle with ☰)
• Live updates — save a file in VS Code, browser updates in real time
• Auto-reconnect — if VS Code reloads, browser reconnects automatically

The port is configurable via codeatlas.browserPort setting (default: 7742).

The 6 Diagram Layers

L1 — System Design

See all your services and infrastructure at a glance. Services connect to databases, caches, queues, and each other. Polyglot services show all detected technologies.

L2a — Feature Areas

Zoom into a service to see its domain clusters — automatically detected using Louvain community detection with Jaccard stability matching.

L2b — API & Screen List

Browse every API endpoint, screen, navigation route, network call, and DI binding in a cluster. Filter by method, search by route or handler. Press / to search.

L3 — Sequence Diagram

See the full interaction flow for any API call — classes or files as participants, functions as messages. Cross-file resolution traces up to 8 hops deep.

L4 — File / Class Diagram

See a file's structure: imports, classes, functions, variables, and their dependency edges. Unused imports are dimmed (45% opacity). Class hierarchy shown.

L5 — Function Flow

Control flow inside a single function: if/else as diamonds, loops with dashed back-edges, try/catch/finally as three-way splits. Every branch gets diff highlighting.

Health Dashboard

Run Show Health Report to see dead functions, god files, cyclic dependencies, high coupling, and orphaned clusters — sorted by severity with color-coded borders.

Live Change Tracking

CodeAtlas watches your files. When you save, every diagram updates instantly — in both VS Code webview panels and the browser UI. Changes propagate upward through all 6 layers:

Diff Propagation Example

Colorblind-Safe Diff Indicators (WCAG 1.4.1)

Every change shows three independent visual channels — not just color:

Git Diff Mode

Compare any two commits visually across all diagram layers.

1. Click Compare Commits in the diagram header (or browser home page)
2. Pick a base and head commit
3. Navigate all layers with full diff coloring
4. Click Reset to return to live mode

Works with branches, tags, and pull requests.

Supported Languages & Frameworks

14 languages: JavaScript, TypeScript, Python, Java, Kotlin, Go, Rust, C, C++, C#, PHP, Ruby, Swift, Dart

Mobile & UI Frameworks

Mobile items appear in 4 sections: Screens, Navigation, Network, Dependencies — each with a platform badge.

Infrastructure auto-detected: PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ, Kafka, Celery, Sidekiq, Entity Framework, Eloquent, Room, CoreData, Realm, Firebase, and more.

Blast Radius Analysis

Right-click any function or run Impact Analysis from the sidebar/command palette to see:

• Will Break — direct callers that will fail
• Likely Affected — transitive callers up to 4 hops
• Review Required — modules that import your code but may not call it

Know what breaks before you ship.

AI Query Engine

Ask questions about your codebase in plain English. CodeAtlas highlights matching entities in blue across all 6 diagram layers.

How to use:

1. Click the Ask AI button (sparkle icon) in the toolbar, or press Cmd+Shift+Q
2. Type a question: "Show me the authentication flow", "How does payment connect to the database?", "What are the service controllers?"
3. Matching services, clusters, APIs, files, classes, and functions light up in blue
4. Navigate freely — highlights persist as you drill through layers
5. Hover any highlighted node to see WHY it matched (e.g., "API handler: POST /auth/login")
6. Click Clear or press Esc to remove all highlights

What gets highlighted:

• Services, feature clusters, and sub-cluster pills at L1/L2
• API endpoints with blue left-border at L2b
• Sequence diagram participants AND message arrows between them at L3
• File/function nodes AND connecting edges at L4/L5
• Config files and type definitions (even without functions)

Smart features:

• Zero results show suggested query examples to help you get started
• Progress indicators for long-running queries ("Analyzing codebase...", "Still working...")
• Results cached for 5 minutes — repeated queries return instantly
• Concurrent queries handled safely — only the latest result is displayed
• Works in both VS Code webview and standalone browser mode
• Set your API key inline from the browser (no VS Code command palette needed)

Setup: Enable LLM features in settings (codeatlas.llmNaming: true), then run CodeAtlas: Set LLM API Key to enter your OpenRouter, OpenAI, or Anthropic key. Free tier available via OpenRouter.

Commit Timeline Replay

Watch your codebase evolve commit-by-commit with a cinematic visual replay.

1. Click Timeline Replay (⏯) in the toolbar
2. Select a branch from the dropdown — commits load automatically
3. The merge-base with main/master is auto-detected and marked with a yellow badge
4. Click the start and end commits — the range highlights in blue
5. Click Start Replay — CodeAtlas builds diffs on-demand and auto-navigates:
   • L5 Flow — each changed function's control flow
   • L4 File — changed file dependency graphs
   • L3 Sequence — affected API interaction diagrams
   • L2a Feature — impacted feature clusters
   • L1 System — full system design with propagated diff colors

Playback controls:

• ⏸ Pause / ▶ Resume — freeze on any diagram to explore
• ⏭ Skip — jump to the next commit
• ■ Stop — end replay and return to live mode
• Speed slider — adjust from 0.5s to 5s per step

All diagrams use the full 3-channel WCAG diff colors (green/added, orange/modified, red/deleted) so you can see exactly what each commit changed.

Comments for AI Agents

Right-click any node in any diagram to add a comment. Comments are exported to comments.md in your workspace root with full architectural context — service, cluster, API, file, and function — so LLM agents can pick them up and understand exactly where to make changes.

Keyboard Shortcuts

Export

AI Assistant Integration (MCP)

CodeAtlas ships a standalone Model Context Protocol server that any MCP-compatible LLM client can consume. Pointing your agent at a workspace gives the model live structural answers — routes, sequences, diffs, impact analysis, architecture violations, full SQL access — without it reading the source files.

Why it matters: token economics

Measured against the test project, every query returns 5×–60× fewer tokens than the equivalent file-walking approach:

A 2.7B-class model with a 16K context window can now answer "what handles this route?" or "what breaks if I change X?" on a 1k-file codebase using one MCP call instead of dozens of file reads. The retrieval problem moves from the LLM to the framework.

What's exposed (25 tools)

Context packs: list_entrypoints, list_entrypoints_paged, get_entrypoint_pack, get_feature_pack, pre_edit_brief, get_function_source, trace_call_path Diff & impact: get_diff_summary, get_api_surface_diff, get_impact_of_change, get_impact_analysis, get_function_dependencies Search & query: search_workspace (weighted reverse index), query_snapshot (read-only SQL), describe_snapshot_schema Health & rules: get_health_report, list_architecture_violations, get_coverage_overlay Workspace: get_workspace_status, find_similar_entities, list_saved_views, compare_workspaces Interop: export_openapi_spec, export_function_calling_spec, summarise_payload

Plus five MCP resources: codeatlas://workspace/{microservices, apis, features, entrypoints, diff-summary}.

Quick setup — five clients

The binary lives inside the installed extension at ~/.vscode/extensions/codeatlaslive.codeatlas-live-<version>/dist/mcp-server.js. Point your client at it with the workspace path as the single argument.

Claude Code — claude mcp add codeatlas -s user -- node ~/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js /absolute/path/to/your/repo (or edit ~/.claude.json directly).

Cursor — Cursor → Settings → MCP → Add Server:

{
  "mcpServers": {
    "codeatlas": {
      "command": "node",
      "args": [
        "/Users/<you>/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

VS Code (1.103+, with Copilot Chat agent mode) — drop into .vscode/mcp.json at the workspace root:

{
  "servers": {
    "codeatlas": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${userHome}/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js",
        "${workspaceFolder}"
      ]
    }
  }
}

Codex CLI — append to ~/.codex/config.toml:

[mcp_servers.codeatlas]
command = "node"
args = [
  "/Users/<you>/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js",
  "/absolute/path/to/your/repo",
]

Gemini CLI / Antigravity — ~/.gemini/settings.json (or .gemini/settings.json in the project root):

{
  "mcpServers": {
    "codeatlas": {
      "command": "node",
      "args": [
        "/Users/<you>/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

After registering, reload your client and the 25 tools appear alongside its built-ins.

A wrapper for any-workspace use

If you want one config that works in any project (so you don't have to update the workspace path each time), drop this onto your $PATH:

#!/usr/bin/env bash
# /usr/local/bin/codeatlas-mcp
exec node ~/.vscode/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js "$PWD"

Then your client configs become command: codeatlas-mcp with no args — workspace is wherever you launched the client.

Self-init: no VS Code required

The MCP server bootstraps the snapshot itself when launched against a workspace that has no .codeatlas/state.db yet — scans the workspace, classifies it as a codebase (or returns status: 'not_a_codebase' for docs-only / empty dirs), runs the full indexing pipeline, and starts a file watcher to keep state current. You can register the MCP server against a brand-new repo and the LLM gets working answers within seconds — no VS Code launch required.

Concurrent VS Code + MCP

When both run on the same workspace, MCP wins write ownership. The extension watches for .codeatlas/.mcp-preempt, yields its lock when an MCP process requests it, disables auto-update for the session, and shows a recovery toast. Close+reopen the workspace once the MCP process exits to reclaim writes. No silent races on state.db.

Commands

Settings

Privacy & Security

• Your code stays local. All analysis runs on your machine.
• Browser UI is localhost-only. Server binds to 127.0.0.1 with WebSocket origin validation.
• LLM features are opt-in. Only short snippets are sent, and sensitive values are filtered before transmission.
• Sensitive data never persisted. Passwords, tokens, and connection strings are scrubbed from the state file.
• CSP enforced. Webview uses a nonce-based Content Security Policy.
• Atomic writes. State file is written with a tmp-file-and-rename pattern; a schema-version header lets the extension cleanly rebuild after upgrades.

Telemetry

CodeAtlas sends anonymous product-usage events so we can understand which features are used and debug issues across editors and platforms.

What we collect:

• Lifecycle events — first install, update, launch (extension version, days-since-install).
• Interaction events — which features are used: AI Review, Ask AI, Timeline Replay, Git Diff, Initialize, Resync, Sign-In.
• Editor context — editor name (e.g. Visual Studio Code, Cursor, VSCodium), uri scheme, distribution channel (Marketplace vs Open VSX), platform, architecture, remote-mode kind (WSL / SSH / dev-container).
• Anonymous device ID — a per-device hash provided by VS Code (vscode.env.machineId). Not tied to your real identity unless you sign in.
• User account when signed in — your email and a generated user identifier, only after explicit sign-in. Used to associate device events with your account.
• Error and notification events — feature failures, parse errors, and warning toasts shown.

What we do NOT collect:

• Your source code or any file content
• File names or directory structure
• Git history, commit messages, branch names, or repository URLs
• Search queries or natural-language prompts (only their length is recorded)
• LLM responses or AI Review findings text
• Any value entered into a password field, API key, or secret

How to opt out:

• Stay signed out — events are then attributed only to an anonymous device hash with no email or user identifier attached.
• Block api2.amplitude.com at the firewall (or disable network access for the VS Code extension host) for a complete opt-out.

Why CodeAtlas?

Supported Frameworks & Languages

JavaScript/TypeScript: Express, NestJS, Next.js (App + Pages Router), Nuxt, Remix, SvelteKit, Hono, tRPC, GraphQL, gRPC Python: Django, Django REST Framework, FastAPI, Flask, Starlette Java/Kotlin: Spring Boot, Spring WebFlux, Micronaut, JAX-RS, Ktor Go: Gin, Echo, Chi, Fiber, net/http Rust: Actix, Axum, Rocket C#: ASP.NET Core, Minimal API PHP: Laravel, Symfony Ruby: Rails, Sinatra Swift: Vapor Mobile: Android (Jetpack Compose, Hilt, Room), iOS (SwiftUI, UIKit), React Native, Flutter/Dart, Expo Router

Infrastructure detection: MongoDB, PostgreSQL, MySQL, Redis, RabbitMQ, Kafka, Celery, Sidekiq, Prisma, Sequelize, and more.

Quality

Every release is validated against 33 real-world framework repos covering Express, NestJS, Fastify, Next.js, Nuxt, Remix, SvelteKit, tRPC, Apollo, Django, FastAPI, Flask, Spring, Ktor, Gin, Echo, Chi, Fiber, Laravel, Symfony, Rails, Sinatra, Actix, Axum, Rocket, ASP.NET, Vapor, plus mobile (React Native, Flutter, Jetpack Compose, SwiftUI). The suite asserts diagram correctness layer-by-layer (L1–L5), output stability across runs, and a per-repo performance budget — so an upgrade never silently regresses detection on your stack.

Feedback & Support

• Report issues: GitHub Issues
• Documentation: codeatlas.live

License

See LICENSE.md