### Start PlantUML Local Render Server

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Start a local PlantUML render server using the provided JAR file. Security profile and allowlist configurations may be necessary.

```bash
java -jar scripts/plantuml-mit-1.2026.2.jar -picoweb
```

--------------------------------

### Run Upgrade Script

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the upgrade script from the examples folder to update PlantUML files. This script can be run in read-only mode or with overwrite capabilities.

```bash
uv run upgrade.sh
```

--------------------------------

### Full Example with Multiple Includes

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Demonstrates defining the AWSPuml macro, including AWSCommon.puml, and then including specific service files or category files. Use release tags for production diagrams.

```plantuml
' Define the main location (URL or local file path)
!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
' Include main AWSCommon and then resource files
!include AWSPuml/AWSCommon.puml
!include AWSPuml/BusinessApplications/all.puml
!include AWSPuml/Storage/SimpleStorageService.puml
```

--------------------------------

### Hello World PlantUML Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

A basic 'Hello World' example demonstrating how to include AWS common files and specific services, then use them to draw elements and relationships. Uncomment the dark mode variable for styling.

```plantuml
@startuml Hello World
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/BusinessApplications/all.puml
!include AWSPuml/Storage/SimpleStorageService.puml

actor "Person" as personAlias
WorkDocs(desktopAlias, "Label", "Technology", "Optional Description")
SimpleStorageService(storageAlias, "Label", "Technology", "Optional Description")

personAlias --> desktopAlias
desktopAlias --> storageAlias

@enduml
```

--------------------------------

### Run Local HTTP Server (CORS)

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Start a local HTTP server in the dist directory with CORS support. This is necessary for testing Structurizr themes or Mermaid icons.

```bash
cd dist
uv run python ../scripts/http_server_cors.py
```

--------------------------------

### Mermaid Generic Icons Architecture Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Example of a basic Mermaid architecture diagram using generic icons. Ensure Mermaid syntax is correctly rendered.

```mermaid
architecture-beta
 group api(cloud)[API]
    
        service db(database)[Database] in api
        service disk1(disk)[Storage] in api
        service disk2(disk)[Storage] in api
        service server(server)[Server] in api
    
        db:L -- R:server
        disk1:T -- B:server
        disk2:T -- B:db  
    
```

--------------------------------

### S3 Upload Workflow Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/s3-upload-workflow/S3 Upload Workflow - mermaid.html

Mermaid diagram illustrating an S3 upload workflow with AWS services. This example uses the architecture syntax to define services and their interactions.

```mermaid
architecture-beta
  service user(aws:user)[User]
  group awscloud(aws:aws-cloud)[AWS Cloud]
  group region(aws:region)[Region] in awscloud

  group s3bucket(aws:simple-storage-service)[Amazon S3 bucket] in region

    service video(aws:multimedia)[video] in s3bucket
    service audio(aws:tape-storage)[audio] in s3bucket
    service transcript(aws:documents)[transcript] in s3bucket
    
    user:R -[1 upload]-> L:video
    video:R --> L:audio
    audio:R --> L:transcript

  service handler(aws:lambda-lambda-function)[ObjectCreated event handler] in region
  service mediaconvert(aws:elemental-mediaconvert)[AWS Elemental MediaConvert] in region
  service transcribe(aws:transcribe)[Amazon Transcribe] in region

  handler:T <-[2]- B:video
  mediaconvert:T -[3]-> B:audio
  transcribe:T -[4]-> B:transcript

  group workflow(aws:step-functions-workflow)[AWS Step Functions workflow] in region

    service extractaudio(aws:lambda-lambda-function)[extract audio] in workflow
    service transcribeaudio(aws:lambda-lambda-function)[transcribe audio] in workflow

    extractaudio:R --> L:transcribeaudio
    extractaudio{group}:L <-[Start Execution]- B:handler
    extractaudio:T --> B:mediaconvert
    transcribeaudio:T --> B:transcribe
```

--------------------------------

### Mermaid AWS Icons from Iconify Architecture Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Architecture diagram using AWS icons sourced from iconify.design within Mermaid. This example highlights the use of 'logos:aws-' prefixes.

