Understand, navigate, and refactor any JavaScript & TypeScript codebase as an interactive architecture graph.
Features • Quick Start • Architecture • CLI Mode • Shortcuts • Documentation • Contributing
Point Visual Code Architecture IDE at any JavaScript or TypeScript project folder. It statically parses every module, resolves imports and tsconfig aliases, extracts functions and classes, and renders a live, interactive map of how the codebase fits together.
🔒 100% Local & Deterministic: No cloud upload, no API keys, no LLM hallucinations, and no indexing delay. Every number and edge is derived directly from the real AST. The exact same repo produces the exact same graph every time.
|
Every source file is an interactive node with its full import/export edges. Colour-coded by folder layer, sized by complexity, with type-only imports and dynamic imports visually distinguished. |
Collapse hundreds of files into high-level directory clusters at configurable depth. See how packages and features communicate without getting lost in individual files. |
|
Drill down into any individual file to see exact caller/callee relationships for every exported function, class method, and local handler. |
Select any file or function to trace every direct and transitive caller affected by a change. Displays the shortest dependency paths and blast-radius depth. |
|
Discovers unreferenced files and unused exports with confidence scoring and exact explanations (e.g. unimported entry points, orphaned helpers). |
Identifies high-risk architectural hotspots based on fan-in, fan-out, cyclomatic complexity, and lines of code. Isolates circular import cycles instantly. |
- Node.js:
v22.5.0or newer (uses built-innode:sqlite, zero native compilation needed).
# 1. Clone the repository
git clone https://github.com/rishwebb/Architecture-IDE.git
cd Architecture-IDE
# 2. Install dependencies
npm install
# 3. Start development server (Web Browser UI + Backend)
npm run devOpen http://127.0.0.1:5173 in your browser, enter or browse for any project path, and hit Analyse.
npm run devRuns the Express analysis backend on port 5174 and the Vite React UI on port 5173.
Provides native folder dialogs and OS file-manager reveal actions:
# Production desktop build
npm run desktop:build
# Build standalone Windows installer & portable .exe
npm run distRun analysis directly from your terminal or CI/CD pipeline without any GUI:
# Summary printed in terminal
npm run analyze -- /path/to/project
# Pipe full JSON output
npm run analyze -- /path/to/project --json | jq .metrics.summary
# Save analysis to file
npm run analyze -- /path/to/project --json=graph.jsonThe project is engineered as a clean monorepo with strict one-way dependency flow:
flowchart LR
A[Source Files] --> B["@vcide/parser\n(Babel AST)"]
B --> C["@vcide/graph-engine\n(Resolver, Scanner, Metrics)"]
C --> D["@vcide/backend\n(Express 5 + SQLite)"]
D --> E["@vcide/frontend\n(React 19 + React Flow)"]
D --> F["Electron Shell\n(Desktop Window)"]
| Package | Role | Details |
|---|---|---|
parser/ |
AST Extraction | Pure AST parser via Babel. Extracts imports, exports, functions, calls, and cyclomatic complexity with zero project coupling. |
graph-engine/ |
Graph & Metrics | Resolves relative paths, tsconfig.json aliases, exports maps; calculates blast radius, detects cycles, and flags dead code. |
backend/ |
API & Storage | Express 5 REST API exposing the engine over HTTP, with a persistent SQLite database (node:sqlite) for history and recents. |
frontend/ |
Interactive UI | React 19, React Flow (@xyflow/react), Tailwind CSS, and Electron integration. |
scripts/ |
CLI & Launchers | Dev runner, desktop launcher, icon generators, and headless CLI tool. |
tests/ |
Test Suite | Comprehensive 147-test suite using Node's built-in test runner against real project fixtures. |
| Shortcut (Win / Linux) | Shortcut (macOS) | Action |
|---|---|---|
| Ctrl + O | ⌘ + O | Open project folder |
| Ctrl + R | ⌘ + R | Re-analyse current project |
| Ctrl + F | ⌘ + F | Fuzzy search files & symbols |
| Ctrl + 1 | ⌘ + 1 | Switch to Architecture Graph view |
| Ctrl + 2 | ⌘ + 2 | Switch to Module Folders view |
| Ctrl + 3 | ⌘ + 3 | Switch to Call Graph view |
| Ctrl + Alt + 1 | ⌥ + ⌘ + 1 | Toggle File Inspector |
| Ctrl + Alt + 2 | ⌥ + ⌘ + 2 | Toggle Impact Analysis panel |
| Ctrl + Alt + 3 | ⌥ + ⌘ + 3 | Toggle Dead Code panel |
| Ctrl + Alt + 4 | ⌥ + ⌘ + 4 | Toggle Hotspots & Risk panel |
| Ctrl + Shift + ? | ⇧ + ⌘ + ? | Open Shortcuts cheat sheet |
npm run dev # Start Backend (5174) and Vite (5173) concurrently
npm run dev:backend # Backend only with hot reloading (node --watch)
npm run build # Build production frontend into frontend/dist
npm start # Start production backend (serves frontend/dist)
npm test # Run 147 test suite with Node's native runner
npm run typecheck # TypeScript static typecheck over frontend
npm run desktop # Electron shell connected to dev server
npm run desktop:build # Build bundle and open in Electron shell
npm run dist # Package Windows NSIS installer and portable .exe
npm run dist:dir # Package unpacked desktop application folder- 📐 Architecture Guide: Deep dive into the multi-stage analysis pipeline and AST graph building.
- 🔌 HTTP API Reference: Complete reference of all 20 backend REST endpoints, payload schemas, and SSE streams.
- 🗺️ Project Roadmap: Completed milestones and planned future phases (Git time-machine, 3D city visualization, AI explainers).
Contributions are welcome! Please read our Contributing Guidelines before submitting pull requests.
- Fork the Project
- Create your Feature Branch (
git checkout -b feat/AmazingFeature) - Commit your Changes (
git commit -m 'feat: add amazing feature') - Push to the Branch (
git push origin feat/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.