# awslabs/aws-icons-for-plantuml architecture

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

- Interactive diagram: https://gitdiagram.com/awslabs/aws-icons-for-plantuml
- Repository: https://github.com/awslabs/aws-icons-for-plantuml

## Overview

##### File Structure Analysis
- Top-level directories:
- `scripts/` contains Python scripts, PlantUML jars, Batik libs, config files and test harnesses to generate the distribution.
- Configuration & metadata:
- `.github/` & `.vscode/` for repo settings and CI templates.
- `README.md`, `CONTRIBUTING.md`, license files.

##### README Insights
- Emphasizes how users include `AWSCommon.puml` and other `dist/` assets into PlantUML.
- Details build & distribution process (see `scripts/README.md`).

a. Main Components
- **Version Control (GitHub)** – hosts source, scripts, examples, dist, CI workflows.
- **Source Assets** – raw SVGs and intermediate PUML in `source/official` and `source/unofficial`.
- **Distribution Artifact** – generated `.puml` files under `dist/`, plus JSON theme files.
- **CI/CD Pipeline** – GitHub Actions triggers tests (`scripts/test_upgrade.py`), build, version bump, release.

b. Relationships & Interactions
1. Contributor pushes code → GitHub (Version Control).
2. CI/CD workflow picks up PR/commit → runs tests & build scripts.
3. Build Engine reads `source/` and `scripts/config.yml` → transforms SVGs to `.puml` (via Batik + PlantUML jars) → writes `dist/`.
4. On success → CI/CD packages `dist/` into a release artifact (GitHub Release, npm? etc.).
5. Examples reference the new `dist/` → rendered by PlantUML and published in docs.

c. Architectural Patterns & Principles
- **Separation of Concerns**: raw assets vs. build logic vs. generated artifacts vs. examples.
- **Code-as-Documentation**: `examples/` serve as runnable guides.
- **Extensibility**: new AWS services added by dropping SVGs in `source/` and updating config.

d. Key Technologies & Frameworks
- Python 3.x scripts for orchestration (`requirements.txt`).
- PlantUML (multiple versions bundled as JARs) + Batik (SVG rasterizer).
- YAML configs (`scripts/config.yml`) drive file naming/version.
- GitHub Actions (workflow definitions in `.github/workflows/`).
- Markdown & PlantUML C4 model for examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Contributors and Version Control
    Contributor(("Contributor")):::user
    subgraph "Version Control" 
        VC["GitHub Repository"]:::code
    end
    Contributor -->|"push code"| VC
    click VC "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/.github/"

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        CI["GitHub Actions"]:::ci
        PR["Pull Request Template"]:::code
        CI -->|"runs workflows"| Build
        click PR "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    end
    VC -->|"trigger CI"| CI

    %% Source Assets
    subgraph "Source Assets" 
        SO["Official SVGs & PUML"]:::code
        SU["Unofficial SVG Packs"]:::code
        SP1["AWSCommon.puml"]:::code
        SP2["AWSSimplified.puml"]:::code
        SP3["AWSRaw.puml"]:::code
        SP4["AWSExperimental.puml"]:::code
        SP5["AWSC4Integration.puml"]:::code
    end
    click SO "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/source/official/"
    click SU "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/source/unofficial/"
    click SP1 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/source/AWSCommon.puml"
    click SP2 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/source/AWSSimplified.puml"
    click SP3 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/source/AWSRaw.puml"
    click SP4 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/source/AWSExperimental.puml"
    click SP5 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/source/AWSC4Integration.puml"

    %% Build Engine
    subgraph "Build Engine" 
        IB["icon-builder.py"]:::code
        UP["upgrade.py"]:::code
        TU["test_upgrade.py"]:::code
        CFG["config.yml"]:::code
        BAT["batik-1.16/"]:::code
        PUM["plantuml-mit-*.jar"]:::code
        HTTP["http_server_cors.py"]:::code
        REQ["requirements.txt"]:::code
    end
    click IB "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/icon-builder.py"
    click UP "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/upgrade.py"
    click TU "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/test_upgrade.py"
    click CFG "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/config.yml"
    click BAT "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/scripts/batik-1.16/"
    click PUM "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/plantuml-mit-*.jar"
    click HTTP "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/http_server_cors.py"
    click REQ "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/requirements.txt"

    %% Distribution Artifacts
    subgraph "Distribution Artifacts" 
        D1["Root PUML Includes"]:::artifact
        D2["Service Category Folders"]:::artifact
        D3["JSON Themes"]:::artifact
    end
    click D1 "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/dist/"
    click D2 "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/dist/Analytics/"
    click D3 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/dist/aws-icons-mermaid.json"

    %% Examples & Documentation
    subgraph "Examples & Documentation"
        EX["examples/"]:::example
        MD1["README.md"]:::example
        MD2["CONTRIBUTING.md"]:::example
        MD3["CODE_OF_CONDUCT.md"]:::example
        SDOC["scripts/README.md"]:::example
    end
    click EX "https://github.com/awslabs/aws-icons-for-plantuml/tree/main/examples/"
    click MD1 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md"
    click MD2 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/CONTRIBUTING.md"
    click MD3 "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/CODE_OF_CONDUCT.md"
    click SDOC "https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md"

    %% External Services
    subgraph "External Services" 
        AWSICON(("AWS Icon Source")):::external
        PLANTUML(("PlantUML Engine")):::external
        GHRELEASE(("GitHub Releases API")):::external
    end

    %% End Users
    EndUser(("End User")):::user

    %% Data Flows
    VC -->|"source code"| SO
    VC -->|"source code"| SU
    CI -->|"executes"| IB
    CI -->|"executes"| UP
    CI -->|"executes"| TU
    IB -->|"reads"| SO
    IB -->|"reads"| SU
    IB -->|"reads config"| CFG
    IB -->|"calls"| BAT
    IB -->|"calls"| PUM
    IB -->|"uses"| HTTP
    IB -->|"installs"| REQ
    IB -->|"generates"| D1
    IB -->|"generates"| D2
    IB -->|"generates"| D3
    CI -->|"packages"| D1
    CI -->|"packages"| D2
    CI -->|"packages"| D3
    CI -->|"publishes release"| GHRELEASE
    D1 -->|"referenced by"| EX
    D2 -->|"referenced by"| EX
    D3 -->|"referenced by"| EX
    EX -->|"used by"| EndUser
    EndUser -->|"includes PUML"| PLANTUML
    IB -->|"pulls assets from"| AWSICON

    %% Styles
    classDef code fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef artifact fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef ci fill:#FFE0B2,stroke:#F57C00,color:#E65100;
    classDef example fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#FFCDD2,stroke:#E53935,color:#B71C1C;
    classDef user fill:#FFF9C4,stroke:#FBC02D,color:#F57F17;
```