```mermaid
architecture-beta
    group api(logos:aws-lambda)[API]
    
        service db(logos:aws-aurora)[Database] in api
        service disk1(logos:aws-glacier)[Storage] in api
        service disk2(logos:aws-s3)[Storage] in api
        service server(logos:aws-ec2)[Server] in api
    
        db:L -- R:server
        disk1:T -- B:server
        disk2:T -- B:db  
    
```

--------------------------------

### Mermaid AWS Icons from aws-icons-for-plantuml Architecture Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Architecture diagram using AWS icons from the aws-icons-for-plantuml library within Mermaid. This example uses 'aws:' prefixes and custom theme variables.

```mermaid
---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#ED7100"
---
      architecture-beta
        group api(aws:lambda)[API]
    
        service db(aws:aurora)[Database] in api
        service disk1(aws:simple-storage-service-glacier)[Storage] in api
        service disk2(aws:simple-storage-service)[Storage] in api
        service server(aws:ec2)[Server] in api
    
        db:L <-- R:server
        disk1:T <-- B:server
        disk2:T <-- B:db  
    
```

--------------------------------

### Check Environment Prerequisites

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute this command to verify that all necessary prerequisites for the icon builder are met. It will exit if the environment is ready.

```bash
$ uv run icon-builder.py --check-env
Prerequisites met, exiting
```

--------------------------------

### Check Environment Dependencies for Icon Builder

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Use this command to verify that all necessary prerequisites are met before running the icon builder script. If all dependencies are satisfied, it will confirm and exit.

```bash
uv run icon-builder.py --check-env
Prerequisites met, exiting
```

--------------------------------

### Run Icon Builder Script

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the icon builder script to create a configuration template. This is a preliminary step before generating the final configuration.

```bash
uv run icon-builder.py --create-config-template
```

--------------------------------

### Mermaid Initialization with AWS Icons

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Initializes Mermaid.js with custom AWS icons loaded from a JSON file and registers the 'logos' icon pack. Requires a local server to fetch icons.

```javascript
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.13.0/dist/mermaid.esm.mjs'; let baseUrl = 'http://localhost:8000'; let icons = await fetch(`${baseUrl}/aws-icons-mermaid.json`).then((res) => res.json()); // https://mermaid.js.org/config/icons.html mermaid.registerIconPacks([ { name: 'logos', loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()), }, { name: 'aws', loader: () => icons }, ]); mermaid.initialize({ startOnLoad: true });
```

--------------------------------

### AWS Cloud Diagram with Configuration

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Illustrates an AWS Cloud architecture with API Gateway, Lambda, and DynamoDB. Includes theme configuration.

```plantuml
---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#7D8998"
---
architecture-beta
  service client(aws:client)[Client]
  group awscloud(aws:aws-cloud)[AWS Cloud]
    service api(aws:api-gateway)[Amazon API Gateway] in awscloud
    service lambda1(aws:lambda)[AWS Lambda] in awscloud
    service dynamodb(aws:dynamodb)[Amazon DynamoDB] in awscloud

    client:R -[1]-> L:api
    api:R -[2]-> L:lambda1
    lambda1:R -[3]-> L:dynamodb

    junction junctionLeft
    service s3(aws:simple-storage-service)[Amazon S3] in awscloud
    service lambda2(aws:lambda)[AWS Lambda] in awscloud
    junction junctionRight

    client:B -- T:junctionLeft
    junctionLeft:R -[4]-> L:s3
    s3:R -[5]-> L:lambda2

    lambda2:R -[6]- L:junctionRight
    junctionRight:T --> B:dynamodb
```

--------------------------------

### Mermaid Architecture Diagram: AWS CodePipeline

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/README.md

An example of an `architecture-beta` Mermaid diagram representing an AWS CodePipeline workflow, including services like CodeBuild, CodeDeploy, and S3. This diagram uses AWS icons for services.

```mermaid
---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#C925D1"
---
architecture-beta
  group cp(aws:codepipeline)[AWS CodePipeline]

    service gr(aws:git-repository)[Git Repository] in cp
    service cb(aws:codebuild)[AWS CodeBuild] in cp
    service cd1(aws:codedeploy)[AWS CodeDeploy] in cp
    service s3(aws:simple-storage-service)[Amazon S3 artifact store] in cp
    service user(aws:user)[Human Approval] in cp
    service dev(aws:ec2)[Amazon EC2 dev] in cp
    service cd2(aws:codedeploy)[AWS CodeDeploy] in cp
    service prod(aws:ec2)[Amazon EC2 prod] in cp
    service sns(aws:simple-notification-service)[SNS Notification] in cp

    gr:R --> L:cb
    cb:R --> L:cd1
    cb:B --> T:s3
    cd1:R --> L:user
    cd1:B --> T:dev
    user:R --> L:cd2
    cd2:B --> T:prod
    cd2:R --> L:sns
```

