# mhlabs/cfn-diagram architecture

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

- Interactive diagram: https://gitdiagram.com/mhlabs/cfn-diagram
- Repository: https://github.com/mhlabs/cfn-diagram

## Overview

##### File structure
- Top-level:
- index.js & index.spec.js – CLI entry point and its unit test.
- graph/ – modules supporting graph generation:
– Vis.js: builds nodes/edges for the vis.js UI
- shared/ – core logic helpers: templateParser.js (walks CFN template, extracts resources and relations), templateCache.js (caches parsed templates).
- tests/ – unit tests for JsonUtil and one sample template.
- .github/ – CI workflows (Node.js build/test, npm publish).
- BUILD.md, README.md, package.json – build instructions, project description, dependencies.

##### README for additional insights
- Confirms command names, flags, default behaviors (e.g. –skip-synth for CDK, –ci-mode disables prompts).
- Mentions external integration: AWS CDK synth step (invoking CDK CLI), headless Chromium for CI screenshots in companion package.

a. Main components
1. CLI Layer
- index.js uses a command-pattern (e.g. commander.js) to dispatch subcommands.
- Each commands/<format>/index.js implements one “driver” that orchestrates parsing + generation.
2. Core Processing Layer
- shared/templateParser.js: reads & normalizes a CFN/SAM/CDK template, identifies resources, dependencies, nested stacks.
- shared/templateCache.js: caching mechanism if multiple commands reference the same template.
3. Graph Generators
- graph/Vis.js & graph/ui/: builds a JSON graph model (nodes + edges) and injects it into an HTML template with vis.js for interactive output.
- commands/asciiart: calls same parser, then renders a text-based layout via mxgraph-to-asciiart helper.
5. Utilities & Config
- resources/JsonUtil.js: file loading (YAML/JSON), error handling.
- resources/FilterConfig.js & IconMap.js: data to filter or decorate resource nodes.
6. External Integrations
- CDK CLI (child_process spawn for synth)
- AWS CloudFormation API (browse command uses AWS SDK to retrieve deployed stacks)
b. Relationships & interactions
- User invokes “cfn-dia <command>” → index.js → appropriate commands/<cmd>/index.js.
- That module:
1. Loads template with JsonUtil → passes through templateParser → yields resource graph.
2. Optionally invokes CDK synth or AWS SDK browse.
4. Writes output to file system (or stdout).
c. Architectural patterns / design principles
- Command Pattern: isolates each output format’s logic.
- Separation of concerns: parsing, caching, graph model, and rendering are decoupled.
- Plugin-like extensibility: new output format = new commands/<new>/module + generator.
- Data flow is linear: Input → Parse → Model → Render → Output.
d. Key technologies / frameworks
- Node.js, commander.js (CLI), YAML parser, AWS SDK, child_process (CDK), vis.js, mxGraph XML, JSON graph models.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        CLI["index.js"]:::cli
        CLItest["index.spec.js"]:::cli
        ASCII["commands/asciiart/index.js"]:::cli
        Browse["commands/browse/index.js"]:::cli
        DrawIO["commands/draw.io/index.js"]:::cli
        HTMLCMD["commands/html/index.js"]:::cli
        MermaidCMD["commands/mermaid/index.js"]:::cli
    end

    subgraph "Core Logic"
        Parser["shared/templateParser.js"]:::core
        Cache["shared/templateCache.js"]:::core
    end

    subgraph "Resources/Utilities"
        JsonUtil["resources/JsonUtil.js"]:::util
        FilterConf["resources/FilterConfig.js"]:::util
        IconMap["resources/IconMap.js"]:::util
    end

    subgraph "Graph Generators"
        MxGen["graph/MxGenerator.js"]:::gen
        VisGen["graph/Vis.js"]:::gen
        ASCIIHelper["commands/asciiart/mxgraph-to-asciiart.js"]:::gen
    end

    subgraph "Vis.js UI"
        VisUIPage["graph/ui/index.html"]:::gen
        VisUISingle["graph/ui/index_standalone.template"]:::gen
        VisUIIcons["graph/ui/icons.js"]:::gen
    end

    subgraph "Tests"
        JsonUtilTest["JsonUtil.spec.js"]:::core
        SampleTemplate["template.json"]:::core
    end

    subgraph "External Integrations"
        AWSCLI["AWS CDK CLI"]:::ext
        AWSSDK["AWS SDK"]:::ext
        DrawIOView["draw.io viewer"]:::ext
        VisjsRuntime["vis.js runtime"]:::ext
    end

    %% CLI dispatch
    CLI -->|"dispatch"| ASCII
    CLI -->|"dispatch"| Browse
    CLI -->|"dispatch"| DrawIO
    CLI -->|"dispatch"| HTMLCMD
    CLI -->|"dispatch"| MermaidCMD

    %% Parsing flow
    ASCII -->|"parseTemplate()"| JsonUtil
    Browse -->|"parseTemplate()"| JsonUtil
    DrawIO -->|"parseTemplate()"| JsonUtil
    HTMLCMD -->|"parseTemplate()"| JsonUtil
    MermaidCMD -->|"parseTemplate()"| JsonUtil

    JsonUtil -->|"load()"| Parser
    Parser -->|"cache lookup"| Cache
    Parser -->|"filter types"| FilterConf
    Parser -->|"map icons"| IconMap

    %% Generation
    ASCII -->|"toAscii()"| ASCIIHelper
    DrawIO -->|"generateXml()"| MxGen
    HTMLCMD -->|"buildGraph()"| VisGen
    MermaidCMD -->|"serializeMermaid"| MerchGen["Mermaid DSL"]:::gen

    VisGen -->|"inject UI"| VisUIPage
    VisGen -->|"inject UI"| VisUISingle
    VisGen -->|"load icons"| VisUIIcons
    VisGen -->|"runtime"| VisjsRuntime

    %% External calls
    Browse -->|"awsBrowse()"| AWSSDK
    Browse -->|"cdkSynth()"| AWSCLI

    %% Tests
    JsonUtilTest -->|"unit tests"| JsonUtil
    JsonUtilTest -->|"uses"| SampleTemplate

    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef util fill:#bfb,stroke:#333,stroke-width:1px
    classDef gen fill:#ffb,stroke:#333,stroke-width:1px
    classDef ext fill:#fbf,stroke:#333,stroke-width:1px

    %% Click Events
    click CLI "https://github.com/mhlabs/cfn-diagram/blob/master/index.js"
    click CLItest "https://github.com/mhlabs/cfn-diagram/blob/master/index.spec.js"
    click ASCII "https://github.com/mhlabs/cfn-diagram/blob/master/commands/asciiart/index.js"
    click ASCIIHelper "https://github.com/mhlabs/cfn-diagram/blob/master/commands/asciiart/mxgraph-to-asciiart.js"
    click Browse "https://github.com/mhlabs/cfn-diagram/blob/master/commands/browse/index.js"
    click DrawIO "https://github.com/mhlabs/cfn-diagram/blob/master/commands/draw.io/index.js"
    click HTMLCMD "https://github.com/mhlabs/cfn-diagram/blob/master/commands/html/index.js"
    click MermaidCMD "https://github.com/mhlabs/cfn-diagram/blob/master/commands/mermaid/index.js"
    click MxGen "https://github.com/mhlabs/cfn-diagram/blob/master/graph/MxGenerator.js"
    click VisGen "https://github.com/mhlabs/cfn-diagram/blob/master/graph/Vis.js"
    click VisUIPage "https://github.com/mhlabs/cfn-diagram/blob/master/graph/ui/index.html"
    click VisUISingle "https://github.com/mhlabs/cfn-diagram/blob/master/graph/ui/index_standalone.template"
    click VisUIIcons "https://github.com/mhlabs/cfn-diagram/blob/master/graph/ui/icons.js"
    click JsonUtil "https://github.com/mhlabs/cfn-diagram/blob/master/resources/JsonUtil.js"
    click FilterConf "https://github.com/mhlabs/cfn-diagram/blob/master/resources/FilterConfig.js"
    click IconMap "https://github.com/mhlabs/cfn-diagram/blob/master/resources/IconMap.js"
    click Parser "https://github.com/mhlabs/cfn-diagram/blob/master/shared/templateParser.js"
    click Cache "https://github.com/mhlabs/cfn-diagram/blob/master/shared/templateCache.js"
    click JsonUtilTest "https://github.com/mhlabs/cfn-diagram/blob/master/tests/resources/JsonUtil.spec.js"
    click SampleTemplate "https://github.com/mhlabs/cfn-diagram/blob/master/tests/template.json"
```
