# blushft/go-diagrams architecture

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

- Interactive diagram: https://gitdiagram.com/blushft/go-diagrams
- Repository: https://github.com/blushft/go-diagrams

## Overview

##### File structure
Top-level components:
- cmd/gen/main.go
- nodes/ – definitions of individual node types grouped by provider/category
- aws/, azure/, gcp/, k8s/, generic/, saas/, etc.
- Each subfolder holds Go files that wrap asset metadata into a Node factory
- _examples/ – sample applications showing usage patterns (app, webservice, workers, kubernetes)
- pkg/ – misc packages (e.g., rand helper)
- go.mod, go.sum – Go module configuration

##### README for additional insights
- Provider nodes as plugins/factories (nodes/aws, nodes/gcp, …) backed by static assets
- CLI frontend (cmd/gen) that wires the core API to a command-line interface
- Output integration with Graphviz for DOT → image

a. Main components to represent:
- CLI entrypoint (“gen” binary)
- Node provider packages (“nodes” directory, subdivided by cloud/saas/etc.)
- Asset repository (“assets” directory)
- Example applications (clients of the library under _examples/)
- External dependency: Graphviz engine (dot)
b. Relationships & interactions:
- The CLI calls into the core API to parse flags/options and user code.
- Edges and Groups are built by the core API.
- The core API outputs a .dot file plus copied asset images into an output folder.
- An external Graphviz process (dot) consumes the .dot file to produce final PNG/SVG.
- Examples import the core API + nodes to demonstrate usage but do not feed back into core.
c. Architectural patterns/design principles:
- API-first library design: expose builder pattern with fluent Connect/Add/Group calls.
- Separation of concerns:
- nodes/ wrap assets into typed constructors
- cmd/ implements CLI glue
- Immutable data structures for nodes/edges, functional option pattern for configuration.
d. Technologies/frameworks/libraries:
- Go modules (go.mod)
- Graphviz DOT as output format
- Standard library for CLI flags/logging

##### Detailed element checklist
- CLI → Core API
- Core API → Providers
- Providers → Assets
- Core API → .dot file (output) → Graphviz
- Examples → Core API & Providers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Entrypoint
    subgraph "CLI Layer"
        CLI["gen CLI binary"]:::cli
    end

    %% Core API
    subgraph "Core Library" 
        CoreAPI["diagram/ (Core API)"]:::core
        DiagramsEntry["diagrams.go (Convenience)"]:::core
    end

    %% Providers
    subgraph "Node Providers" 
        AWS["nodes/aws/"]:::provider
        Azure["nodes/azure/"]:::provider
        GCP["nodes/gcp/"]:::provider
        K8s["nodes/k8s/"]:::provider
        Generic["nodes/generic/"]:::provider
        SaaS["nodes/saas/"]:::provider
    end

    %% Assets
    subgraph "Asset Store"
        Assets["assets/"]:::asset
    end

    %% Example Clients
    subgraph "Examples"
        ExApp["_examples/app/main.go"]:::example
        ExWeb["_examples/webservice/main.go"]:::example
        ExWorkers["_examples/workers/main.go"]:::example
        ExK8s["_examples/kubernetes/main.go"]:::example
    end

    %% Misc Packages
    subgraph "Misc Packages"
        Rand["pkg/rand/rand.go"]:::misc
        Attr["attr/attr.go"]:::misc
    end

    %% Static Resources & Config
    subgraph "Static & Config"
        Images["images/"]:::asset
        NodesAssets["nodes/assets/assets.go"]:::asset
        GoMod["go.mod"]:::misc
        GoSum["go.sum"]:::misc
    end

    %% External Renderer
    subgraph "External Systems"
        Graphviz["Graphviz (dot)"]:::external
    end

    %% Relationships
    CLI -->|"invoke API"| CoreAPI
    CoreAPI -->|"invoke NewNode()"| AWS
    CoreAPI -->|"invoke NewNode()"| Azure
    CoreAPI -->|"invoke NewNode()"| GCP
    CoreAPI -->|"invoke NewNode()"| K8s
    CoreAPI -->|"invoke NewNode()"| Generic
    CoreAPI -->|"invoke NewNode()"| SaaS
    AWS -->|"read icon.png"| Assets
    Azure -->|"read icon.png"| Assets
    GCP -->|"read icon.png"| Assets
    K8s -->|"read icon.png"| Assets
    Generic -->|"read icon.png"| Assets
    SaaS -->|"read icon.png"| Assets
    CoreAPI -->|"write .dot file"| Graphviz
    Graphviz -->|"produce PNG/SVG"| CoreAPI
    ExApp -->|"uses API & Providers"| CoreAPI
    ExApp -->|"uses API & Providers"| AWS
    ExWeb -->|"uses API & Providers"| CoreAPI
    ExWeb -->|"uses API & Providers"| Azure
    ExWorkers -->|"uses API & Providers"| CoreAPI
    ExWorkers -->|"uses API & Providers"| GCP
    ExK8s -->|"uses API & Providers"| CoreAPI
    ExK8s -->|"uses API & Providers"| K8s

    %% Click Events
    click CLI "https://github.com/blushft/go-diagrams/blob/master/cmd/gen/main.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/diagram.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/node.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/edge.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/group.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/options.go"
    click CoreAPI "https://github.com/blushft/go-diagrams/blob/master/diagram/direction.go"
    click DiagramsEntry "https://github.com/blushft/go-diagrams/blob/master/diagrams.go"
    click AWS "https://github.com/blushft/go-diagrams/tree/master/nodes/aws/"
    click Azure "https://github.com/blushft/go-diagrams/tree/master/nodes/azure/"
    click GCP "https://github.com/blushft/go-diagrams/tree/master/nodes/gcp/"
    click K8s "https://github.com/blushft/go-diagrams/tree/master/nodes/k8s/"
    click Generic "https://github.com/blushft/go-diagrams/tree/master/nodes/generic/"
    click SaaS "https://github.com/blushft/go-diagrams/tree/master/nodes/saas/"
    click Assets "https://github.com/blushft/go-diagrams/tree/master/assets/"
    click ExApp "https://github.com/blushft/go-diagrams/blob/master/_examples/app/main.go"
    click ExWeb "https://github.com/blushft/go-diagrams/blob/master/_examples/webservice/main.go"
    click ExWorkers "https://github.com/blushft/go-diagrams/blob/master/_examples/workers/main.go"
    click ExK8s "https://github.com/blushft/go-diagrams/blob/master/_examples/kubernetes/main.go"
    click Rand "https://github.com/blushft/go-diagrams/blob/master/pkg/rand/rand.go"
    click Attr "https://github.com/blushft/go-diagrams/blob/master/attr/attr.go"
    click Images "https://github.com/blushft/go-diagrams/tree/master/images/"
    click NodesAssets "https://github.com/blushft/go-diagrams/blob/master/nodes/assets/assets.go"
    click GoMod "https://github.com/blushft/go-diagrams/blob/master/go.mod"
    click GoSum "https://github.com/blushft/go-diagrams/blob/master/go.sum"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef provider fill:#fff3cd,stroke:#856404,color:#856404;
    classDef asset fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef example fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef misc fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