--------------------------------

### Include AWSCommon.puml from Local Path

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Include the AWSCommon.puml file from a local path. This method is suitable when the library is downloaded and stored locally.

```plantuml
!include path/to/AWSCommon.puml
```

--------------------------------

### Generate All Icons

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Run the icon-builder script without parameters to generate all new icons and update the config.yml file. This process may take several minutes.

```bash
$ uv run icon-builder.py
```

--------------------------------

### Create New config.yml

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Run this command to create a new default config.yml file from the template. You can rename an existing config.yml to preserve custom settings.

```bash
$ uv run icon-builder.py --create-config-template
../source/AWSCommon.puml
Successfully created config-template.yml
$ mv config-template.yml config.yml
```

--------------------------------

### Initialize Mermaid with AWS Icon Packs

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/README.md

This JavaScript code initializes Mermaid, registers custom icon packs including AWS icons from a local JSON file, and sets up the Mermaid instance for use. Ensure the 'dist' folder is served locally.

```javascript
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.mjs';
let baseUrl = 'http://localhost:8000';
let icons = await fetch(`${baseUrl}/aws-icons-mermaid.json`).then((res) => res.json());
mermaid.registerIconPacks([
  {
    name: 'logos',
    loader: () =>
      fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
  },
  {
    name: 'aws',
    loader: () => icons
  },
]);
mermaid.initialize({ startOnLoad: true });
```

--------------------------------

### Run Icon Builder Script

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the main icon builder script to generate output files after configuration. This script processes the icons and creates various output formats.

```bash
uv run icon-builder.py
```

--------------------------------

### Include AWSCommon.puml from GitHub URL

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Include the main AWSCommon.puml file directly from the GitHub repository URL. Ensure you use a specific release version (e.g., v23.0) instead of the main branch for stability.

```plantuml
!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist/AWSCommon.puml
```

--------------------------------

### Run Upgrade Script in Read-Only Mode

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the upgrade script in read-only mode to preview changes without modifying files. This is the default behavior.

```bash
uv run upgrade.py file.puml
```

--------------------------------

### Sequence Diagram with Image Tags and Custom Styling

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

This snippet demonstrates generating a sequence diagram using image tags and applying custom styling for colors, text positioning, and stereotypes. It offers more control over the visual appearance.

```plantuml
@startuml Sequence Diagram - Images
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/AWSExperimental.puml
!include AWSPuml/Compute/Lambda.puml
!include AWSPuml/NetworkingContentDelivery/APIGateway.puml
!include AWSPuml/General/Internetalt1.puml
!include AWSPuml/General/User.puml
!include AWSPuml/Database/DynamoDB.puml

'Hide the bottom boxes / Use filled triangle arrowheads
hide footbox
skinparam style strictuml

skinparam MaxMessageSize 200

participant "$UserIMG()\nUser" as user
box AWS Cloud
'Instead of using ...Participant(), native creole img tags can be used
participant "$APIGatewayIMG()\nCredit Card System\nAll methods are POST" as api << REST API >>
participant "$LambdaIMG()\nAuthorizeCard\nReturns status" as lambda << python3.9 >>
participant "PaymentTransactions\n$DynamoDBIMG()\nsortkey=transaction_id+token" as db << on-demand >>
endbox
participant "Authorizer\nReturns status and token\n$Internetalt1IMG()" as processor

'Use shortcut syntax for activation with colored lifelines and return keyword
user -> api++ $AWSColor(ApplicationIntegration): <$Callout_1> Process transaction\l<$Callout_SP> "POST /prod/process"
api -> lambda++ $AWSColor(Compute): <$Callout_2> Invokes lambda with\l<$Callout_SP> cardholder details
lambda -> processor++ $AWS_COLOR_SQUID: <$Callout_3> Submit via API token\l<$Callout_SP> card number, expiry, CID
processor -> processor: Validate and\lcreate token
return status code, token
lambda ->> db: PUT transaction id, token
return status code,\rtransaction id
return status code
@enduml
```

