CodeArchViz 📊

Automatic Architecture Visualization Generator

Generate beautiful, interactive architecture diagrams from any codebase. CodeArchViz analyzes your project structure and import relationships to create a D3.js-powered visualization.

Features

• 🔍 Automatic Detection - Scans your codebase and auto-detects architectural patterns (hooks, services, stores, components, etc.)
• 🎨 Interactive Visualization - Zoom, pan, search, and explore your architecture
• 🏗️ Layer-Based Layout - Organizes code by architectural layers (pages, components, services, etc.)
• 🔗 Relationship Mapping - Shows imports, hooks, stores, and service dependencies
• ⚙️ Fully Configurable - Customize layers, colors, patterns, and file detection
• 📦 Zero Dependencies at Runtime - Generates a single HTML file with embedded D3.js

Installation

npm install -g codearchviz
# or use directly with npx (no install needed)
npx codearchviz

Quick Start

# Show all available commands
codearchviz --help

# Analyze current directory
codearchviz

# Analyze a specific project
codearchviz /path/to/your/project

# Specify output directory
codearchviz /path/to/project -o docs/architecture

# Custom project name
codearchviz /path/to/project -n "My Awesome Project"

# Verbose mode (shows auto-detected layers)
codearchviz /path/to/project -v

Then open the generated output/index.html in your browser, or serve it:

npx serve output

All Commands

| Command | Description | |---------|-------------| | codearchviz | Analyze current directory | | codearchviz <path> | Analyze a specific project | | codearchviz -o <dir> | Set output directory (default: output) | | codearchviz -n <name> | Set project name in visualization | | codearchviz -c <file> | Use custom config file | | codearchviz -v | Verbose output (shows detected layers) | | codearchviz --no-open | Don't auto-open browser | | codearchviz --help | Show help | | codearchviz --version | Show version |

Auto-Detection

CodeArchViz automatically recognizes common folder naming patterns:

| Layer | Detected Folders | |-------|-----------------| | Components | components/, ui/, widgets/, atoms/, molecules/ | | Pages | pages/, views/, screens/, routes/ | | Hooks | hooks/, composables/, use/ | | Services | services/, api/, clients/, gateway/, repository/ | | Stores | stores/, store/, state/, redux/, zustand/ | | Utils | utils/, lib/, helpers/, shared/, common/ | | Types | types/, interfaces/, models/, schemas/ | | Contexts | contexts/, providers/ |

It also detects by file naming:

• useXxx.ts → Hook
• XxxService.ts, XxxApi.ts → Service
• XxxStore.ts, XxxSlice.ts → Store
• XxxContext.tsx, XxxProvider.tsx → Context

Configuration

Create a codearchviz.config.js file in your project root:

export default {
  projectName: 'My Project',
  
  include: ['src/**/*.{ts,tsx}'],
  
  exclude: [
    '**/node_modules/**',
    '**/*.test.*',
    '**/__tests__/**'
  ],
  
  layers: [
    { id: 'pages', label: 'Pages', color: '#10b981', patterns: ['**/pages/**'] },
    { id: 'components', label: 'Components', color: '#8b5cf6', patterns: ['**/components/**'] },
    { id: 'services', label: 'Services', color: '#f59e0b', patterns: ['**/services/**'] },
    { id: 'hooks', label: 'Hooks', color: '#14b8a6', patterns: ['**/hooks/**'] },
    { id: 'stores', label: 'Stores', color: '#ec4899', patterns: ['**/stores/**'] }
  ]
};

See codearchviz.config.example.js for a complete configuration reference.

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -c, --config <file> | Path to config file | codearchviz.config.js | | -o, --output <dir> | Output directory | output | | -n, --name <name> | Project name | Directory name | | -v, --verbose | Show detailed output | false | | --no-open | Don't open browser | false |

How It Works

1. File Discovery - Scans your project using glob patterns
2. Node Creation - Creates a node for each file with detected type and layer
3. Import Analysis - Parses import statements to build the dependency graph
4. Edge Classification - Categorizes relationships (renders, uses-hook, uses-store, etc.)
5. Visualization - Generates an interactive HTML file with D3.js

Supported File Types

• JavaScript (.js, .jsx)
• TypeScript (.ts, .tsx)
• Vue (.vue)
• Svelte (.svelte)

Layer Detection

Files are assigned to layers based on their path patterns:

| Layer | Default Patterns | |-------|------------------| | Pages | pages/**, views/**, screens/** | | Layout | layout/**, layouts/** | | Features | features/**, modules/** | | Components | components/**, ui/** | | Services | services/**, api/** | | Stores | stores/**, store/**, state/** | | Hooks | hooks/**, composables/** | | Contexts | contexts/**, providers/** | | Utilities | utils/**, lib/**, helpers/** |

Node Types & Shapes

| Type | Shape | Detection | |------|-------|-----------| | Page | Large Circle | *Page.tsx, /pages/* | | Layout | Medium Circle | *Layout.tsx, /layout/* | | Feature | Star | /features/* | | Component | Small Circle | Any React/Vue component | | Service | Hexagon | *Service.ts, *Api.ts | | Store | Diamond | *Store.ts, /store/* | | Hook | Circle | use*.ts, /hooks/* | | Context | Rounded Square | *Context.tsx, *Provider.tsx | | Utility | Square | /utils/*, /lib/* |

Visualization Controls

• Click Node - Highlight connections and show details
• Search - Filter nodes by name or path
• Zoom - Mouse wheel or +/- buttons
• Pan - Click and drag
• Reset - Return to initial view
• Labels - Toggle node labels
• Legend - Click to show/hide layers

Example Projects

# React + TypeScript project
npx codearchviz ~/projects/my-react-app -n "My React App"

# Vue.js project
npx codearchviz ~/projects/vue-store -n "Vue Store"

# Node.js backend
npx codearchviz ~/projects/express-api -n "Express API" \
  -c codearchviz-backend.config.js

Programmatic Usage

import { analyze, generateVisualization } from 'codearchviz';

const config = {
  projectName: 'My Project',
  include: ['src/**/*.ts'],
  exclude: ['**/node_modules/**'],
  layers: [/* ... */]
};

const data = await analyze('/path/to/project', config);
const outputPath = await generateVisualization(data, config, 'output');
console.log(`Generated: ${outputPath}`);

Development

# Clone the repo
git clone https://github.com/yourusername/codearchviz.git
cd codearchviz

# Install dependencies
npm install

# Run on a test project
npm run analyze -- /path/to/test/project

# Serve the output
npm run serve

Contributing

Contributions are welcome! Please open an issue or submit a PR.

License

MIT © 2026