# clinicjs/node-clinic architecture

> Architecture diagram of the GitHub repository clinicjs/node-clinic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clinicjs/node-clinic
- Repository: https://github.com/clinicjs/node-clinic

## Overview

##### Project Type & Purpose
- Clinic.js is an open-source Node.js command-line performance-profiling suite.
- It provides four profiling “subcommands” (doctor, bubbleprof, flame, heapprofiler) that:
- spawn your target Node.js application under instrumentation
- optionally run a benchmarking tool (autocannon, wrk)
- collect raw performance traces via Node.js core hooks

##### File Structure Analysis
- Top level
- bin.js – the CLI entry point
- lib/clean.js & lib/help-formatter.js – core data-processing and help formatting utilities
- package.json – declares dependencies, sub-commands, scripts
- docs/ – textual documentation of internal profilers
- test-local/ & test/ – extensive integration and unit test suites
- Patterns & Architecture
- Single‐process CLI tool with modular “subcommands”
- Delegation: bin.js parses args and dispatches to one of the profiling modules
- Each subcommand follows the same pipeline: Argument Parsing → Data Collection → Benchmark Runner (optional) → Analysis → Visualization

##### README Insights
- Explains functional flow: “clinic <tool> -- node server.js”
- Points to four plugin repos (node-clinic-doctor, ‑bubbleprof, ‑flame, ‑heap-profiler)

a. Main Components
1) CLI Interface (bin.js + args parser)
2) Subcommand Modules (Doctor, Bubbleprof, Flame, HeapProfiler)
3) Benchmark Runner (autocannon/wrk subprocess)
4) Node.js Core Instrumentation API (hooks into V8 & JS event loop)
5) Data Processing Layer (clean.js, analysis algorithms)
6) Visualization Generator (HTML + static assets)
7) File System (storage of raw traces and reports)
8) External Services (optional: container runtime like Podman)

b. Relationships & Data Flows
- User invokes “clinic <tool>” → CLI Interface parses args → Dispatches to the chosen Subcommand Module
- Subcommand Module spawns:
- Target Node.js App under instrumentation (Node.js Core Instrumentation API)
- Benchmark Runner (if ––autocannon/––on-port flag present)
- While target runs, instrumentation emits trace files (raw .clinic data) into the File System
- On application exit (or ––collect-only), Subcommand Module invokes Data Processing Layer to:
- Clean & merge raw data (lib/clean.js)
- Apply analysis heuristics (e.g., identify I/O bottlenecks in doctor)
- Processed data flows into Visualization Generator → outputs HTML report to File System

c. Architectural Patterns & Principles
- Modular subcommands for separation of concerns
- Reuse of common utilities (help-formatter, clean.js) across subcommands
- Pipeline stages connected by file-based artifacts (.clinic folders)
- Plugin-style extensibility (adding new profiling modes)