--------------------------------

### Mermaid Generic Architecture Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/README.md

This Mermaid `architecture-beta` diagram demonstrates the use of generic icons for services like API, Database, Storage, and Server within a group.

```mermaid
architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service disk2(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db
```

--------------------------------

### Check PlantUML Version

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the PlantUML JAR with the -version parameter to check its version and license information.

```bash
$ java -jar scripts/plantuml-mit-1.2026.2.jar -version
PlantUML version 1.2026.2 / bb8550d [2026-02-27 17:45:29 UTC]
(MIT source distribution)
```

--------------------------------

### Run Upgrade Script with Overwrite

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the upgrade script with the --overwrite flag to modify PlantUML files directly. Supports filename wildcards for batch updates.

```bash
uv run upgrade.py --overwrite "*.puml"
```

--------------------------------

### Basic AWS IoT Rules Engine Usage

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Illustrates a simple AWS architecture workflow using AWS service entities for message processing via the Rules Engine, including an error action. Enable dark mode by uncommenting '!$AWS_DARK = true'.

```plantuml
@startuml Basic Usage - AWS IoT Rules Engine
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/InternetOfThings/IoTRule.puml
!include AWSPuml/Analytics/KinesisDataStreams.puml
!include AWSPuml/ApplicationIntegration/SimpleQueueService.puml

left to right direction

agent "Published Event" as event 

IoTRule(iotRule, "Action Error Rule", "error if Kinesis fails")
KinesisDataStreams(eventStream, "IoT Events", "2 shards")
SimpleQueueService(errorQueue, "Rule Error Queue", "failed Rule actions")

event --> iotRule : JSON message
iotRule --> eventStream : messages
iotRule --> errorQueue : Failed action message

@enduml
```

--------------------------------

### Configure VS Code PlantUML Extension

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Update your VS Code settings.json to use the local PlantUML server for rendering. Ensure the server address matches the one you are running.

```json
  "plantuml.render": "PlantUMLServer",
  "plantuml.server": "http://localhost:8080/plantuml/"
```

--------------------------------

### AWS Marketplace and CloudFront Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Depicts a more complex AWS architecture involving Marketplace, Lambda Edge, CloudFront, and S3. Includes theme configuration.

```plantuml
---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#7D8998"
---
architecture-beta
  service users(aws:users)[Customers]
  group awscloud(aws:aws-cloud)[AWS Cloud]
    service marketplace(aws:marketplace)[AWS Marketplace] in awscloud
    service edge(aws:cloudfront-edge-location)[Lambda Edge] in awscloud
    service cloudfront(aws:cloudfront)[Amazon CloudFront] in awscloud
    service s3(aws:simple-storage-service)[Amazon S3] in awscloud

    service page(aws:documents)[Registration Page] in awscloud

    service api(aws:api-gateway)[Amazon API Gateway] in awscloud
    service lambda(aws:lambda)[AWS Lambda] in awscloud
    service dynamodb(aws:dynamodb)[Amazon DynamoDB] in awscloud

    users:R --> L:marketplace
    users:B --> L:page
    marketplace:B --> T:page
    marketplace:R --> L:edge
    edge:R --> L:cloudfront
    cloudfront:B --> R:page
    cloudfront:R --> L:s3

    page:B --> T:api

    api:R --> L:lambda
    lambda:R --> L:dynamodb
```

--------------------------------

### Run Pytest for Upgrade Script

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Execute the pytest suite to test the functionality of the upgrade script. This ensures the script correctly handles icon and category updates.

```bash
uv run pytest test_upgrade.py
```

--------------------------------

### Define Local PUML Include Path

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Redefine the AWSPuml macro in your .puml file to point to your local web server when including .puml files from the dist directory.

```plantuml
!define AWSPuml http://localhost:8000
```

--------------------------------

### Basic AWS Service Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Defines AWS services and their relationships in a simple diagram. Uses PlantUML syntax.

```plantuml
service prod(aws:ec2)[Amazon EC2 prod] in cp
service sns(aws:simple-notification-service)[SNS Notification] in cp

gr:R --> L:cb
cb:R --> L:cd1
cb:B --> T:s3
cd1:R --> L:user
cd1:B --> T:dev
user:R --> L:cd2
cd2:B --> T:prod
cd2:R --> L:sns
```

