project-description.md

Code Relationship VisualizerCode Relationship Visualizer OverviewOverview Code Relationship Visualizer is a developer tool that analyzes source code and generates interactive dependency graphs, helping developers understand large codebases faster. The tool scans project files, extracts relationships between modules, services, classes, and functions, and visualizes those relationships in an interactive graph. ExampleExample Instead of manually tracing dependencies: UserService

↓

AuthService

↓

TokenManager Developers can explore the architecture visually through an interactive interface. Problem StatementProblem Statement As software projects grow, understanding code relationships becomes increasingly difficult. Common challenges include: Large repositories with hundreds of files Unknown dependencies between modules Difficult onboarding for new developers Hidden circular dependencies Complex refactoring processes Lack of architecture visibility Developers often spend significant time reading code before understanding how components interact. Proposed SolutionProposed Solution Create a tool that automatically analyzes source code and generates: Dependency graphs Call graphs Architecture maps Circular dependency reports Dead code reports Impact analysis visualizations The generated output should be easy to explore through a web-based interactive interface. Project GoalsProject Goals Primary GoalsPrimary Goals Simplify understanding of large repositories Improve developer onboarding Reduce time spent tracing dependencies Assist in architecture reviews Support refactoring activities Secondary GoalsSecondary Goals Detect architectural issues Identify unused modules Generate documentation automatically Integrate into development workflows

Product VisionProduct Vision The project should evolve into a complete Code Intelligence Platform. Initial VisionInitial Vision npx codeviz Generate dependency reports instantly. Long-Term VisionLong-Term Vision npx codeviz analyze

Generate:

Dependency Maps

Architecture Reports

Code Health Metrics

Impact Analysis Reports

Team Ownership Maps

Core FeaturesCore Features

1. Dependency Visualization1. Dependency Visualization

Analyze imports and module references.

Example:

UserController

↓

UserService

↓

UserRepository OutputOutput

Interactive Graph

Searchable Nodes

Zoom and Pan Support

Dependency Highlighting

2. Call Graph Generation2. Call Graph Generation

Track function-to-function relationships.

Example:

login()

↓

authenticate()

↓

generateToken() Useful for understanding execution flow.

3. Circular Dependency Detection3. Circular Dependency Detection

Detect dependency loops.

Example:

A → B

B → C

C → A

Output:

Warning: Circular Dependency Detected

A → B → C → A

4. Dead Code Detection4. Dead Code Detection

Identify unused files and modules.

Example:

PaymentService.ts Not referenced anywhere.

Output:

Unused Module Detected

5. Impact Analysis5. Impact Analysis

Select a node and view all affected components.

Example:

AuthService

Shows:

UserService AdminService SessionService Useful before refactoring.

6. Architecture Validation6. Architecture Validation

Allow teams to define architecture rules.

Example:

Controllers

↓

Services

↓

Repositories

Violation:

Controller → Repository

Output:

Architecture Violation Detected

Target UsersTarget Users Individual DevelopersIndividual Developers Understanding unfamiliar projects

Refactoring

Learning architecture Development TeamsDevelopment Teams Onboarding new members Code reviews Architecture discussions Open Source ContributorsOpen Source Contributors Understanding large repositories Navigating unfamiliar codebases Supported LanguagesSupported Languages Version 1Version 1 JavaScript TypeScript

Reason:

TypeScript Compiler API provides reliable AST parsing. Version 2Version 2

Python

Using Python's built-in AST module. Version 3Version 3

Java

Go

Rust

Additional language support through dedicated parsers. System ArchitectureSystem Architecture

Project Source

↓

File Scanner

↓

AST Parser

↓

Dependency Extractor

↓

Graph Builder

↓

Visualization Engine

Technical ComponentsTechnical Components File ScannerFile Scanner Responsible for locating source files. Supported patterns: src//*.ts src//.tsx src/**/.js src/**/*.jsx AST ParserAST Parser Extracts imports, exports, classes, and function relationships.

Example:

import { AuthService } from './auth'

Extracted Relationship:

{

"source": "UserService", "target": "AuthService"

}

Graph BuilderGraph Builder Transforms relationships into graph structures.

Example:

{

"nodes": [],

"edges": []

}

Visualization EngineVisualization Engine Renders interactive dependency maps.

Capabilities:

Search

Zoom

Pan

Highlight Paths

Expand Nodes

Collapse Nodes

Recommended Technology StackRecommended Technology Stack Core EngineCore Engine LanguageLanguage TypeScript ParsingParsing TypeScript Compiler API CLI FrameworkCLI Framework

Commander.js

Build ToolBuild Tool tsup TestingTesting

Vitest

LintingLinting ESLint VisualizationVisualization Preferred OptionPreferred Option

React Flow

Benefits:

Modern UI

Interactive Nodes

Easy Customization

AlternativeAlternative

Cytoscape.js

Benefits:

Better Performance

Large Graph Support

Product InterfacesProduct Interfaces

• CLI Interface1. CLI Interface Primary interface.

Example:

npx codeviz or npx codeviz src

• HTML Report Generator2. HTML Report Generator

Example:

npx codeviz --html

Output:

report/ ├── index.html ├── assets/ └── graph.json Open directly in a browser.

• VS Code Extension3. VS Code Extension Potential future feature.

Options:

Visualize Current File

Show Dependency Graph

Show Call Graph

Find Circular Dependencies

• GitHub Action4. GitHub Action Analyze pull requests automatically.

Example:

• uses: codeviz/action Outputs architecture changes within PR comments. Development RoadmapDevelopment Roadmap Phase 1 — MVPPhase 1 — MVP GoalGoal Dependency extraction and CLI output.

Features:

[x] File scanning [x] AST parsing [x] Dependency extraction [x] Terminal visualization

Estimated Duration:

4 weeks

Phase 2 — Interactive VisualizationPhase 2 — Interactive Visualization GoalGoal Generate interactive HTML reports.

Features:

[x] Cytoscape.js integration [x] Search functionality [x] Zoom and pan [x] Node inspection [x] Impact analysis

Estimated Duration:

4 weeks Phase 3 — Advanced AnalysisPhase 3 — Advanced Analysis

Features:

[x] Circular dependency detection [x] Dead code detection [x] Architecture validation

Estimated Duration:

4 weeks Phase 4 — EcosystemPhase 4 — Ecosystem

Features:

VS Code Extension GitHub Action CI/CD Integration

Estimated Duration:

4–6 weeks Future OpportunitiesFuture Opportunities SaaS PlatformSaaS Platform Potential cloud offering: npx codeviz upload

Provides:

Team Dashboards

Architecture Reports

Dependency Trends

Code Health Metrics

Enterprise FeaturesEnterprise Features

Architecture Governance

Team Ownership Mapping

Security Analysis

Compliance Reporting

Success MetricsSuccess Metrics

Faster onboarding time Reduced architecture misunderstandings Reduced refactoring risks Increased repository visibility Improved developer productivity Project TaglineProject Tagline "Understand your codebase before reading every file."