walkthrough.md

Codebase Intelligence Graph — System Walkthrough & Architecture Guide

Welcome to the comprehensive walkthrough of the Codebase Intelligence Graph! This document explains what we built, how it works under the hood, why there is a backend server, and how language support functions.

---

1. What Have We Built So Far?

We have constructed a full-stack Abstract Syntax Tree (AST) Architecture Explorer that statically visualizes and analyzes any local TypeScript codebase without uploading files.

🌟 Key Capabilities at a Glance:

1. In-Memory AST Codebase Analyzer: Parses .ts and .tsx source code directly into AST nodes using ts-morph, resolves internal module import/export links, and respects tsconfig.json path aliases (@/*).
2. Multi-Layer node_modules Exclusion: Rigorously excludes third-party packages, declaration files (.d.ts), and build artifacts (dist/, .next/, build/).
3. Symbol & Function Discovery: Extracts internal declarations from every file: React Components, Custom Hooks, Helper Functions, TypeScript Interfaces, Type Aliases, and Classes, badging their export visibility.
4. Automated Dagre Flow Layout: Positions hundreds of connected files automatically into clean Top-to-Bottom (TB) or Left-to-Right (LR) hierarchical ranks.
5. Interactive React Flow Canvas: Interactive canvas with zoom, pan, minimap, category color coding, and reactive neighborhood glowing focus.
6. Visual Folder Browser & Native OS Picker: In-app filesystem directory browser with codebase detection badges plus native Windows Explorer dialog integration (0 file uploads).
7. Topological Sort Engine: Kahn’s algorithm computing both:
   • Execution Flow (Entrypoint $\rightarrow$ Leaves, default): Runtime boot path from index.tsx down to utilities.
   • Build Order (Leaves $\rightarrow$ Entrypoint): Compilation prerequisite sequence from types up to the app shell.
8. Fault-Tolerant Cycle-Breaking: Automatically bypasses circular dependency deadlocks so 100% of the codebase remains ordered and visible, with offending cyclic loops isolated in pulsing crimson red.
9. Interactive Canvas Flow Player: Floating player docked at the bottom of the canvas that steps through or auto-plays the resolution of the codebase node-by-node.
10. Zero-Friction npx repotrace Production CLI: Standalone executable package that runs on an isolated port (default 4242), automatically avoids port collisions, serves the compiled SPA client, and launches the browser to analyze any local directory with zero setup.

---

2. End-to-End Pipeline: How It Works

flowchart TD
    subgraph Client ["Frontend (React + Vite + React Flow)"]
        UI[User clicks Browse or inputs Path]
        TopBar[TopBar Toolbar]
        Canvas[React Flow Graph Canvas]
        Drawer[Topo Order Drawer]
        Player[Canvas Flow Player]
        Dagre[Dagre Auto-Layout Engine]
        TopoEngine[Client Topo Sort & Cycle Breaker]
    end

    subgraph Server ["Backend (Node.js + Express + ts-morph)"]
        API["Express API (Port 3001)"]
        Explorer["Filesystem Explorer (/api/explore)"]
        WinDialog["PowerShell Windows Dialog (/api/browse-folder)"]
        Analyzer["CodebaseAnalyzer (server/analyzer.ts)"]
        TSMorph["ts-morph Project AST Engine"]
        Glob["fast-glob Discovery"]
    end

    UI --> TopBar
    TopBar -->|POST /api/analyze path| API
    TopBar -->|POST /api/browse-folder| WinDialog
    TopBar -->|GET /api/explore| Explorer
    API --> Analyzer
    Analyzer --> Glob
    Analyzer --> TSMorph
    TSMorph -->|AST Parsing & Symbol Extraction| Analyzer
    Analyzer -->|JSON: raw nodes, edges, symbols| API
    API -->|GraphPayload| Client
    Client --> Dagre
    Client --> TopoEngine
    Dagre --> Canvas
    TopoEngine --> Drawer
    TopoEngine --> Player
    Player -->|Highlight active step| Canvas

Loading

---

3. What is the Responsibility of the Backend Server?

The Real JSON Response from the Backend:

{
  "success": true,
  "rootPath": "C:/Users/ASUS/Desktop/ProjectX/example-repo",
  "analyzedAt": "2026-08-29T10:53:28.123Z",
  "totalFiles": 10,
  "totalDependencies": 12,
  "nodes": [
    {
      "id": "src/components/Chat.tsx",
      "name": "Chat.tsx",
      "path": "src/components/Chat.tsx",
      "ext": ".tsx",
      "metrics": {
        "incomingCount": 1,
        "outgoingCount": 2
      },
      "symbols": [
        {
          "name": "Chat",
          "kind": "component",
          "isExported": true
        },
        {
          "name": "ChatProps",
          "kind": "interface",
          "isExported": false
        }
      ]
    },
    {
      "id": "src/hooks/useChat.ts",
      "name": "useChat.ts",
      "path": "src/hooks/useChat.ts",
      "ext": ".ts",
      "metrics": {
        "incomingCount": 1,
        "outgoingCount": 2
      },
      "symbols": [
        {
          "name": "useChat",
          "kind": "hook",
          "isExported": true
        }
      ]
    }
  ],
  "edges": [
    {
      "id": "src/App.tsx->src/components/Chat.tsx",
      "source": "src/App.tsx",
      "target": "src/components/Chat.tsx",
      "type": "IMPORTS"
    },
    {
      "id": "src/components/Chat.tsx->src/hooks/useChat.ts",
      "source": "src/components/Chat.tsx",
      "target": "src/hooks/useChat.ts",
      "type": "IMPORTS"
    }
  ]
}

You might wonder: why can't this run 100% in the web browser?

Web browsers operate inside a strict security sandbox:

• A webpage running in Google Chrome or Firefox cannot access your computer's local hard drive arbitrary paths (e.g. C:\Users\ASUS\Desktop\MyProject).
• A browser cannot read thousands of local files on disk without the user manually dragging and dropping every single file and waiting for gigabytes of uploads.
• The official TypeScript compiler (tsc) and ts-morph AST parser require direct filesystem access (fs, path, file watchers).

The Responsibilities of the Backend Server (server/):

1. Direct Filesystem Access:
   • Accesses any directory on your computer in milliseconds without copying or uploading files.
2. Heavyweight AST Computation (server/analyzer.ts):
   • Uses ts-morph and the TypeScript compiler engine to parse code into abstract syntax trees.
   • Resolves module specifiers (e.g., matching import { Chat } from '@/components/Chat' to src/components/Chat.tsx using tsconfig.json).
   • Extracts functions, hooks, interfaces, and export metadata.
3. OS System Integrations:
   • POST /api/browse-folder: Launches native Windows Explorer Folder Dialogs via a lightweight PowerShell call and returns the chosen folder path to the frontend.
   • GET /api/explore: Safely inspects local directory contents for the in-app navigator.
4. Lightweight Data Delivery:
   • Emits a clean, compact JSON payload containing only the graph topology ({ nodes, edges, symbols }), which takes less than a few kilobytes over HTTP!

The Responsibilities of the Frontend Client (src/):

1. Layout Positioning (src/utils/layout.ts):
   • Computes 2D coordinates (x, y) for every node and smooth bezier curve routing for every edge using @dagrejs/dagre.
2. Interactive UI (src/components/):
   • React Flow canvas rendering with minimap, zoom, drag, and pan.
   • Inspector sidebar with clickable symbols and caller/dependency links.
3. Graph Intelligence Algorithms (src/utils/topoSort.ts):
   • Runs Kahn’s topological sort, architectural tier grouping, cycle detection, and step-by-step playback synchronization instantaneously in browser memory with zero server lag!

---

4. Does This Only Work for TypeScript Projects or Any Project?

Current Status:

Right now, the AST engine is built specifically for TypeScript and JavaScript projects (.ts, .tsx, .js, .jsx).

Why?

Our analyzer uses ts-morph, which is a high-level wrapper around the official TypeScript Compiler API. TypeScript’s compiler understands:

• JavaScript and TypeScript grammar.
• JSX/TSX syntax (React components).
• TypeScript interfaces, type aliases, and generic signatures.
• tsconfig.json compiler options and path aliases.

Can We Make It Work for Any Language? YES!

The architecture we built separates the Analyzer (Data Producer) from the Graph Canvas (Data Consumer). The frontend only expects a standardized JSON format:

{
  "nodes": [
    { "id": "main.py", "name": "main.py", "ext": ".py", "symbols": [...] }
  ],
  "edges": [
    { "source": "main.py", "target": "models.py", "type": "IMPORTS" }
  ]
}

To support other languages in the future, we would simply create pluggable language adapters in the server/:

• Python: Use Python's native ast module or Tree-sitter to extract import / from ... import statements and class/function defs.
• Go: Use Go's standard go/parser and go/ast packages to resolve internal package imports.
• Rust: Use syn / ra_ap_syntax or Tree-sitter to parse mod and use declarations.
• Java/Kotlin: Use JavaParser or Tree-sitter.

Because our UI layout and Topological Sort engines operate purely on abstract graph nodes and directed edges, 100% of the UI (Dagre layout, React Flow, Topo Order Drawer, Canvas Stepper, Cycle Alert) will immediately work with ANY language adapter without modifying a single line of frontend code!

---

5. Summary of Files in the Architecture

File Path	Role	Description
server/analyzer.ts	Backend Analyzer	CodebaseAnalyzer using ts-morph to parse AST, resolve imports, filter node_modules, and extract symbols.
server/index.ts	Backend Server	Express API providing /api/analyze, /api/explore, /api/browse-folder, and /api/presets.
src/utils/topoSort.ts	Graph Algorithm	Fault-tolerant Kahn's Topological Sort with bidirectional support and cycle breaking.
src/utils/layout.ts	Layout Engine	Dagre graph coordinate calculation and dynamic node/edge styling.
src/components/GraphCanvas.tsx	Canvas UI	React Flow wrapper with minimap, controls, and background grid.
src/components/FileNode.tsx	Custom Node	File cards with category badges, symbol counters, and glowing cycle/stepper cues.
src/components/TopoOrderDrawer.tsx	Flow Drawer	Side guide grouping files by architectural tier with execution vs build toggle.
src/components/CanvasFlowPlayer.tsx	Stepper Bar	Floating playback controls for animated canvas traversal.
src/components/FolderBrowserModal.tsx	Explorer Modal	In-app visual folder navigator and native Windows Explorer trigger.
src/components/Sidebar.tsx	Inspector Panel	Node drawer detailing symbols, callers, dependencies, and clickable navigation links.