<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->

Architecture Diagram

Back to Style Guide — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: architecture-beta Best for: Cloud infrastructure, service topology, deployment architecture, network layout When NOT to use: Logical system boundaries (use C4), component layout without cloud semantics (use Block)

Accessibility: Mermaid 12.0.0 emits accTitle/accDescr for this type. Keep a visible description and verify older destination renderers.

Exemplar Diagram

Architecture diagram showing a cloud-hosted web application with a load balancer, API server, database, and cache deployed within a VPC:

architecture-beta
    accTitle: Architecture Example
    accDescr: Illustrative architecture diagram; the surrounding text describes its data and relationships.
    group cloud(cloud)[AWS Cloud]
    group vpc(cloud)[VPC] in cloud

    service lb(internet)[Load Balancer] in vpc
    service api(server)[API Server] in vpc
    service db(database)[PostgreSQL] in vpc
    service cache(disk)[Redis Cache] in vpc

    lb:R --> L:api
    api:R --> L:db
    api:B --> T:cache

Tips

• Use group for logical boundaries (VPC, region, cluster, availability zone)
• Use service for individual components
• Direction annotations on connections: :L (left), :R (right), :T (top), :B (bottom)
• Built-in icon types: cloud, server, database, internet, disk
• Nest groups with in parent_group
• Keep labels concise. Mermaid 12.0.0 accepts hyphens and Unicode inside []; older hosts may differ
• Use --> for directional arrows, -- for undirected edges
• Keep to 6–8 services per diagram
• Always pair with a Markdown text description above for screen readers

Template

Description of the infrastructure topology and key components:

architecture-beta
    accTitle: Architecture Example
    accDescr: Illustrative architecture diagram; the surrounding text describes its data and relationships.
    group region(cloud)[Cloud Region]

    service frontend(internet)[Web Frontend] in region
    service backend(server)[API Server] in region
    service datastore(database)[Database] in region

    frontend:R --> L:backend
    backend:R --> L:datastore

Complex Example

_Multi-region cloud deployment with 3 nested groups (2 regional clusters + shared services) showing 9 services, cross-region database replication, CDN distribution, and centralized monitoring. Demonstrates how nested group + in syntax creates clear infrastructure boundaries:_

architecture-beta
    accTitle: Architecture Example
    accDescr: Illustrative architecture diagram; the surrounding text describes its data and relationships.
    group cloud(cloud)[AWS Platform]

    group east(cloud)[US East Region] in cloud
    service lb_east(internet)[Load Balancer East] in east
    service app_east(server)[App Server East] in east
    service db_primary(database)[Primary Database] in east

    group west(cloud)[US West Region] in cloud
    service lb_west(internet)[Load Balancer West] in west
    service app_west(server)[App Server West] in west
    service db_replica(database)[Replica Database] in west

    group shared(cloud)[Shared Services] in cloud
    service cdn(internet)[CDN Edge] in shared
    service monitor(server)[Monitoring] in shared
    service queue(server)[Message Queue] in shared

    cdn:B --> T:lb_east
    cdn:B --> T:lb_west
    lb_east:R --> L:app_east
    lb_west:R --> L:app_west
    app_east:B --> T:db_primary
    app_west:B --> T:db_replica
    db_primary:R --> L:db_replica
    app_east:R --> L:queue
    app_west:R --> L:queue
    monitor:B --> T:app_east

Why this works

• Nested groups mirror real infrastructure — cloud > region > services is exactly how teams think about multi-region deployments. The nesting creates clear blast radius boundaries.
• Conservative labels keep this example readable across hosts; current Mermaid also accepts Unicode and hyphens in labels. Group nesting and built-in icons supply the primary visual distinctions.
• Directional annotations select ports — :B --> T: connects the source bottom to the target top, and :R --> L: connects source right to target left. Inspect routing and crossings; port selection does not guarantee a clean layout.
• Cross-region replication is explicit — the db_primary:R --> L:db_replica edge is the most important infrastructure detail and reads clearly as a horizontal connection between regions.

Verified reference

Syntax examples reviewed against official Mermaid documentation and rendered with Mermaid 12.0.0 (2026-10-01). Check the destination version; appearance and accessibility are not guaranteed by a successful parse.