--------------------------------

### Define AWSPuml Macro for GitHub URL

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Define a macro 'AWSPuml' to point to the distribution directory on GitHub. This simplifies subsequent include statements. It's recommended to use a specific release version.

```plantuml
!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
```

--------------------------------

### Sequence Diagram with Participant Macros

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Use this snippet to generate a detailed UML sequence diagram with AWS icons using participant macros. It requires including common AWS and specific service definitions.

```plantuml
@startuml Sequence Diagram - Technical
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/Compute/all.puml
!include AWSPuml/NetworkingContentDelivery/APIGateway.puml
!include AWSPuml/General/Internetalt1.puml
!include AWSPuml/Database/DynamoDB.puml

actor User as user
APIGatewayParticipant(api, Credit Card System, All methods are POST)
LambdaParticipant(lambda, AuthorizeCard,)
DynamoDBParticipant(db, Payment Transactions, sortkey=transaction_id+token)
Internetalt1Participant(processor, Authorizer, Returns status and token)

user -> api: Process transaction
POST /prod/process
api -> lambda: Invokes lambda with cardholder details
lambda -> processor: Submit via API token
card number, expiry, CID
processor -> processor: Validate and create token
processor -> lambda: Returns status code and token
lambda -> db: PUT transaction id, token
lambda -> api: Returns
status code, transaction id
api -> user: Returns status code
@enduml
```

--------------------------------

### Create Color JSON Mapping

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Run this command to generate the JSON structure for AWS category colors. This is useful when new categories are added or colors are updated. The output needs to be manually copied into AWSCommon.puml.

```bash
$ uv run icon-builder.py --create-color-json
```

--------------------------------

### Basic Cognito Sequence Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/cognito-scenario/README.md

This snippet uses basic PlantUML syntax to define participants, messages, and an alt fragment for a Cognito authentication flow.

```plantuml
@startuml Amazon S3 objects using IAM Temporary Credentials

title Amazon S3 objects using IAM Temporary Credentials
' compare with https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html

participant "User" as user
participant "Cognito User Pool" as userpool
participant "Cognito Identity Pool" as idpool
participant "S3 Bucket" as s3
participant "STS" as sts
participant "IAM Policy" as permissions

' 1. Authenticate and get tokens
user -> userpool: InitiateAuth
user <-- userpool: ID Token and Access Token

' 2. Exchange tokens for AWS credentials
user -> idpool: GetCredentialsForIdentity
idpool -> idpool: map to IAM Role
idpool -> sts: AssumeRoleWithWebIdentity(Role)
idpool <-- sts: temporary security credentials
user <-- idpool: temporary security credentials

' 3. Access AWS services with credentials
user -> s3: GetObject
s3 -> permissions: check permissions
alt no access
  s3 <-- permissions: Deny
  user <-- s3: error (AccessDenied)
else access
  s3 <-- permissions: Allow
  user <-- s3: S3 object
end

@enduml
```

--------------------------------

### Mermaid AWS Cloud and VPC Architecture Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/mermaid-js/mermaid.html

Detailed architecture diagram of AWS Cloud, VPC, Availability Zones, NAT Gateways, and EC2 instances using aws-icons-for-plantuml. Includes custom theme variables.

```mermaid
---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#7D8998"
---
      architecture-beta
        group awscloud(aws:aws-cloud)[AWS Cloud]
        group vpc(aws:vpc)[Virtual private cloud] in awscloud

        group az2[Availability Zone 2] in vpc
          service nat2(aws:vpc-nat-gateway)[NAT gateway] in az2
          service instance21(aws:ec2-instance)[Instance] in az2
          service instance22(aws:ec2-instance)[Instance] in az2
          
        group az1[Availability Zone 1] in vpc
          service nat1(aws:vpc-nat-gateway)[NAT gateway] in az1
          service instance11(aws:ec2-instance)[Instance] in az1
          service instance12(aws:ec2-instance)[Instance] in az1

        group asg1(aws:auto-scaling-group)[Auto Scaling group] in vpc
          service asgr1(aws:ec2-auto-scaling-resource) in asg1
        group asg2(aws:auto-scaling-group)[Auto Scaling group] in vpc
          service asgr2(aws:ec2-auto-scaling-resource) in asg2

        service asg(aws:ec2-auto-scaling)[Amazon EC2 Auto Scaling] in vpc
        
        asg:B -- T:asgr1{group}
        asgr1{group}:B -- T:asgr2{group}

        instance21:L -- R:asgr1{group}
        instance22:L -- R:asgr2{group}

        instance11:R -- L:asgr1{group}
        instance12:R -- L:asgr2{group}
    
```

