# pahen/madge architecture

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

- Interactive diagram: https://gitdiagram.com/pahen/madge
- Repository: https://github.com/pahen/madge

## Overview

##### Project Type and Purpose
- Madge is an open-source command-line and programmatic Node.js tool for analyzing JavaScript (and CSS preprocessor) module dependency trees, detecting circular dependencies, and generating visual graphs (via Graphviz).
- It exposes a CLI entrypoint (`bin/cli.js`) and a Promise-based API (`lib/api.js`), orchestrating a pipeline of sub-modules that handle tree extraction, cycle detection, graph construction, and output formatting.

##### High-Level File Structure Analysis
- Top-Level
– `bin/cli.js`: CLI bootstrap, argument parsing, invokes the API.
– `lib/`: core modules implementing the pipeline:
- `api.js`: facade that wires up the pipeline and returns results (obj, circular, dot, image, svg, etc.).
- `tree.js`: uses `dependency-tree`/`precinct` to traverse the file system and build the raw dependency graph.
- `cyclic.js`: analyzes the raw graph to find circular dependencies.
- `graph.js`: transforms the dependency data into a Graphviz-compatible DOT structure.
- `output.js`: serializes DOT to console text or writes image files (SVG, DOT).
- `log.js`: centralized logging and warning management.
– `test/`: comprehensive suite covering AMD, CommonJS, ES6, TypeScript, Vue, JSX, CSS preprocessors, circular cases, error scenarios.
- Configuration & Metadata
– `package.json`, `.eslintrc`, `.editorconfig`, `.nvmrc`, GitHub workflows, `.release-it.json`.

##### README-Driven Insights
- Core external dependencies:
- `dependency-tree` (via `precinct`/`detective`) for file parsing and AST-based dependency resolution.
- Graphviz (optional) to render DOT graphs to images.
- Supported module formats: AMD, CJS, ES6, TypeScript, JSX, Vue, CSS preprocessors.
- API methods: `.obj()`, `.circular()`, `.dot()`, `.image()`, `.svg()`, etc., each returning Promises.
- Configurable via CLI flags or `.madgerc`/`package.json` madge section.

a. Main Components
1. CLI Layer
- Entry (`bin/cli.js`) → parses CLI args + config → calls API.
2. API Facade (`lib/api.js`)
- Validates inputs/config → orchestrates pipeline → exposes Promise interface.
3. Dependency Tree Generator (`lib/tree.js`)
- File system walker → AST parsing → builds raw module graph.
4. Cycle Detector (`lib/cyclic.js`)
- Graph traversal → identifies strongly connected components.
5. Graph Builder (`lib/graph.js`)
6. Output Manager (`lib/output.js`)
- Renders DOT text, writes SVG/PNG via Graphviz CLI or Graphviz JS.
7. Logging/Warnings (`lib/log.js`)
- Captures debug/info/warning messages.
8. External Services
- File System (fs) for module reads.
- Graphviz for image rendering.
- Optional Webpack/RequireJS/TypeScript configs for resolving aliases.
b. Relationships & Data Flow
– Config flows top-down from CLI/API to each module (tree, graph, output).
– Logging cross-cuts all modules.
c. Architectural Patterns & Principles
– Pipeline pattern: sequential processing stages.
– Modular separation of concerns: each lib/*.js has a single responsibility.
– Promise-based asynchronous flow.
– Plugin-style extensibility via config (e.g., custom detective options, Graphviz flags).
d. Key Technologies & Libraries
– Node.js core: `fs`, `path`.
– `dependency-tree`/`precinct` for module analysis.
– Graphviz (via CLI).
– Promises (native or Bluebird).
– Commander or minimist (in CLI for argument parsing).
– Test frameworks (Mocha, Chai, or similar).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Metadata
    subgraph "Configuration & Metadata"
        packageJson["package.json"]:::config
        eslintrc[".eslintrc"]:::config
        editorconfig[".editorconfig"]:::config
        nvmrc[".nvmrc"]:::config
        releaseit[".release-it.json"]:::config
        workflows[".github/workflows/nodejs.yml"]:::config
    end

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entry (bin/cli.js)"]:::cli
    end

    %% API Facade
    subgraph "API Facade"
        API["API Facade (lib/api.js)"]:::api
    end

    %% Core Pipeline Modules
    subgraph "Core Pipeline"
        Tree["Tree Generator\n(raw dependency map)"]:::pipeline
        Cyclic["Cycle Detector\n(circular list)"]:::pipeline
        Graph["Graph Builder\n(DOT object)"]:::pipeline
        Output["Output Manager\n(SVG/DOT output)"]:::pipeline
        Log["Logging/Warnings"]:::log
    end

    %% External Services
    subgraph "External Services"
        FileSystem["File System (fs)"]:::external
        Graphviz["Graphviz CLI"]:::external
    end

    %% Test Suite
    subgraph "Test Suite"
        Test["Tests (test/)"]:::test
    end

    %% Data Flow
    packageJson & eslintrc & editorconfig & nvmrc & releaseit & workflows -->|config| CLI
    packageJson & eslintrc & editorconfig & nvmrc & releaseit & workflows -->|config| API

    CLI -->|"args & flags"| API
    API -->|"validated config"| Tree
    Tree -->|"raw dependency map"| Cyclic
    Cyclic -->|"circular dependencies"| Graph
    Graph -->|"DOT object"| Output
    Output -->|"SVG/DOT files"| Graphviz
    Graphviz -->|"writes files"| FileSystem

    %% Logging cross-cutting
    CLI --> Log
    API --> Log
    Tree --> Log
    Cyclic --> Log
    Graph --> Log
    Output --> Log

    %% Test integration
    Test --> API
    Test --> Tree
    Test --> Cyclic
    Test --> Graph
    Test --> Output

    %% Click Events
    click CLI "https://github.com/pahen/madge/blob/master/bin/cli.js"
    click API "https://github.com/pahen/madge/blob/master/lib/api.js"
    click Tree "https://github.com/pahen/madge/blob/master/lib/tree.js"
    click Cyclic "https://github.com/pahen/madge/blob/master/lib/cyclic.js"
    click Graph "https://github.com/pahen/madge/blob/master/lib/graph.js"
    click Output "https://github.com/pahen/madge/blob/master/lib/output.js"
    click Log "https://github.com/pahen/madge/blob/master/lib/log.js"
    click packageJson "https://github.com/pahen/madge/blob/master/package.json"
    click eslintrc "https://github.com/pahen/madge/blob/master/.eslintrc"
    click editorconfig "https://github.com/pahen/madge/blob/master/.editorconfig"
    click nvmrc "https://github.com/pahen/madge/blob/master/.nvmrc"
    click releaseit "https://github.com/pahen/madge/blob/master/.release-it.json"
    click workflows "https://github.com/pahen/madge/blob/master/.github/workflows/nodejs.yml"
    click Test "https://github.com/pahen/madge/tree/master/test/"

    %% Styles
    classDef cli fill:#D6EAF8,stroke:#3498DB
    classDef api fill:#D6EAF8,stroke:#3498DB
    classDef pipeline fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#E5E7E9,stroke:#95A5A6
    classDef config fill:#FCF3CF,stroke:#F4D03F
    classDef log fill:#FDEBD0,stroke:#E67E22
    classDef test fill:#FADBD8,stroke:#E74C3C
```
