Architecture-Visualiser

An interactive architecture map of your codebase, right inside VS Code.

Opening it

No commands to type. Use whichever is closest:

• the diagram button in the editor's top-right toolbar
• the Architecture icon in the activity bar (left), which opens a panel of one-click buttons
• the Architecture item in the status bar (bottom left)
• right-click any folder in the Explorer and choose Visualise Architecture of Folder

You can also use the Command Palette: Architecture-Visualiser: Open Architecture Diagram.

Three levels of zoom

Double-click to drill down, press Esc to go back up, and double-click a file to open it.

Insights

• Architecture health score (0–100, A–F) with a breakdown of what costs points
• Import cycles, drawn as animated red edges. Click one to highlight every file in it. import type and Python if TYPE_CHECKING: imports don't count.
• Layering issues, where lower layers import higher ones (e.g. the data layer importing UI)
• Hotspots, the most-imported files, plus the files with the highest fan-out
• Possibly unused files, which nothing imports and which aren't entry points

Architecture rules

Create architecture-visualiser.json with the button in the Insights tab or the Create Architecture Rules File command:

{
  "rules": [
    { "name": "UI must not access the data layer", "from": "src/ui/**", "to": "src/data/**", "severity": "error" }
  ],
  "ignore": ["**/*.test.*"]
}

Violations appear as amber edges in the diagram and as errors or warnings in VS Code's Problems panel, at the offending import line. The file has JSON-schema autocompletion.

Drift tracking

Save snapshot records the current structure in .architecture-visualiser/snapshot.json; you can commit it. After that, new dependencies are highlighted in green, removed ones in red, and new files get a NEW badge. This is useful for spotting architecture changes in a PR.

Working with the diagram

• ⌘K / Ctrl+K: jump to any component, file or service, or run a command
• Hover a node to trace its dependencies. Click it to open the inspector, which shows depends-on and used-by lists, packages and largest files.
• Minimap, zoom controls, and automatic left-to-right or top-to-bottom layout that fits the panel
• Keyboard: 1 2 3 switch views, F fits the diagram, T changes the theme, [ toggles the sidebar, / opens search
• Live updates on save. Only changed files are re-parsed.
• Right-click a folder in the Explorer and choose Visualise Architecture of Folder to diagram just that folder
• Status bar summary with the health grade and cycle count
• Export as SVG, PNG (2×) or Mermaid, ready for a README
• Light and dark themes: match VS Code automatically or pick Light or Dark from the toolbar (or press T). Exports use the chosen theme.

Supports TypeScript, JavaScript (JSX/TSX, ESM/CJS), Python and Java (Maven and Gradle multi-module projects). Everything runs locally. No code leaves your machine.

If a project contains languages that aren't supported yet (Kotlin, Go, C#, …), the Overview says how many files were skipped, so a partial analysis is never mistaken for the full picture.

How it works

1. Scan the folder. It honors .gitignore (including nested ones) and skips node_modules, dist, virtualenvs and similar folders.
2. Parse imports with tree-sitter (WASM).
3. Resolve each import to a file: relative paths, tsconfig/jsconfig paths and baseUrl, ESM .js → .ts, monorepo packages (including exports maps), and Python src/ layouts and relative imports. For Java it resolves explicit, wildcard, static and nested-class imports, same-package references and fully-qualified names, using each file's package declaration.
4. Group files into components: one per Maven/Gradle module (inside its parent module's group), otherwise by folder, with the biggest folder split until no single box dominates. Test code doesn't create component dependencies.
5. Analyze cycles (Tarjan's strongly-connected components), layering, rules and drift, and detect infrastructure from a catalog of about 90 technologies.
6. Render with a custom canvas: ELK layered layout, HTML cards and SVG edges.

Settings

Development

npm install
npm run build              # bundles dist/extension.js + dist/webview.js and copies grammars
npm test                   # unit tests (vitest)
npm run test:integration   # launches VS Code and runs the commands end to end
npm run package            # builds a .vsix

Press F5 in VS Code to start an Extension Development Host.