--------------------------------

### PlantUML Diagram with AWS Icons and Colors

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/examples/cognito-scenario/README.md

This PlantUML script defines a diagram illustrating Amazon S3 object access using IAM temporary credentials. It includes definitions for AWS icons, custom colors, and a sequence of interactions between users, Cognito, IAM, and S3.

```plantuml
@startuml Amazon S3 objects using IAM Temporary Credentials

title Amazon S3 objects using IAM Temporary Credentials
' compare with https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html

' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v22.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/AWSExperimental.puml
!include AWSPuml/General/User.puml
!include AWSPuml/General/SAMLtoken.puml
!include AWSPuml/SecurityIdentityCompliance/Cognito.puml
!include AWSPuml/SecurityIdentityCompliance/IdentityAccessManagementPermissions.puml
!include AWSPuml/SecurityIdentityCompliance/IdentityAccessManagementAWSSTSAlternate.puml
!include AWSPuml/SecurityIdentityCompliance/IdentityAccessManagementTemporarySecurityCredential.puml
!include AWSPuml/SecurityIdentityCompliance/IdentityAccessManagementRole.puml
!include AWSPuml/Storage/SimpleStorageServiceBucket.puml
!include AWSPuml/Storage/SimpleStorageServiceObject.puml

hide footbox
skinparam style strictuml

skinparam Sequence {
    MessageAlignment left
}
skinparam Note {
  TextAlignment left 
  FontColor black
  BackgroundColor %lighten($AWS_COLOR_SMILE, 90)
}
skinparam WrapWidth 300
skinparam MaxMessageSize 600

!procedure $AWSIcon($service, $line1, $line2="")
participant "$AWSImg($service)\n<b>$line1</b>\n$line2"
!endprocedure 

$AWSIcon(User, " ", "User") as user <<Tenant 1>>
$AWSIcon(Cognito, "User Pool", "Amazon Cognito") as userpool
$AWSIcon(Cognito, "Identity Pool", "Amazon Cognito") as idpool
$AWSIcon(SimpleStorageServiceBucket, "Bucket", "Amazon S3") as s3 <<Multi-Tenant>>
$AWSIcon(IdentityAccessManagementAWSSTSAlternate, " ", "AWS STS") as sts
$AWSIcon(IdentityAccessManagementPermissions, "Policy", "AWS IAM") as permissions

note over userpool
  1. Authenticate and get tokens
end note
user -> userpool++ $AWSColor(SecurityIdentityCompliance): InitiateAuth
return ID Token and Access Token
note<<AWSIcon>> left
  $SAMLtokenIMG("0.5") $SAMLtokenIMG("0.5")
end note

note over idpool
  2. Exchange tokens for AWS credentials
end note
user -> idpool++ $AWSColor(SecurityIdentityCompliance): GetCredentialsForIdentity
idpool -> idpool: map to IAM Role
$AWSIconLeft(IdentityAccessManagementRole)
idpool -> sts++ $AWSColor(SecurityIdentityCompliance): AssumeRoleWithWebIdentity(Role)
return temporary security credentials
$AWSIconLeft(IdentityAccessManagementTemporarySecurityCredential)
return temporary security credentials
$AWSIconLeft(IdentityAccessManagementTemporarySecurityCredential)

note over s3
  3. Access AWS services with credentials
end note
user -> s3++ $AWSColor(Storage): GetObject
s3 -> permissions++ $AWSColor(SecurityIdentityCompliance): check permissions
alt no access
  permissions --> s3: ❌  Deny
  s3 --> user: error (AccessDenied)
else access
  return ✅  Allow
  return S3 object
  $AWSIconLeft(SimpleStorageServiceObject)
end

@enduml
```

--------------------------------

### VPC with Availability Zones and Subnets

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

This snippet defines a VPC with multiple Availability Zones and subnets, including NAT gateways and EC2 instances. It uses predefined group macros for AWS Cloud, VPC, Availability Zone, and Subnets.

