Living Architecture Diagram

---
description: Generate an interactive dependency graph visualization of the codebase
allowed-tools: Bash, Read, Write, Glob, Grep
context:
  - type: command
    command: "find src -name '*.ts' -o -name '*.tsx' -o -name '*.js' | head -200"
---

# Living Architecture Diagram

Analyze the import graph of the codebase and generate a self-contained, interactive HTML page that visualizes module dependencies using D3.js.

## Steps

1. **Collect source files.** Use the context output or run `find` to locate all `.ts`, `.tsx`, `.js`, and `.jsx` files under `src/`. Exclude `node_modules`, `dist`, and `.next` directories.
2. **Parse imports.** For each source file, read it and extract import statements:
   - ES modules: `import ... from './path'` and `import ... from 'package'`
   - CommonJS: `require('./path')` and `require('package')`
   - Dynamic imports: `import('./path')`
   - Re-exports: `export ... from './path'`
   Only track **local imports** (starting with `.` or `/`). Ignore external packages.
3. **Resolve paths.** Normalize relative import paths to absolute paths relative to the project root. Handle index files (`./components` → `./components/index.ts`) and TypeScript path aliases if a `tsconfig.json` is present.
4. **Build the adjacency list.** Create a JSON structure:
   ```json
   {
     "nodes": [{ "id": "src/components/Button.tsx", "group": "components" }],
     "links": [{ "source": "src/app/page.tsx", "target": "src/components/Button.tsx" }]
   }
   ```
   The `group` field is the first directory segment under `src/` (e.g., `components`, `lib`, `app`).
5. **Generate the HTML file.** Create a self-contained HTML file at `architecture-diagram.html` that includes:

### Required features
- Load D3.js v7 from a CDN (`https://d3js.org/d3.v7.min.js`).
- Render a **force-directed graph** with:
  - Nodes as circles, sized by number of connections (imports + importers)
  - Links as lines with arrows indicating import direction
  - Color-coded by `group` (directory) using `d3.schemeCategory10`
- **Interactive features:**
  - Drag nodes to rearrange
  - Zoom and pan with mouse wheel / trackpad
  - Hover over a node to highlight its direct connections and dim everything else
  - Click a node to show a tooltip with: file path, number of imports, number of importers, list of direct dependencies
- **Legend** showing directory-to-color mapping
- **Search box** to find and highlight a specific file
- **Stats sidebar** showing: total modules, total connections, most-connected module, most-imported module, orphan modules (no imports or importers)
- Responsive layout that works on any screen size
- Dark background with light-colored nodes for readability

6. **Open the file.** Run `open architecture-diagram.html` (macOS) or `xdg-open architecture-diagram.html` (Linux) to display the result.

## Rules

- The HTML file must be completely self-contained — no local file dependencies, only CDN links.
- Handle circular dependencies gracefully (they are common and should be rendered as bidirectional arrows).
- If the codebase has more than 200 files, cluster by directory and allow expanding/collapsing clusters.
- Add a small "Generated by Codebase Architect" footer with the generation timestamp.