# danielyaa5/puml-for-markdown architecture

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

- Interactive diagram: https://gitdiagram.com/danielyaa5/puml-for-markdown
- Repository: https://github.com/danielyaa5/puml-for-markdown

## Overview

##### Project type and purpose
- This is an open-source CLI tool written in Node.js, called `puml-for-markdown`.

##### File structure
- Top-level:
- bin/index.js – the CLI entry point (shebang script).
- index.js – main library code.
- package.json, .npmignore, .nvmrc, .gitignore – configuration.
- .husky/pre-commit – hook wiring for auto-generating images.
- Directories:
- puml/ – sample C4-style PlantUML definitions and examples.
- Patterns:
- A single Node.js process exposing a CLI
- Separation between parsing Markdown, processing PlantUML files, calling external services, and writing outputs
- Hook integration for Git pre-commit

##### Extract architectural insights from README
- Core modules:
- Markdown parser (detects `<!--[…]-->` comments with PUML references)
- Link shortener (invokes TinyURL by default, optional full URL mode)
- HTTP clients for PlantUML server and TinyURL service
- File writers (updates Markdown in place, outputs images to `dist_puml`)
- Configurability via CLI flags: server URL, root directory, hot-reload, output formats, ignore patterns

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core Modules"
        CLI["CLI Frontend"]:::core
        Parser["Markdown Parser"]:::core
        Processor["PUML Processor & Dependency Graph"]:::core
        Encoder["Encoder Service"]:::service
        Shortener["Link Shortener Service"]:::service
        HTTP["HTTP Client"]:::service
        Writer["File System Writer"]:::core
    end

    %% External Services
    PlantUML[(PlantUML Web Service)]:::external
    TinyURL[(TinyURL Service)]:::external

    %% Storage
    MD[("Markdown File Storage")]:::support
    Dist[("Generated Diagrams (dist_puml)")]:::support

    %% Git Hook
    Hook["Git Hook Runner"]:::support

    %% Configuration & Docs
    subgraph "Configuration & Docs"
        PKG["package.json"]:::support
        NPMI[".npmignore"]:::support
        NVMRC[".nvmrc"]:::support
        GITI[".gitignore"]:::support
        README["README.md"]:::support
        CONTRIB["CONTRIBUTING.md"]:::support
        LICENSE["LICENSE.md"]:::support
        LOCK["package-lock.json"]:::support
    end

    %% Data Flows
    Hook -->|"invokes"| CLI
    CLI -->|"parse CLI flags & load config"| Parser
    CLI -->|"load config"| PKG
    Parser -->|"emit PUML references"| Processor
    Processor -->|"puml text"| Encoder
    Encoder -->|"encoded string"| HTTP
    HTTP -->|"send to PlantUML"| PlantUML
    PlantUML -->|"image/SVG URL"| HTTP
    HTTP -->|"return URL"| Encoder
    Encoder -->|"encoded URL"| Shortener
    Shortener -->|"short URL"| Writer
    Writer -->|"update .md"| MD
    Writer -->|"write images"| Dist

    %% Click Events
    click CLI "https://github.com/danielyaa5/puml-for-markdown/blob/main/bin/index.js"
    click Parser "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click Processor "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click Encoder "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click Shortener "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click HTTP "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click Writer "https://github.com/danielyaa5/puml-for-markdown/blob/main/index.js"
    click Hook "https://github.com/danielyaa5/puml-for-markdown/tree/main/.husky/pre-commit"
    click PKG "https://github.com/danielyaa5/puml-for-markdown/blob/main/package.json"
    click NPMI "https://github.com/danielyaa5/puml-for-markdown/blob/main/.npmignore"
    click NVMRC "https://github.com/danielyaa5/puml-for-markdown/blob/main/.nvmrc"
    click GITI "https://github.com/danielyaa5/puml-for-markdown/blob/main/.gitignore"
    click README "https://github.com/danielyaa5/puml-for-markdown/blob/main/README.md"
    click CONTRIB "https://github.com/danielyaa5/puml-for-markdown/blob/main/CONTRIBUTING.md"
    click LICENSE "https://github.com/danielyaa5/puml-for-markdown/blob/main/LICENSE.md"
    click LOCK "https://github.com/danielyaa5/puml-for-markdown/blob/main/package-lock.json"
    click PUML "https://github.com/danielyaa5/puml-for-markdown/tree/main/puml/"
    click Dist "https://github.com/danielyaa5/puml-for-markdown/tree/main/dist_puml/puml"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef service fill:#E6FFEA,stroke:#22863a,color:#22863a
    classDef external fill:#FFEFD5,stroke:#D47A00,color:#D47A00
    classDef support fill:#F0F0F0,stroke:#6a737d,color:#6a737d
```
