HotCode (System Architecture Scanner & Interactive Visual Graph Generator)

hotcode is a lightweight, zero-configuration codebase architecture scanner and visual dependency mapper. It parses directory trees using AST mappings (Tree-sitter) and regex heuristic parsers, constructs a directional system knowledge graph, resolves inter-file/inter-service references, and generates a standalone, interactive physics-simulated HTML visualization page.

Key Features

• Universal Multi-Language AST Parsing: Supports Python and JavaScript/TypeScript/JSX/TSX.
• Non-Code Asset Mapping:
  • SQL Schemas: Extracts database tables and maps relationships via foreign keys/references constraints.
  • Documentation: Scans Markdown files and maps relative document links to files or other assets.
  • Shell Scripts: Traces execution dependency chains between shell scripts.
• Cross-Repo Microservice Mapping: Connects HTTP requests (using fetch, axios, or Python requests) directly to their corresponding backend API route endpoints.
• Clean Architecture Checker: Detects architectural violations (such as endpoint controllers directly bypassing services to invoke database schemas) and highlights warnings.
• Rich Visual Exports:
  • Interactive HTML Graph (graph.html): A standalone, offline-ready UI featuring dynamic searches, checkboxes to show/hide entities, toggling dead code visualization, physics configurations, and a detailed sidebar listing dependencies and warnings.
  • Markdown Report (hotcode-report.md): A detailed GFM report featuring overview metrics, ASCII directory trees, endpoints caller lists, and an auto-generated Mermaid call-flow flowchart.

Usage Guide

You can run hotcode directly using npx or by cloning and running it locally.

Option 1: Run Instantly via npx (Recommended)

You don't need to install anything. Just run the tool on your target directories:

# Scan a single repository directory
npx @mohamedadelshendy/hotcode <path-to-directory>

# Scan multiple directories (for microservice/request mapping)
npx @mohamedadelshendy/hotcode <path-to-repo-A> <path-to-repo-B>

# Specify a custom output directory (defaults to "hotcode-out")
npx @mohamedadelshendy/hotcode <path-to-directory> --out my-architecture-docs

Option 2: Running Locally from Source

If you have cloned the repository and want to run it from source:

1. Install Dependencies:

   npm install

2. Build the CLI:

   npm run build

3. Run the Scanner:

   # Scan directory, placing outputs in default "hotcode-out"
   npm run cli -- <path-to-directory>
   
   # Scan multiple directories with custom output folder name
   npm run cli -- <path-to-repo-A> <path-to-repo-B> --out custom-output

Output Architecture Files

By default, files are generated in the ./hotcode-out/ folder:

1. graph.html: The interactive visual graph dashboard. Double-click to open in any web browser to explore, search, and inspect code connections.
2. hotcode-report.md: Markdown report showing tree structures, metrics, and a Mermaid flowchart.
3. hotcode-summary.json: The complete queryable JSON codebase dependency model.