```plantuml
@startuml VPC
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/AWSSimplified.puml
!include AWSPuml/Compute/EC2.puml
!include AWSPuml/Compute/EC2Instance.puml
!include AWSPuml/Groups/AWSCloud.puml
!include AWSPuml/Groups/VPC.puml
!include AWSPuml/Groups/AvailabilityZone.puml
!include AWSPuml/Groups/PublicSubnet.puml
!include AWSPuml/Groups/PrivateSubnet.puml
!include AWSPuml/NetworkingContentDelivery/VPCNATGateway.puml
!include AWSPuml/NetworkingContentDelivery/VPCInternetGateway.puml

hide stereotype
skinparam linetype ortho

AWSCloudGroup(cloud) {
  VPCGroup(vpc) {
    VPCInternetGateway(internet_gateway, "Internet gateway", "")

    AvailabilityZoneGroup(az_1, "\tAvailability Zone 1\t") {
      PublicSubnetGroup(az_1_public, "Public subnet") {
        VPCNATGateway(az_1_nat_gateway, "NAT gateway", "") #Transparent
      }
      PrivateSubnetGroup(az_1_private, "Private subnet") {
        EC2Instance(az_1_ec2_1, "Instance", "") #Transparent
      }

      az_1_ec2_1 .u.> az_1_nat_gateway
    }

    AvailabilityZoneGroup(az_2, "\tAvailability Zone 2\t") {
      PublicSubnetGroup(az_2_public, "Public subnet") {
        VPCNATGateway(az_2_nat_gateway, "NAT gateway", "") #Transparent
      }
      PrivateSubnetGroup(az_2_private, "Private subnet") {
        EC2Instance(az_2_ec2_1, "Instance", "") #Transparent
      }

      az_2_ec2_1 .u.> az_2_nat_gateway
    }

    az_2_nat_gateway .[hidden]u.> internet_gateway
    az_1_nat_gateway .[hidden]u.> internet_gateway
  }
}
@enduml
```

--------------------------------

### Raw Image Usage in PlantUML Diagrams

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

Shows how to include individual AWS icon images directly within PlantUML diagrams for components, databases, and compute services. Enable dark mode by uncommenting '!$AWS_DARK = true'.

```plantuml
@startuml Raw usage - Images
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/ArtificialIntelligence/SageMakerAIModel.puml
!include AWSPuml/Compute/Compute.puml
!include AWSPuml/General/Documents.puml

component "$SageMakerAIModelIMG()" as myMLModel
database "$DocumentsIMG()" as myDocuments
Compute(mySecondFunction, "Agent Runtime", "Python")

rectangle "$SageMakerAIModelIMG()" as mySecondML

myMLModel --> myDocuments
mySecondFunction --> mySecondML

@enduml
```

--------------------------------

### Generate Simplified View PlantUML Diagram

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/README.md

This PlantUML script generates a simplified view of an application architecture by uncommenting the `AWSSimplified.puml` include. This view focuses on high-level interactions, omitting technical details for executive-level discussions.

```plantuml
@startuml Two Modes - Technical View
' Uncomment the line below for "dark mode" styling
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml

' Uncomment the following line to create simplified view
!include AWSPuml/AWSSimplified.puml

!include AWSPuml/General/Users.puml
!include AWSPuml/NetworkingContentDelivery/APIGateway.puml
!include AWSPuml/SecurityIdentityCompliance/Cognito.puml
!include AWSPuml/Compute/Lambda.puml
!include AWSPuml/Database/DynamoDB.puml

left to right direction

Users(sources, "Events", "millions of users")
APIGateway(votingAPI, "Voting API", "user votes")
Cognito(userAuth, "User Authentication", "jwt to submit votes")
Lambda(generateToken, "User Credentials", "return jwt")
Lambda(recordVote, "Record Vote", "enter or update vote per user")
DynamoDB(voteDb, "Vote Database", "one entry per user")

sources --> userAuth
sources --> votingAPI
userAuth <--> generateToken
votingAPI --> recordVote
recordVote --> voteDb
@enduml
```

--------------------------------

### Generate Symbols Only

Source: https://github.com/awslabs/aws-icons-for-plantuml/blob/main/scripts/README.md

Use this parameter to regenerate only the AWSSymbols.md, Structurizr theme, and Mermaid icons files after icons have been created.

```bash
$ uv run icon-builder.py --symbols-only
```