d. Key Technologies & Libraries
- Node.js (>=16) & V8 Core Instrumentation hooks
- subarg (argument parsing)
- child_process.spawn (to run benchmark tools)
- file‐system module (persisting raw data & reports)
- HTML/CSS/JS for static visualizations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Parser<br>(bin.js)"]:::blue
        Help["Help Formatter<br>(lib/help-formatter.js)"]:::blue
        Dispatcher["Subcommand Dispatcher"]:::blue
    end
    CLI --> Help
    Help --> Dispatcher

    %% Subcommand Modules
    subgraph "Subcommand Modules"
        Doctor["Doctor Module"]:::blue
        Bubble["Bubbleprof Module"]:::blue
        Flame["Flame Module"]:::blue
        Heap["HeapProfiler Module"]:::blue
    end
    Dispatcher --> Doctor
    Dispatcher --> Bubble
    Dispatcher --> Flame
    Dispatcher --> Heap

    %% Collection Layer
    subgraph "Data Collection" 
        Instr["Instrumentation API<br>(Node.js Core Hooks)"]:::green
        Bench["Benchmark Runner<br>(autocannon/wrk)"]:::green
    end
    Doctor -->|spawns| Instr
    Doctor -->|optional| Bench
    Bubble -->|spawns| Instr
    Bubble -->|optional| Bench
    Flame -->|spawns| Instr
    Flame -->|optional| Bench
    Heap -->|spawns| Instr
    Heap -->|optional| Bench

    Instr --> Raw["Raw Trace Files<br>(.clinic)"]:::fs
    Bench --> Raw

    %% Analysis Layer
    subgraph "Data Processing" 
        Clean["Cleaner & Merger<br>(lib/clean.js)"]:::orange
        Analyze["Analysis Algorithms"]:::orange
    end
    Raw --> Clean --> Analyze

    %% Visualization Layer
    subgraph "Visualization"
        Visual["HTML Report Generator"]:::purple
        Reports["HTML Reports & Assets"]:::fs
    end
    Analyze --> Visual --> Reports

    %% Project Files
    subgraph "Documentation"
        DocD["clinic-doctor.txt"]:::doc
        DocB["clinic-bubbleprof.txt"]:::doc
        DocF["clinic-flame.txt"]:::doc
        DocH["clinic-heap-profiler.txt"]:::doc
    end

    subgraph "Tests"
        TAut["cli-autocannon.test.js"]:::test
        TLocal["test-local/*-*.test.js"]:::test
        TDoc["cli-doctor-*.test.js"]:::test
        TBub["cli-bubbleprof-*.test.js"]:::test
        TFl["cli-flame-*.test.js"]:::test
        THeap["cli-heapprofiler-*.test.js"]:::test
    end

    subgraph "Fixtures"
        F1["html-and-folder/"]:::fs
        F2["only-folder/"]:::fs
        F3["too-big-should-fail/"]:::fs
    end

    subgraph "Configuration"
        Pkg["package.json"]:::config
        Npmrc[".npmrc"]:::config
        CI[".github/workflows/ci.yml"]:::config
        NR[".github/workflows/notify-release.yml"]:::config
    end

    %% Click Events
    click CLI "https://github.com/clinicjs/node-clinic/blob/main/bin.js"
    click Help "https://github.com/clinicjs/node-clinic/blob/main/lib/help-formatter.js"
    click Clean "https://github.com/clinicjs/node-clinic/blob/main/lib/clean.js"
    click DocD "https://github.com/clinicjs/node-clinic/blob/main/docs/clinic-doctor.txt"
    click DocB "https://github.com/clinicjs/node-clinic/blob/main/docs/clinic-bubbleprof.txt"
    click DocF "https://github.com/clinicjs/node-clinic/blob/main/docs/clinic-flame.txt"
    click DocH "https://github.com/clinicjs/node-clinic/blob/main/docs/clinic-heap-profiler.txt"
    click TAut "https://github.com/clinicjs/node-clinic/blob/main/test/cli-autocannon.test.js"
    click TLocal "https://github.com/clinicjs/node-clinic/blob/main/test-local/cli-*-*.test.js"
    click TDoc "https://github.com/clinicjs/node-clinic/blob/main/test/cli-doctor-*.test.js"
    click TBub "https://github.com/clinicjs/node-clinic/blob/main/test/cli-bubbleprof-*.test.js"
    click TFl "https://github.com/clinicjs/node-clinic/blob/main/test/cli-flame-*.test.js"
    click THeap "https://github.com/clinicjs/node-clinic/blob/main/test/cli-heapprofiler-*.test.js"
    click F1 "https://github.com/clinicjs/node-clinic/tree/main/test/fixtures/html-and-folder/"
    click F2 "https://github.com/clinicjs/node-clinic/tree/main/test/fixtures/only-folder/"
    click F3 "https://github.com/clinicjs/node-clinic/tree/main/test/fixtures/too-big-should-fail/"
    click Pkg "https://github.com/clinicjs/node-clinic/blob/main/package.json"
    click Npmrc "https://github.com/clinicjs/node-clinic/blob/main/.npmrc"
    click CI "https://github.com/clinicjs/node-clinic/blob/main/.github/workflows/ci.yml"
    click NR "https://github.com/clinicjs/node-clinic/blob/main/.github/workflows/notify-release.yml"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef green fill:#DFF4DD,stroke:#1C8C3B,color:#1C8C3B;
    classDef orange fill:#FFE8CC,stroke:#D97706,color:#B45309;
    classDef purple fill:#F3E8FF,stroke:#6B21A8,color:#5B21B6;
    classDef fs fill:#F0F0F0,stroke:#999999,color:#333333,stroke-dasharray: 2 2;
    classDef doc fill:#FFF5D0,stroke:#D4A017,color:#8A6D11;
    classDef test fill:#F0D9FF,stroke:#8A2BE2,color:#5B21B6;
    classDef config fill:#D9EDF7,stroke:#31708F,color:#23527C;
```
