Markdown Mermaid Writing

Markdown and Mermaid Writing

Overview

This skill teaches you — and enforces a standard for — creating scientific documentation using markdown with embedded Mermaid diagrams as the default and canonical format.

The core bet: a relationship expressed as a Mermaid diagram inside a .md file is more valuable than any image. It is text, so it diffs cleanly in git. It requires no build step. It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses fewer tokens than a prose description of the same relationship. And it can always be converted to a polished image later — but the text version remains the source of truth.

"The more you get your reports and files in .md in just regular text, which mermaid is

as well as being a simple 'script language'. This just helps with any downstream rendering

and especially AI generated images (using mermaid instead of just long form text to

describe relationships < tokens). Additionally mermaid can render along with markdown for

easy use almost anywhere by humans or AI."

>

— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

When to Use This Skill

Use this skill when:

• Creating any scientific document — reports, analyses, manuscripts, methods sections
• Writing any documentation — READMEs, how-tos, decision records, project docs
• Producing any diagram — workflows, data pipelines, architectures, timelines, relationships
• Generating any output that will be version-controlled — if it's going into git, it should be markdown
• Working with any other skill — this skill defines the documentation layer that wraps every other output
• Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always

Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams. Those are Phase 2 and Phase 3 — only used when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images).

🎨 The Source Format Philosophy

Why text-based diagrams win

The three-phase workflow

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Phase 1 Mermaid in markdown is always required and is the source of truth. Phases 2 and 3 are optional downstream conversions for polished output.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
    out["📊 Final Deliverable"]

    p1 --> out
    p1 -.->|"when needed"| p2
    p1 -.->|"when needed"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

Phase 1 is mandatory. Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.

What Mermaid can express

Mermaid covers 24 diagram types. Almost every scientific relationship fits one:

💡 Pick the right type, not the easy one. Don't default to flowcharts for everything.

A timeline beats a flowchart for chronological events. A sequence beats a flowchart for

service interactions. Scan the table and match.

---

🔧 Core workflow

Step 1: Identify the document type

Check if a template exists before writing from scratch:

Step 2: Read the style guide

Before writing any .md file: read references/markdown_style_guide.md.

Key rules to internalize:

• One H1 per document — the title. Never more.
• Emoji on H2 headings only — one emoji per H2, none in H3/H4
• Cite everything — every external claim gets a footnote [^N] with full URL
• Bold sparingly — max 2-3 bold terms per paragraph, never full sentences
• Horizontal rule after every `</details>` — mandatory
• Tables over prose for comparisons, configurations, structured data
• Diagrams over walls of text — if it describes flow, structure, or relationships, add Mermaid

Step 3: Pick the diagram type and read its guide

Before creating any Mermaid diagram: read references/mermaid_style_guide.md.

Then open the specific type file (e.g., references/diagrams/flowchart.md) for the exemplar, tips, and copy-paste template.

Mandatory rules for every diagram:

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows.

• No `%%{init}` directives — breaks GitHub dark mode
• No inline `style` — use classDef only
• One emoji per node max — at the start of the label
• `snake_case` node IDs — match the label

Step 4: Write the document

Start from the template. Apply the markdown style guide. Place diagrams inline with related text — not in a separate "Figures" section.

Step 5: Commit as text

The .md file with embedded Mermaid is what gets committed. If you also generated a PNG or AI image, those are supplementary — the markdown is the source.

---

⚠️ Common pitfalls

Radar chart syntax (radar-beta)

WRONG:

radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]

CORRECT:

radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3

• Use `radar-beta` not radar (the bare keyword doesn't exist)
• Use `axis` to define dimensions, not x-axis
• Use `curve` to define data series, not quoted labels with colon
• No `accTitle`/`accDescr` — radar-beta doesn't support accessibility annotations; always add a descriptive italic paragraph above the diagram

XY Chart vs Radar confusion

Forgetting accTitle/accDescr on supported types

Only some diagram types support accTitle/accDescr. For those that don't, always place a descriptive italic paragraph directly above the code block:

_Radar chart comparing three methods across five performance dimensions. Note: Radar charts do not support accTitle/accDescr._

radar-beta
...

---

🔗 Integration with other skills

With scientific-schematics

scientific-schematics generates AI-powered publication-quality images (PNG). Use the Mermaid diagram as the brief for the schematic:

Workflow:
1. Create the concept as Mermaid in .md (this skill — Phase 1)
2. Describe the same concept to scientific-schematics for a polished PNG (Phase 3)
3. Commit both — the .md as source, the PNG as a supplementary figure

With scientific-writing

When scientific-writing produces a manuscript, all diagrams and structural figures should use this skill's standards. The writing skill handles prose and citations; this skill handles visual structure.

Workflow:
1. Use scientific-writing to draft the manuscript
2. For every figure that shows a workflow, architecture, or relationship:
   - Replace placeholder with a Mermaid diagram following this skill's guide
3. Use scientific-schematics only for figures that truly need photorealistic/complex rendering

With literature-review

Literature review produces summaries with lots of relationship data. Use this skill to:

• Create concept maps (Mindmap) of the literature landscape
• Show publication timelines (Timeline or Gantt)
• Compare methodologies (Quadrant or Radar)
• Diagram data flows described in papers (Sequence or Flowchart)

With any skill that produces output documents

Before finalizing any document from any skill, apply this skill's checklist:

• [ ] Does the document use a template? If so, did I start from the right one?
• [ ] Are all diagrams in Mermaid with accTitle + accDescr?
• [ ] No %%{init}, no inline style, only classDef?
• [ ] Are all external claims cited with [^N]?
• [ ] One H1, emoji on H2 only?
• [ ] Horizontal rules after every </details>?

---

📚 Reference index

Style guides

Diagram type guides (24 types)

Each file contains: production-quality exemplar, tips specific to that type, and a copy-paste template.

references/diagrams/ — architecture, block, c4, class, complex\_examples, er, flowchart, gantt, git\_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user\_journey, xy\_chart, zenuml

Document templates (9 types)

templates/ — decision\_record, how\_to\_guide, issue, kanban, presentation, project\_documentation, pull\_request, research\_paper, status\_report

Examples

assets/examples/example-research-report.md — a complete scientific research report demonstrating proper heading hierarchy, multiple diagram types (flowchart, sequence, gantt), tables, footnote citations, collapsible sections, and all style guide rules applied.

---

📝 Attribution

All style guides, diagram type guides, and document templates in this skill are ported from the SuperiorByteWorks-LLC/agent-project repository under the Apache-2.0 License.

• Source: https://github.com/SuperiorByteWorks-LLC/agent-project
• Author: Clayton Young / Superior Byte Works, LLC (@borealBytes)
• License: Apache-2.0

This skill (as part of claude-scientific-skills) is distributed under the MIT License. The included Apache-2.0 content is compatible for downstream use with attribution retained, as preserved in the file headers throughout this skill.

---

[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/

CRISPR-Based Gene Editing Efficiency Analysis

_Example research report — demonstrates markdown-mermaid-writing skill standards. All diagrams use Mermaid embedded in markdown as the source format._

---

📋 Overview

This report analyzes the efficiency of CRISPR-Cas9 gene editing across three cell line models under variable guide RNA (gRNA) conditions. Editing efficiency was quantified by T7E1 assay and next-generation sequencing (NGS) of on-target loci[^1].

Key findings:

• HEK293T cells show highest editing efficiency (mean 78%) across all gRNA designs
• GC content between 40–65% correlates with editing efficiency (r = 0.82)
• Off-target events occur at <0.1% frequency across all conditions tested

---

🔄 Experimental workflow

CRISPR editing experiments followed a standardized five-stage protocol. Each stage has defined go/no-go criteria before proceeding.

flowchart TD
    accTitle: CRISPR Editing Experimental Workflow
    accDescr: Five-stage experimental pipeline from gRNA design through data analysis, with quality checkpoints between each stage.

    design["🧬 Stage 1<br/>gRNA Design<br/>(CRISPRscan + Cas-OFFinder)"]
    synth["⚙️ Stage 2<br/>Oligo Synthesis<br/>& Annealing"]
    transfect["🔬 Stage 3<br/>Cell Transfection<br/>(Lipofectamine 3000)"]
    screen["🧪 Stage 4<br/>Primary Screen<br/>(T7E1 assay)"]
    ngs["📊 Stage 5<br/>NGS Validation<br/>(150 bp PE reads)"]

    qc1{GC 40-65%?}
    qc2{Yield ≥ 2 µg?}
    qc3{Viability ≥ 85%?}
    qc4{Band visible?}

    design --> qc1
    qc1 -->|"✅ Pass"| synth
    qc1 -->|"❌ Redesign"| design
    synth --> qc2
    qc2 -->|"✅ Pass"| transfect
    qc2 -->|"❌ Re-synthesize"| synth
    transfect --> qc3
    qc3 -->|"✅ Pass"| screen
    qc3 -->|"❌ Optimize"| transfect
    screen --> qc4
    qc4 -->|"✅ Pass"| ngs
    qc4 -->|"❌ Repeat"| screen

    classDef stage fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef gate fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef fail fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d

    class design,synth,transfect,screen,ngs stage
    class qc1,qc2,qc3,qc4 gate

---

🔬 Methods

Cell lines and culture

Three cell lines were used: HEK293T (human embryonic kidney), K562 (chronic myelogenous leukemia), and Jurkat (T-lymphocyte). All lines were maintained in RPMI-1640 with 10% FBS at 37°C / 5% CO₂[^2].

gRNA design and efficiency prediction

gRNAs targeting the _EMX1_ locus were designed using CRISPRscan[^3] with the following criteria:

Transfection protocol

RNP complexes were assembled at 1:1.2 molar ratio (Cas9:gRNA) and delivered by lipofection. Cells were harvested 72 hours post-transfection for genomic DNA extraction.

Analysis pipeline

sequenceDiagram
    accTitle: NGS Data Analysis Pipeline
    accDescr: Sequence of computational steps from raw FASTQ files through variant calling to final efficiency report.

    participant raw as 📥 Raw FASTQ
    participant qc as 🔍 FastQC
    participant trim as ✂️ Trimmomatic
    participant align as 🗺️ BWA-MEM2
    participant call as ⚙️ CRISPResso2
    participant report as 📊 Report

    raw->>qc: Per-base quality scores
    qc-->>trim: Flag low-Q reads (Q<20)
    trim->>align: Cleaned reads
    align->>align: Index reference genome (hg38)
    align->>call: BAM + target region BED
    call->>call: Quantify indel frequency
    call-->>report: Editing efficiency (%)
    call-->>report: Off-target events
    report-->>report: Statistical summary

---

📊 Results

Editing efficiency by cell line

HEK293T cells showed significantly higher editing efficiency than both K562 (p < 0.001) and Jurkat (p < 0.001) lines by one-way ANOVA with Tukey post-hoc correction.

Effect of GC content on efficiency

GC content between 40–65% was strongly correlated with editing efficiency (Pearson r = 0.82, p < 0.0001, n = 48 gRNAs).

xychart-beta
    accTitle: Editing Efficiency vs gRNA GC Content
    accDescr: Bar chart showing mean editing efficiency grouped by GC content bins, demonstrating optimal performance in the 40 to 65 percent GC range

    title "Mean Editing Efficiency by GC Content Bin (HEK293T)"
    x-axis ["< 30%", "30–40%", "40–50%", "50–65%", "> 65%"]
    y-axis "Editing Efficiency (%)" 0 --> 100
    bar [18, 42, 76, 81, 38]

Timeline of key experimental milestones

timeline
    accTitle: Experiment Timeline — CRISPR Efficiency Study
    accDescr: Chronological milestones from study design through manuscript submission across six months

    section Month 1
        Study design and gRNA library design : 48 gRNAs across 3 target loci
        Cell line authentication : STR profiling confirmed all three lines
    section Month 2
        gRNA synthesis and QC : 46/48 gRNAs passed yield threshold
        Pilot transfections (HEK293T) : Optimized lipofection conditions
    section Month 3
        Full transfection series : All 3 cell lines, all 46 gRNAs, 6 replicates
        T7E1 primary screening : Passed go/no-go for all conditions
    section Month 4
        NGS library preparation : 276 samples processed
        Sequencing run (NovaSeq) : 150 bp PE, mean 50k reads/sample
    section Month 5
        Bioinformatic analysis : CRISPResso2 pipeline
        Statistical analysis : ANOVA, correlation, regression
    section Month 6
        Manuscript preparation : This report

---

🔍 Discussion

Why HEK293T outperforms suspension lines

HEK293T's superior editing efficiency relative to K562 and Jurkat likely reflects three factors[^4]:

1. Adherent morphology — enables more uniform lipofection contact 2. High transfection permissiveness — HEK293T expresses the SV40 large T antigen, which may facilitate nuclear import 3. Cell cycle distribution — higher proportion in S/G2 phase where HDR is favored

<details> <summary><strong>🔧 Technical details — off-target analysis</strong></summary>

Off-target editing was assessed by GUIDE-seq at the 5 highest-activity gRNAs. No off-target sites exceeding 0.1% editing frequency were detected. The three potential sites flagged by Cas-OFFinder (≤2 mismatches) showed 0.00%, 0.02%, and 0.04% indel frequencies — all below the assay noise floor of 0.05%.

Full GUIDE-seq data available in supplementary data package (GEO accession pending).

</details>

---

Comparison with published benchmarks

_Radar chart comparing three CRISPR delivery methods across five performance dimensions. Note: Radar charts do not support accTitle/accDescr — description provided above._

radar-beta
title Performance vs. Published Methods
axis eff["Efficiency"], spec["Specificity"], del["Delivery ease"], cost["Cost"], viab["Cell viability"]
curve this_study["This study (RNP + Lipo)"]{78, 95, 80, 85, 90}
curve plasmid["Plasmid Cas9 (lit.)"]{55, 70, 90, 95, 75}
curve electroporation["Electroporation RNP (lit.)"]{88, 96, 50, 60, 65}
max 100
graticule polygon
ticks 5
showLegend true

---

🎯 Conclusions

1. RNP-lipofection in HEK293T achieves >75% CRISPR editing efficiency — competitive with electroporation without the associated viability cost 2. gRNA GC content is the single strongest predictor of editing efficiency in our dataset (r = 0.82) 3. This protocol is not directly transferable to suspension lines without further optimization; K562 and Jurkat require electroporation or viral delivery for comparable efficiency

---

🔗 References

[^1]: Ran, F.A. et al. (2013). "Genome engineering using the CRISPR-Cas9 system." _Nature Protocols_, 8(11), 2281–2308. https://doi.org/10.1038/nprot.2013.143

[^2]: ATCC. (2024). "Cell Line Authentication and Quality Control." https://www.atcc.org/resources/technical-documents/cell-line-authentication

[^3]: Moreno-Mateos, M.A. et al. (2015). "CRISPRscan: designing highly efficient sgRNAs for CRISPR-Cas9 targeting in vivo." _Nature Methods_, 12(10), 982–988. https://doi.org/10.1038/nmeth.3543

[^4]: Molla, K.A. & Yang, Y. (2019). "CRISPR/Cas-Mediated Base Editing: Technical Considerations and Practical Applications." _Trends in Biotechnology_, 37(10), 1121–1142. https://doi.org/10.1016/j.tibtech.2019.03.008

<!-- 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](../mermaid_style_guide.md) — 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: Architecture diagrams do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

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
    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
• Labels must be plain text — no emoji and no hyphens in [] labels (parser treats - as an edge operator)
• 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
    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
    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.
• Plain text labels only — architecture diagrams parse-fail with emoji in [] labels. All visual distinction comes from the group nesting and icon types (internet, server, database).
• Directional annotations prevent overlap — :B --> T: (bottom-to-top), :R --> L: (right-to-left) control where edges connect. Without these, Mermaid stacks edges on top of each other.
• 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.

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

Block Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: block-beta Best for: System block composition, layered architectures, component topology where spatial layout matters When NOT to use: Process flows (use Flowchart), infrastructure with cloud icons (use Architecture)

⚠️ Accessibility: Block diagrams do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Block diagram showing a three-tier web application architecture from client-facing interfaces through application services to data storage, with emoji labels indicating component types:_

block-beta
    columns 3

    block:client:3
        columns 3
        browser["🌐 Browser"]
        mobile["📱 Mobile App"]
        cli["⌨️ CLI Tool"]
    end

    space:3

    block:app:3
        columns 3
        api["🖥️ API Server"]
        worker["⚙️ Worker"]
        cache["⚡ Redis Cache"]
    end

    space:3

    block:data:3
        columns 2
        db[("💾 PostgreSQL")]
        storage["📦 Object Storage"]
    end

    browser --> api
    mobile --> api
    cli --> api
    api --> worker
    api --> cache
    worker --> db
    api --> db
    worker --> storage

---

Tips

• Use columns N to control the layout grid
• Use space:N for empty cells (alignment/spacing)
• Nest block:name:span { ... } for grouped sections
• Connect blocks with --> arrows
• Use emoji in labels ["🔧 Component"] for visual distinction
• Use cylinder ("text") syntax for databases within blocks
• Keep to 3–4 rows with 3–4 columns for readability
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the system layers and how components connect:_

block-beta
    columns 3

    block:layer1:3
        columns 3
        comp_a["📋 Component A"]
        comp_b["⚙️ Component B"]
        comp_c["📦 Component C"]
    end

    space:3

    block:layer2:3
        columns 2
        comp_d["💾 Component D"]
        comp_e["🔧 Component E"]
    end

    comp_a --> comp_d
    comp_b --> comp_d
    comp_c --> comp_e

---

Complex Example

_Enterprise platform architecture rendered as a 5-tier block diagram with 15 components. Each tier is a block group spanning the full width, with internal columns controlling component layout. Connections show the primary data flow paths between tiers:_

block-beta
    columns 4

    block:clients:4
        columns 4
        browser["🌐 Browser"]
        mobile["📱 Mobile App"]
        partner["🔌 Partner API"]
        admin["🔐 Admin Console"]
    end

    space:4

    block:gateway:4
        columns 2
        apigw["🌐 API **Gateway**"]
        auth["🔐 Auth Service"]
    end

    space:4

    block:services:4
        columns 4
        user_svc["👤 User Service"]
        order_svc["📋 Order Service"]
        product_svc["📦 Product Service"]
        notify_svc["📤 Notification Service"]
    end

    space:4

    block:data:4
        columns 3
        postgres[("💾 PostgreSQL")]
        redis["⚡ Redis Cache"]
        elastic["🔍 Elasticsearch"]
    end

    space:4

    block:infra:4
        columns 3
        mq["📥 Message Queue"]
        logs["📊 Log Aggregator"]
        metrics["📊 Metrics Store"]
    end

    browser --> apigw
    mobile --> apigw
    partner --> apigw
    admin --> auth
    apigw --> auth
    apigw --> user_svc
    apigw --> order_svc
    apigw --> product_svc
    order_svc --> notify_svc
    user_svc --> postgres
    order_svc --> postgres
    product_svc --> elastic
    order_svc --> redis
    notify_svc --> mq
    order_svc --> mq
    mq --> logs

Why this works

• 5 tiers read top-to-bottom like a network diagram — clients, gateway, services, data, infrastructure. Each tier is a block spanning the full width with its own column layout.
• `space:4` creates visual separation between tiers without unnecessary lines or borders, keeping the diagram clean and scannable.
• Cylinder syntax `("text")` for databases — PostgreSQL renders as a cylinder, instantly recognizable as a data store. Other components use standard rectangles.
• Connections show real data paths — not every possible connection, just the primary flows. A fully-connected diagram would be unreadable; this shows the key paths an engineer would trace during debugging.

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

C4 Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: C4Context, C4Container, C4Component Best for: System architecture at varying zoom levels — context, containers, components When NOT to use: Infrastructure topology (use Architecture), runtime sequences (use Sequence)

---

Exemplar Diagram — System Context

C4Context
    accTitle: Online Store System Context
    accDescr: C4 context diagram showing how a customer interacts with the store and its external payment dependency

    title Online Store - System Context

    Person(customer, "Customer", "Places orders")
    System(store, "Online Store", "Catalog and checkout")
    System_Ext(payment, "Payment Provider", "Card processing")

    Rel(customer, store, "Orders", "HTTPS")
    Rel(store, payment, "Pays", "API")

    UpdateRelStyle(customer, store, $offsetY="-40", $offsetX="-30")
    UpdateRelStyle(store, payment, $offsetY="-40", $offsetX="-30")

---

C4 Zoom Levels

Tips

• Use Person() for human actors
• Use System() for internal systems, System_Ext() for external
• Use Container(), ContainerDb(), ContainerQueue() at the container level
• Label relationships with verbs and protocols: "Reads from", "SQL/TLS"
• Use Container_Boundary(id, "name") { ... } to group containers
• Keep descriptions short — long text causes label overlaps
• Limit to 4–5 elements at the Context level to avoid crowding
• Avoid emoji in C4 labels — the C4 renderer handles its own styling
• Use UpdateRelStyle() to adjust label positions if overlaps occur

---

Template

C4Context
    accTitle: Your System Context
    accDescr: Describe the system boundaries and external interactions

    Person(user, "User", "Role description")

    System(main_system, "Your System", "What it does")
    System_Ext(external, "External Service", "What it provides")

    Rel(user, main_system, "Uses", "HTTPS")
    Rel(main_system, external, "Calls", "API")

---

Complex Example

A C4 Container diagram for an e-commerce platform with 3 Container_Boundary groups, 10 containers, and 2 external systems. Shows how to use boundaries to organize services by layer, with UpdateRelStyle offsets preventing label overlaps.

C4Container
    accTitle: E-Commerce Platform Container View
    accDescr: C4 container diagram showing web and mobile frontends, core backend services, and data stores with external payment and email dependencies

    Person(customer, "Customer", "Shops online")

    Container_Boundary(frontend, "Frontend") {
        Container(spa, "Web App", "React", "Single-page app")
        Container(bff, "BFF API", "Node.js", "Backend for frontend")
    }

    Container_Boundary(services, "Core Services") {
        Container(order_svc, "Order Service", "Go", "Order processing")
        Container(catalog_svc, "Product Catalog", "Go", "Product data")
        Container(user_svc, "User Service", "Go", "Auth and profiles")
    }

    Container_Boundary(data, "Data Layer") {
        ContainerDb(pg, "PostgreSQL", "SQL", "Primary data store")
        ContainerDb(redis, "Redis", "Cache", "Session and cache")
        ContainerDb(search, "Elasticsearch", "Search", "Product search")
    }

    System_Ext(payment_gw, "Payment Gateway", "Card processing")
    System_Ext(email_svc, "Email Service", "Transactional email")

    Rel(customer, spa, "Browses", "HTTPS")
    Rel(spa, bff, "Calls", "GraphQL")
    Rel(bff, order_svc, "Places orders", "gRPC")
    Rel(bff, catalog_svc, "Queries", "gRPC")
    Rel(bff, user_svc, "Authenticates", "gRPC")
    Rel(order_svc, pg, "Reads/writes", "SQL")
    Rel(order_svc, payment_gw, "Charges", "API")
    Rel(order_svc, email_svc, "Sends", "SMTP")
    Rel(catalog_svc, search, "Indexes", "REST")
    Rel(user_svc, redis, "Sessions", "TCP")
    Rel(catalog_svc, pg, "Reads", "SQL")

    UpdateRelStyle(customer, spa, $offsetY="-40", $offsetX="-50")
    UpdateRelStyle(spa, bff, $offsetY="-30", $offsetX="10")
    UpdateRelStyle(bff, order_svc, $offsetY="-30", $offsetX="-40")
    UpdateRelStyle(bff, catalog_svc, $offsetY="-30", $offsetX="10")
    UpdateRelStyle(bff, user_svc, $offsetY="-30", $offsetX="50")
    UpdateRelStyle(order_svc, pg, $offsetY="-30", $offsetX="-50")
    UpdateRelStyle(order_svc, payment_gw, $offsetY="-30", $offsetX="10")
    UpdateRelStyle(order_svc, email_svc, $offsetY="10", $offsetX="10")
    UpdateRelStyle(catalog_svc, search, $offsetY="-30", $offsetX="10")
    UpdateRelStyle(user_svc, redis, $offsetY="-30", $offsetX="10")
    UpdateRelStyle(catalog_svc, pg, $offsetY="10", $offsetX="30")

Why this works

• Container_Boundary groups map to deployment units — frontend, core services, and data layer each correspond to real infrastructure boundaries (CDN, Kubernetes namespace, managed databases)
• Every `Rel` has `UpdateRelStyle` — C4's auto-layout stacks labels on top of each other by default. Offset every relationship to prevent overlaps, even if it seems fine at first (adding elements later will shift things)
• Descriptions are kept to 1-3 words — "Card processing", "Session and cache", "Auth and profiles". Long descriptions are the #1 cause of C4 rendering issues
• Container types are semantic — ContainerDb for databases gives them the cylinder icon, Container for services. The C4 renderer provides its own visual differentiation

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

Class Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: classDiagram Best for: Object-oriented design, type hierarchies, interface contracts, domain models When NOT to use: Database schemas (use ER), runtime behavior (use Sequence)

---

Exemplar Diagram

classDiagram
    accTitle: Payment Processing Class Hierarchy
    accDescr: Interface and abstract base class with two concrete implementations for credit card and digital wallet payment processing

    class PaymentProcessor {
        <<interface>>
        +processPayment(amount) bool
        +refund(transactionId) bool
        +getStatus(transactionId) string
    }

    class BaseProcessor {
        <<abstract>>
        #apiKey: string
        #timeout: int
        +validateAmount(amount) bool
        #logTransaction(tx) void
    }

    class CreditCardProcessor {
        -gateway: string
        +processPayment(amount) bool
        +refund(transactionId) bool
        -tokenizeCard(card) string
    }

    class DigitalWalletProcessor {
        -provider: string
        +processPayment(amount) bool
        +refund(transactionId) bool
        -initiateHandshake() void
    }

    PaymentProcessor <|.. BaseProcessor : implements
    BaseProcessor <|-- CreditCardProcessor : extends
    BaseProcessor <|-- DigitalWalletProcessor : extends

    style PaymentProcessor fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    style BaseProcessor fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    style CreditCardProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    style DigitalWalletProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

---

Tips

• Use <<interface>> and <<abstract>> stereotypes for clarity
• Show visibility: + public, - private, # protected
• Keep to 4–6 classes per diagram — split larger hierarchies
• Use style ClassName fill:...,stroke:...,color:... for light semantic coloring:
• 🟣 Purple for interfaces/abstractions
• 🔵 Blue for base/abstract classes
• 🟢 Green for concrete implementations
• Relationship arrows:
• <|-- inheritance (extends)
• <|.. implementation (implements)
• *-- composition · o-- aggregation · --> dependency

---

Template

classDiagram
    accTitle: Your Title Here
    accDescr: Describe the class hierarchy and the key relationships between types

    class InterfaceName {
        <<interface>>
        +methodOne() ReturnType
        +methodTwo(param) ReturnType
    }

    class ConcreteClass {
        -privateField: Type
        +methodOne() ReturnType
        +methodTwo(param) ReturnType
    }

    InterfaceName <|.. ConcreteClass : implements

---

Complex Example

An event-driven notification platform with 11 classes organized into 3 namespace groups — core orchestration, delivery channels, and data models. Shows interface implementation, composition, and dependency relationships across layers.

classDiagram
    accTitle: Event-Driven Notification Platform
    accDescr: Multi-namespace class hierarchy for a notification system showing core orchestration, four delivery channel implementations, and supporting data models with composition and dependency relationships

    namespace Core {
        class NotificationService {
            -queue: NotificationQueue
            -registry: ChannelRegistry
            +dispatch(notification) bool
            +scheduleDelivery(notification, time) void
            +getDeliveryStatus(id) DeliveryStatus
        }

        class NotificationQueue {
            -pending: List~Notification~
            -maxRetries: int
            +enqueue(notification) void
            +dequeue() Notification
            +retry(attempt) bool
        }

        class ChannelRegistry {
            -channels: Map~string, Channel~
            +register(name, channel) void
            +resolve(type) Channel
            +healthCheck() Map~string, bool~
        }
    }

    namespace Channels {
        class Channel {
            <<interface>>
            +send(notification, recipient) DeliveryAttempt
            +getStatus(attemptId) DeliveryStatus
            +validateRecipient(recipient) bool
        }

        class EmailChannel {
            -smtpHost: string
            -templateEngine: TemplateEngine
            +send(notification, recipient) DeliveryAttempt
            +getStatus(attemptId) DeliveryStatus
            +validateRecipient(recipient) bool
        }

        class SMSChannel {
            -provider: string
            -rateLimit: int
            +send(notification, recipient) DeliveryAttempt
            +getStatus(attemptId) DeliveryStatus
            +validateRecipient(recipient) bool
        }

        class PushChannel {
            -firebaseKey: string
            -apnsKey: string
            +send(notification, recipient) DeliveryAttempt
            +getStatus(attemptId) DeliveryStatus
            +validateRecipient(recipient) bool
        }

        class WebhookChannel {
            -signingSecret: string
            -timeout: int
            +send(notification, recipient) DeliveryAttempt
            +getStatus(attemptId) DeliveryStatus
            +validateRecipient(recipient) bool
        }
    }

    namespace Models {
        class Notification {
            +id: uuid
            +channel: string
            +subject: string
            +body: string
            +priority: string
            +createdAt: timestamp
        }

        class Recipient {
            +id: uuid
            +email: string
            +phone: string
            +deviceTokens: List~string~
            +preferences: Map~string, bool~
        }

        class DeliveryAttempt {
            +id: uuid
            +notificationId: uuid
            +recipientId: uuid
            +status: DeliveryStatus
            +attemptNumber: int
            +sentAt: timestamp
        }

        class DeliveryStatus {
            <<enumeration>>
            QUEUED
            SENDING
            DELIVERED
            FAILED
            BOUNCED
        }
    }

    NotificationService *-- NotificationQueue : contains
    NotificationService *-- ChannelRegistry : contains
    ChannelRegistry --> Channel : resolves

    Channel <|.. EmailChannel : implements
    Channel <|.. SMSChannel : implements
    Channel <|.. PushChannel : implements
    Channel <|.. WebhookChannel : implements

    Channel ..> Notification : receives
    Channel ..> Recipient : delivers to
    Channel ..> DeliveryAttempt : produces

    DeliveryAttempt --> DeliveryStatus : has

    style Channel fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    style DeliveryStatus fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    style NotificationService fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    style NotificationQueue fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    style ChannelRegistry fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    style EmailChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    style SMSChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    style PushChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    style WebhookChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    style Notification fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
    style Recipient fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
    style DeliveryAttempt fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

Why this works

• 3 namespaces mirror architectural layers — Core (orchestration), Channels (delivery implementations), Models (data). A developer can scan one namespace without reading the others.
• Color encodes the role — purple for interfaces/enums, blue for core services, green for concrete implementations, gray for data models. The pattern is instantly recognizable.
• Relationship types are deliberate — composition (*--) for "owns and manages", implementation (<|..) for "fulfills contract", dependency (..>) for "uses at runtime". Each arrow type carries meaning.

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

Composing Complex Diagram Sets

Back to [Style Guide](../mermaid_style_guide.md) — This file covers how to combine multiple diagram types to document complex systems comprehensively.

Purpose: A single diagram captures a single perspective. Real documentation often needs multiple diagram types working together — an overview flowchart linked to a detailed sequence diagram, an ER schema paired with a state machine showing entity lifecycle, a Gantt timeline complemented by architecture before/after views. This file teaches you when and how to compose diagrams for maximum clarity.

---

When to Compose Multiple Diagrams

---

Pattern 1: Overview + Detail

When to use: You need both the big picture AND the specifics. Leadership sees the overview; engineers drill into the detail.

The overview diagram shows high-level phases or components. One or more detail diagrams zoom into specific phases showing the internal interactions.

Overview — Release Pipeline

flowchart LR
    accTitle: Release Pipeline Overview
    accDescr: High-level four-phase release pipeline from code commit through build, staging, and production deployment

    subgraph source ["📥 Source"]
        commit[📝 Code commit] --> pr_review[🔍 PR review]
    end

    subgraph build ["🔧 Build"]
        compile[⚙️ Compile] --> test[🧪 Test suite]
        test --> scan[🔐 Security scan]
    end

    subgraph staging ["🚀 Staging"]
        deploy_stg[☁️ Deploy staging] --> smoke[🧪 Smoke tests]
        smoke --> approval{👤 Approved?}
    end

    subgraph production ["✅ Production"]
        canary[🚀 Canary **5%**] --> rollout[🚀 Full **rollout**]
        rollout --> monitor[📊 Monitor metrics]
    end

    source --> build
    build --> staging
    approval -->|Yes| production
    approval -->|No| source

    classDef phase_start fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef phase_test fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef phase_deploy fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class commit,pr_review,compile phase_start
    class test,scan,smoke,approval phase_test
    class deploy_stg,canary,rollout,monitor phase_deploy

_The production deployment phase involves multiple service interactions. See the detail sequence below for the canary rollout process._

Detail — Canary Deployment Sequence

sequenceDiagram
    accTitle: Canary Deployment Service Interactions
    accDescr: Detailed sequence showing how the CI server orchestrates a canary deployment through the container registry, Kubernetes cluster, and monitoring stack with automated rollback on failure

    participant ci as ⚙️ CI Server
    participant registry as 📦 Container Registry
    participant k8s as ☁️ Kubernetes
    participant monitor as 📊 Monitoring
    participant oncall as 👤 On-Call Engineer

    ci->>registry: 📤 Push tagged image
    registry-->>ci: ✅ Image stored

    ci->>k8s: 🚀 Deploy canary (5% traffic)
    k8s-->>ci: ✅ Canary pods running

    ci->>monitor: 📊 Start canary analysis
    Note over monitor: ⏰ Observe for 15 minutes

    loop 📊 Every 60 seconds
        monitor->>k8s: 🔍 Query error rate
        k8s-->>monitor: 📊 Metrics response
    end

    alt ✅ Error rate below threshold
        monitor-->>ci: ✅ Canary healthy
        ci->>k8s: 🚀 Promote to 100%
        k8s-->>ci: ✅ Full rollout complete
        ci->>monitor: 📊 Continue monitoring
    else ❌ Error rate above threshold
        monitor-->>ci: ❌ Canary failing
        ci->>k8s: 🔄 Rollback to previous
        k8s-->>ci: ✅ Rollback complete
        ci->>oncall: ⚠️ Alert: canary failed
        Note over oncall: 📋 Investigate root cause
    end

How these connect

• The overview flowchart shows the full pipeline with subgraph-to-subgraph connections — leadership reads this to understand the release process
• The detail sequence zooms into "Canary 5% → Full rollout" from the Production subgraph, showing the actual service interactions an engineer would debug
• Naming is consistent — "Canary" and "Monitor metrics" appear in both diagrams, creating a clear bridge between overview and detail

---

Pattern 2: Multi-Perspective Documentation

When to use: The same system needs to be documented for different audiences — database teams, backend engineers, and product managers each need a different view of the same feature.

This example documents a User Authentication feature from three perspectives.

Data Model — for database team

erDiagram
    accTitle: Authentication Data Model
    accDescr: Five-entity schema for user authentication covering users, sessions, refresh tokens, login attempts, and MFA devices with cardinality relationships

    USER ||--o{ SESSION : "has"
    USER ||--o{ REFRESH_TOKEN : "owns"
    USER ||--o{ LOGIN_ATTEMPT : "produces"
    USER ||--o{ MFA_DEVICE : "registers"
    SESSION ||--|| REFRESH_TOKEN : "paired with"

    USER {
        uuid id PK "🔑 Primary key"
        string email "📧 Unique login"
        string password_hash "🔐 Bcrypt hash"
        boolean mfa_enabled "🔒 MFA flag"
        timestamp last_login "⏰ Last active"
    }

    SESSION {
        uuid id PK "🔑 Primary key"
        uuid user_id FK "👤 Session owner"
        string ip_address "🌐 Client IP"
        string user_agent "📋 Browser info"
        timestamp expires_at "⏰ Expiration"
    }

    REFRESH_TOKEN {
        uuid id PK "🔑 Primary key"
        uuid user_id FK "👤 Token owner"
        uuid session_id FK "🔗 Paired session"
        string token_hash "🔐 Hashed token"
        boolean revoked "❌ Revoked flag"
        timestamp expires_at "⏰ Expiration"
    }

    LOGIN_ATTEMPT {
        uuid id PK "🔑 Primary key"
        uuid user_id FK "👤 Attempting user"
        string ip_address "🌐 Source IP"
        boolean success "✅ Outcome"
        string failure_reason "⚠️ Why failed"
        timestamp attempted_at "⏰ Attempt time"
    }

    MFA_DEVICE {
        uuid id PK "🔑 Primary key"
        uuid user_id FK "👤 Device owner"
        string device_type "📱 TOTP or WebAuthn"
        string secret_hash "🔐 Encrypted secret"
        boolean verified "✅ Setup complete"
        timestamp registered_at "⏰ Registered"
    }

Authentication Flow — for backend team

sequenceDiagram
    accTitle: Login Flow with MFA
    accDescr: Step-by-step authentication sequence showing credential validation, conditional MFA challenge, token issuance, and failure handling between browser, API, auth service, and database

    participant B as 👤 Browser
    participant API as 🌐 API Gateway
    participant Auth as 🔐 Auth Service
    participant DB as 💾 Database

    B->>API: 📤 POST /login (email, password)
    API->>Auth: 🔐 Validate credentials
    Auth->>DB: 🔍 Fetch user by email
    DB-->>Auth: 👤 User record

    Auth->>Auth: 🔐 Verify password hash

    alt ❌ Invalid password
        Auth->>DB: 📝 Log failed attempt
        Auth-->>API: ❌ 401 Unauthorized
        API-->>B: ❌ Invalid credentials
    else ✅ Password valid
        alt 🔒 MFA enabled
            Auth-->>API: ⚠️ 202 MFA required
            API-->>B: 📱 Show MFA prompt

            B->>API: 📤 POST /login/mfa (code)
            API->>Auth: 🔐 Verify MFA code
            Auth->>DB: 🔍 Fetch MFA device
            DB-->>Auth: 📱 Device record
            Auth->>Auth: 🔐 Validate TOTP

            alt ❌ Invalid code
                Auth-->>API: ❌ 401 Invalid code
                API-->>B: ❌ Try again
            else ✅ Code valid
                Auth->>DB: 📝 Create session + tokens
                Auth-->>API: ✅ 200 + tokens
                API-->>B: ✅ Set cookies + redirect
            end
        else 🔓 No MFA
            Auth->>DB: 📝 Create session + tokens
            Auth-->>API: ✅ 200 + tokens
            API-->>B: ✅ Set cookies + redirect
        end
    end

Login Experience — for product team

journey
    accTitle: Login Experience Journey Map
    accDescr: User satisfaction scores across the sign-in experience for password-only users and MFA users showing friction points in the multi-factor flow

    title 👤 Login Experience
    section 🔐 Sign In
        Navigate to login          : 4 : User
        Enter email and password   : 3 : User
        Click sign in button       : 4 : User
    section 📱 MFA Challenge
        Receive MFA prompt         : 3 : MFA User
        Open authenticator app     : 2 : MFA User
        Enter 6-digit code         : 2 : MFA User
        Handle expired code        : 1 : MFA User
    section ✅ Post-Login
        Land on dashboard          : 5 : User
        See personalized content   : 5 : User
        Resume previous session    : 4 : User

How these connect

• Same entities, different views — "User", "Session", "MFA Device" appear in the ER diagram as tables, in the sequence as participants/operations, and in the journey as experience touchpoints
• Each audience gets actionable information — the DB team sees indexes and cardinality, the backend team sees API contracts and error codes, the product team sees satisfaction scores and friction points
• The journey reveals what the sequence hides — the sequence diagram shows MFA as a clean conditional branch, but the journey map shows it's actually the worst part of the UX (scores 1-2). This drives the product decision to invest in WebAuthn/passkeys

---

Pattern 3: Before/After Architecture

When to use: Migration documentation where stakeholders need to see the current state, the target state, and understand the transformation.

Current State — Monolith

flowchart TB
    accTitle: Current State Monolith Architecture
    accDescr: Single Rails monolith handling all traffic through one server connected to one database showing the scaling bottleneck

    client([👤 All traffic]) --> mono[🖥️ Rails **Monolith**]
    mono --> db[(💾 Single PostgreSQL)]
    mono --> jobs[⏰ Background **jobs**]
    jobs --> db

    classDef bottleneck fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

    class mono,db bottleneck
    class client,jobs neutral

⚠️ Problem: Single database is the bottleneck. Monolith can't scale horizontally. Deploy = full restart.

Target State — Microservices

flowchart TB
    accTitle: Target State Microservices Architecture
    accDescr: Decomposed microservices architecture with API gateway routing to independent services each with their own data store and a shared message queue for async communication

    client([👤 All traffic]) --> gw[🌐 API **Gateway**]

    subgraph services ["⚙️ Services"]
        user_svc[👤 User Service]
        order_svc[📋 Order Service]
        product_svc[📦 Product Service]
    end

    subgraph data ["💾 Data Stores"]
        user_db[(💾 Users DB)]
        order_db[(💾 Orders DB)]
        product_db[(💾 Products DB)]
    end

    gw --> user_svc
    gw --> order_svc
    gw --> product_svc

    user_svc --> user_db
    order_svc --> order_db
    product_svc --> product_db

    order_svc --> mq[📥 Message Queue]
    mq --> user_svc
    mq --> product_svc

    classDef gateway fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    classDef service fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef datastore fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef infra fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12

    class gw gateway
    class user_svc,order_svc,product_svc service
    class user_db,order_db,product_db datastore
    class mq infra

✅ Result: Each service scales independently. Database-per-service eliminates the shared bottleneck. Async messaging decouples service dependencies.

How these connect

• Same layout, different complexity — both diagrams use flowchart TB so the structural transformation is visually obvious. The monolith is 4 nodes; the target is 11 nodes with subgraphs.
• Color tells the story — the monolith uses red (danger) on the bottleneck components. The target uses blue/green/purple to show healthy, differentiated components.
• Prose bridges the diagrams — the ⚠️ problem callout and ✅ result callout explain _why_ the architecture changes, not just _what_ changed.

---

Linking Diagrams in Documentation

When composing diagrams in a real document, follow these practices:

---

Choosing Your Composition Strategy

flowchart TB
    accTitle: Diagram Composition Decision Tree
    accDescr: Decision flowchart for choosing between single diagram, overview plus detail, multi-perspective, or before-after composition strategies based on audience and documentation needs

    start([📋 What are you documenting?]) --> audience{👥 Multiple audiences?}

    audience -->|Yes| perspectives[📐 Multi-Perspective]
    audience -->|No| depth{📏 Need both summary and detail?}

    depth -->|Yes| overview[🔍 Overview + Detail]
    depth -->|No| change{🔄 Showing a change over time?}

    change -->|Yes| before_after[⚡ Before / After]
    change -->|No| single[📊 Single diagram is fine]

    classDef decision fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef result fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef start_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764

    class audience,depth,change decision
    class perspectives,overview,before_after,single result
    class start start_style

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

Entity Relationship (ER) Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: erDiagram Best for: Database schemas, data models, entity relationships, API data structures When NOT to use: Class hierarchies with methods (use Class), process flows (use Flowchart)

---

Exemplar Diagram

erDiagram
    accTitle: Project Management Data Model
    accDescr: Entity relationships for a project management system showing teams, projects, tasks, members, and comments with cardinality

    TEAM ||--o{ PROJECT : "owns"
    PROJECT ||--o{ TASK : "contains"
    TASK ||--o{ COMMENT : "has"
    TEAM ||--o{ MEMBER : "includes"
    MEMBER ||--o{ TASK : "assigned to"
    MEMBER ||--o{ COMMENT : "writes"

    TEAM {
        uuid id PK "🔑 Primary key"
        string name "👥 Team name"
        string department "🏢 Department"
    }

    PROJECT {
        uuid id PK "🔑 Primary key"
        uuid team_id FK "🔗 Team reference"
        string title "📋 Project title"
        string status "📊 Current status"
        date deadline "⏰ Due date"
    }

    TASK {
        uuid id PK "🔑 Primary key"
        uuid project_id FK "🔗 Project reference"
        uuid assignee_id FK "👤 Assigned member"
        string title "📝 Task title"
        string priority "⚠️ Priority level"
        string status "📊 Current status"
    }

    MEMBER {
        uuid id PK "🔑 Primary key"
        uuid team_id FK "🔗 Team reference"
        string name "👤 Full name"
        string email "📧 Email address"
        string role "🏷️ Job role"
    }

    COMMENT {
        uuid id PK "🔑 Primary key"
        uuid task_id FK "🔗 Task reference"
        uuid author_id FK "👤 Author reference"
        text body "📝 Comment text"
        timestamp created_at "⏰ Created time"
    }

---

Tips

• Include data types, PK/FK annotations, and comment strings with emoji for context
• Use clear verb-phrase relationship labels: "owns", "contains", "assigned to"
• Cardinality notation:
• ||--o{ one-to-many
• ||--|| one-to-one
• }o--o{ many-to-many
• o = zero or more, | = exactly one
• Limit to 5–7 entities per diagram — split large schemas by domain
• Entity names: UPPER_CASE (SQL convention)

---

Template

erDiagram
    accTitle: Your Title Here
    accDescr: Describe the data model and key relationships between entities

    ENTITY_A ||--o{ ENTITY_B : "has many"
    ENTITY_B ||--|| ENTITY_C : "belongs to"

    ENTITY_A {
        uuid id PK "🔑 Primary key"
        string name "📝 Display name"
    }

    ENTITY_B {
        uuid id PK "🔑 Primary key"
        uuid entity_a_id FK "🔗 Reference"
        string value "📊 Value field"
    }

---

Complex Example

A multi-tenant SaaS platform schema with 10 entities spanning three domains — identity & access, billing & subscriptions, and audit & security. Relationships show the full cardinality picture from tenant isolation through user permissions to invoice generation.

erDiagram
    accTitle: SaaS Multi-Tenant Platform Schema
    accDescr: Ten-entity data model for a multi-tenant SaaS platform covering identity management, role-based access, subscription billing, and audit logging with full cardinality relationships

    TENANT ||--o{ ORGANIZATION : "contains"
    ORGANIZATION ||--o{ USER : "employs"
    ORGANIZATION ||--|| SUBSCRIPTION : "holds"
    USER }o--o{ ROLE : "assigned"
    ROLE ||--o{ PERMISSION : "grants"
    SUBSCRIPTION ||--|| PLAN : "subscribes to"
    SUBSCRIPTION ||--o{ INVOICE : "generates"
    USER ||--o{ AUDIT_LOG : "produces"
    TENANT ||--o{ AUDIT_LOG : "scoped to"
    USER ||--o{ API_KEY : "owns"

    TENANT {
        uuid id PK "🔑 Primary key"
        string name "🏢 Tenant name"
        string subdomain "🌐 Unique subdomain"
        string tier "🏷️ Service tier"
        boolean active "✅ Active status"
        timestamp created_at "⏰ Created time"
    }

    ORGANIZATION {
        uuid id PK "🔑 Primary key"
        uuid tenant_id FK "🔗 Tenant reference"
        string name "👥 Org name"
        string billing_email "📧 Billing contact"
        int seat_count "📊 Licensed seats"
    }

    USER {
        uuid id PK "🔑 Primary key"
        uuid org_id FK "🔗 Organization reference"
        string email "📧 Login email"
        string display_name "👤 Display name"
        string status "📊 Account status"
        timestamp last_login "⏰ Last active"
    }

    ROLE {
        uuid id PK "🔑 Primary key"
        uuid tenant_id FK "🔗 Tenant scope"
        string name "🏷️ Role name"
        string description "📝 Role purpose"
        boolean system_role "🔒 Built-in flag"
    }

    PERMISSION {
        uuid id PK "🔑 Primary key"
        uuid role_id FK "🔗 Role reference"
        string resource "🎯 Target resource"
        string action "⚙️ Allowed action"
        string scope "🔒 Permission scope"
    }

    PLAN {
        uuid id PK "🔑 Primary key"
        string name "🏷️ Plan name"
        int price_cents "💰 Monthly price"
        int seat_limit "👥 Max seats"
        jsonb features "📋 Feature flags"
        boolean active "✅ Available flag"
    }

    SUBSCRIPTION {
        uuid id PK "🔑 Primary key"
        uuid org_id FK "🔗 Organization reference"
        uuid plan_id FK "🔗 Plan reference"
        string status "📊 Sub status"
        date current_period_start "📅 Period start"
        date current_period_end "📅 Period end"
    }

    INVOICE {
        uuid id PK "🔑 Primary key"
        uuid subscription_id FK "🔗 Subscription reference"
        int amount_cents "💰 Total amount"
        string currency "💱 Currency code"
        string status "📊 Payment status"
        timestamp issued_at "⏰ Issue date"
    }

    AUDIT_LOG {
        uuid id PK "🔑 Primary key"
        uuid tenant_id FK "🔗 Tenant scope"
        uuid user_id FK "👤 Acting user"
        string action "⚙️ Action performed"
        string resource_type "🎯 Target type"
        uuid resource_id "🔗 Target ID"
        jsonb metadata "📋 Event details"
        timestamp created_at "⏰ Event time"
    }

    API_KEY {
        uuid id PK "🔑 Primary key"
        uuid user_id FK "👤 Owner"
        string prefix "🏷️ Key prefix"
        string hash "🔐 Hashed secret"
        string name "📝 Key name"
        timestamp expires_at "⏰ Expiration"
        boolean revoked "❌ Revoked flag"
    }

Why this works

• 10 entities organized by domain — identity (Tenant, Organization, User, Role, Permission), billing (Plan, Subscription, Invoice), and security (Audit Log, API Key). The relationship lines naturally cluster related entities together.
• Full cardinality tells the business rules — ||--|| (one-to-one) for Organization-Subscription means one subscription per org. }o--o{ (many-to-many) for User-Role means flexible RBAC. Each relationship symbol encodes a constraint.
• Every field has type, annotation, and purpose — PK/FK for schema generation, emoji comments for human scanning. A developer can read this diagram and write the migration script directly.

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

Flowchart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: flowchart Best for: Sequential processes, workflows, decision logic, troubleshooting trees When NOT to use: Complex timing between actors (use Sequence), state machines (use State)

---

Exemplar Diagram

flowchart TB
    accTitle: Feature Development Lifecycle
    accDescr: End-to-end feature flow from idea through design, build, test, review, and release with a revision loop on failed reviews

    idea([💡 Feature idea]) --> spec[📋 Write spec]
    spec --> design[🎨 Design solution]
    design --> build[🔧 Implement]
    build --> test[🧪 Run tests]
    test --> review{🔍 Review passed?}
    review -->|Yes| release[🚀 Release to prod]
    review -->|No| revise[✏️ Revise code]
    revise --> test
    release --> monitor([📊 Monitor metrics])

    classDef start fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    classDef process fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef decision fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class idea,monitor start
    class spec,design,build,test,revise process
    class review decision
    class release success

---

Tips

• Use TB (top-to-bottom) for processes, LR (left-to-right) for pipelines
• Rounded rectangles ([text]) for start/end, diamonds {text} for decisions
• Max 10 nodes — split larger flows into "Phase 1" / "Phase 2" diagrams
• Max 3 decision points per diagram
• Edge labels should be 1–4 words: -->|Yes|, -->|All green|
• Use classDef for semantic coloring — decisions in amber, success in green, actions in blue

Subgraph Pattern

When you need grouped stages:

flowchart TB
    accTitle: CI/CD Pipeline Stages
    accDescr: Three-stage pipeline grouping code quality checks, testing, and deployment into distinct phases

    trigger([⚡ Push to main])

    subgraph quality ["🔍 Code Quality"]
        lint[📝 Lint code] --> format[⚙️ Check formatting]
    end

    subgraph testing ["🧪 Testing"]
        unit[🧪 Unit tests] --> integration[🔗 Integration tests]
    end

    subgraph deploy ["🚀 Deployment"]
        build[📦 Build artifacts] --> ship[☁️ Deploy to staging]
    end

    trigger --> quality
    quality --> testing
    testing --> deploy
    deploy --> done([✅ Pipeline complete])

    classDef trigger_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class trigger trigger_style
    class done success

---

Template

flowchart TB
    accTitle: Your Title Here (3-8 words)
    accDescr: One or two sentences explaining what this diagram shows and what insight the reader gains

    start([🏁 Starting point]) --> step1[⚙️ First action]
    step1 --> decision{🔍 Check condition?}
    decision -->|Yes| step2[✅ Positive path]
    decision -->|No| step3[🔧 Alternative path]
    step2 --> done([🏁 Complete])
    step3 --> done

---

Complex Example

A 20+ node e-commerce order pipeline organized into 5 subgraphs, each representing a processing phase. Subgraphs connect through internal nodes, decision points route orders to exception handling, and color classes distinguish phases at a glance.

flowchart TB
    accTitle: E-Commerce Order Processing Pipeline
    accDescr: Full order lifecycle from intake through fulfillment, shipping, and notification with exception handling paths for payment failures, stockouts, and delivery issues

    order_in([📥 New order]) --> validate_pay{💰 Payment valid?}

    subgraph intake ["📥 Order Intake"]
        validate_pay -->|Yes| check_fraud{🔐 Fraud check}
        validate_pay -->|No| pay_fail[❌ Payment **declined**]
        check_fraud -->|Clear| check_stock{📦 In stock?}
        check_fraud -->|Flagged| manual_review[🔍 Manual **review**]
        manual_review --> check_stock
    end

    subgraph fulfill ["📦 Fulfillment"]
        pick[📋 **Pick** items] --> pack[📦 Pack order]
        pack --> label[🏷️ Generate **shipping** label]
    end

    subgraph ship ["🚚 Shipping"]
        handoff[🚚 Carrier **handoff**] --> transit[📍 In transit]
        transit --> deliver{✅ Delivered?}
    end

    subgraph notify ["📤 Notifications"]
        confirm_email[📧 Order **confirmed**]
        ship_update[📧 Shipping **update**]
        deliver_email[📧 Delivery **confirmed**]
    end

    subgraph exception ["⚠️ Exception Handling"]
        pay_fail --> retry_pay[🔄 Retry payment]
        retry_pay --> validate_pay
        out_of_stock[📦 **Backorder** created]
        deliver_fail[🔄 **Reattempt** delivery]
    end

    check_stock -->|Yes| pick
    check_stock -->|No| out_of_stock
    label --> handoff
    deliver -->|Yes| deliver_email
    deliver -->|No| deliver_fail
    deliver_fail --> transit

    check_stock -->|Yes| confirm_email
    handoff --> ship_update
    deliver_email --> complete([✅ Order **complete**])

    classDef intake_style fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef fulfill_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    classDef ship_style fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warn_style fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef danger_style fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d

    class validate_pay,check_fraud,check_stock,manual_review intake_style
    class pick,pack,label fulfill_style
    class handoff,transit,deliver ship_style
    class confirm_email,ship_update,deliver_email warn_style
    class pay_fail,retry_pay,out_of_stock,deliver_fail danger_style

Why this works

• 5 subgraphs map to real business phases — intake, fulfillment, shipping, notification, and exceptions are how operations teams actually think about orders
• Exception handling is its own subgraph — not scattered across phases. Agents and readers can see all failure paths in one place
• Color classes reinforce structure — blue for intake, purple for fulfillment, green for shipping, amber for notifications, red for exceptions. Even without reading labels, the color pattern tells you which phase you're looking at
• Decisions route between subgraphs — the diamonds ({Payment valid?}, {In stock?}, {Delivered?}) are the points where flow branches, and each branch leads to a clearly-labeled destination

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

Gantt Chart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: gantt Best for: Project timelines, roadmaps, phase planning, milestone tracking, task dependencies When NOT to use: Simple chronological events (use Timeline), process logic (use Flowchart)

---

Exemplar Diagram

gantt
    accTitle: Q1 Product Launch Roadmap
    accDescr: Eight-week project timeline across discovery, design, build, and launch phases with milestones for design review and go/no-go decision

    title 🚀 Q1 Product Launch Roadmap
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section 📋 Discovery
        User research          :done, research, 2026-01-05, 7d
        Competitive analysis   :done, compete, 2026-01-05, 5d
        Requirements doc       :done, reqs, after compete, 3d

    section 🎨 Design
        Wireframes             :done, wire, after reqs, 5d
        Visual design          :active, visual, after wire, 7d
        🏁 Design review       :milestone, review, after visual, 0d

    section 🔧 Build
        Core features          :crit, core, after visual, 10d
        API integration        :api, after visual, 8d
        Testing                :test, after core, 5d

    section 🚀 Launch
        Staging deploy         :staging, after test, 3d
        🏁 Go / no-go          :milestone, decision, after staging, 0d
        Production release     :crit, release, after staging, 2d

---

Tips

• Use section with emoji prefix to group by phase or team
• Mark milestones with :milestone and 0d duration — prefix with 🏁
• Status tags: :done, :active, :crit (critical path, highlighted)
• Use after taskId for dependencies
• Keep total timeline under 3 months for readability
• Use axisFormat to control date display (%b %d = "Jan 05", %m/%d = "01/05")

---

Template

gantt
    accTitle: Your Title Here
    accDescr: Describe the timeline scope and key milestones

    title 📋 Your Roadmap Title
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section 📋 Phase 1
        Task one       :done, t1, 2026-01-01, 5d
        Task two       :active, t2, after t1, 3d

    section 🔧 Phase 2
        Task three     :crit, t3, after t2, 7d
        🏁 Milestone   :milestone, m1, after t3, 0d

---

Complex Example

A cross-team platform migration spanning 4 months with 6 sections, 24 tasks, and 3 milestones. Shows dependencies across teams (backend migration blocks frontend migration), critical path items, and the full lifecycle from planning through launch monitoring.

gantt
    accTitle: Multi-Team Platform Migration Roadmap
    accDescr: Four-month migration project across planning, backend, frontend, data, QA, and launch teams with cross-team dependencies, critical path items, and three milestone gates

    title 🚀 Platform Migration — Q1/Q2 2026
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section 📋 Planning
        Kickoff meeting               :done, plan1, 2026-01-05, 2d
        Architecture review            :done, plan2, after plan1, 5d
        Migration plan document        :done, plan3, after plan2, 5d
        Risk assessment                :done, plan4, after plan2, 3d
        🏁 Planning complete           :milestone, m_plan, after plan3, 0d

    section 🔧 Backend Team
        API redesign                   :crit, be1, after m_plan, 12d
        Data migration scripts         :be2, after m_plan, 10d
        New service deployment         :crit, be3, after be1, 8d
        Backward compatibility layer   :be4, after be1, 6d

    section 🎨 Frontend Team
        Component library update       :fe1, after m_plan, 10d
        Page migration                 :crit, fe2, after be3, 12d
        A/B testing setup              :fe3, after fe2, 5d
        Feature parity validation      :fe4, after fe2, 4d

    section 🗄️ Data Team
        Schema migration               :crit, de1, after be2, 8d
        ETL pipeline update            :de2, after de1, 7d
        Data validation suite          :de3, after de2, 5d
        Rollback scripts               :de4, after de1, 4d

    section 🧪 QA Team
        Test plan creation             :qa1, after m_plan, 7d
        Regression suite               :qa2, after be3, 10d
        Performance testing            :crit, qa3, after qa2, 7d
        UAT coordination               :qa4, after qa3, 5d
        🏁 QA sign-off                 :milestone, m_qa, after qa4, 0d

    section 🚀 Launch
        Staging deploy                 :crit, l1, after m_qa, 3d
        🏁 Go / no-go decision         :milestone, m_go, after l1, 0d
        Production cutover             :crit, l2, after m_go, 2d
        Post-launch monitoring         :l3, after l2, 10d
        Legacy system decommission     :l4, after l3, 5d

Why this works

• 6 sections map to real teams — each team sees their workstream at a glance. Cross-team dependencies (frontend waits for backend API, QA waits for backend deploy) are explicit via after taskId.
• `:crit` marks the critical path — the chain of tasks that determines the total project duration. If any critical task slips, the launch date moves. Mermaid highlights these in red.
• 3 milestones are decision gates — Planning Complete, QA Sign-off, and Go/No-Go. These are the points where stakeholders make decisions, not just status updates.
• 24 tasks across 4 months is readable because sections group by team. Without sections, this would be an unreadable wall of bars.

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

Git Graph

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: gitGraph Best for: Branching strategies, merge workflows, release processes, git-flow visualization When NOT to use: General processes (use Flowchart), project timelines (use Gantt)

---

Exemplar Diagram

gitGraph
    accTitle: Trunk-Based Development Workflow
    accDescr: Git history showing short-lived feature branches merging into main with release tags demonstrating trunk-based development

    commit id: "init"
    commit id: "setup CI"

    branch feature/auth
    checkout feature/auth
    commit id: "add login"
    commit id: "add tests"

    checkout main
    merge feature/auth id: "merge auth" tag: "v1.0"

    commit id: "update deps"

    branch feature/dashboard
    checkout feature/dashboard
    commit id: "add charts"
    commit id: "add filters"

    checkout main
    merge feature/dashboard id: "merge dash"

    commit id: "perf fixes" tag: "v1.1"

---

Tips

• Use descriptive id: labels on commits
• Add tag: for release versions
• Branch names should match your actual convention (feature/, fix/, release/)
• Show the ideal workflow — this is prescriptive, not descriptive
• Use type: HIGHLIGHT on important merge commits
• Keep to 10–15 commits maximum for readability

---

Template

gitGraph
    accTitle: Your Title Here
    accDescr: Describe the branching strategy and merge pattern

    commit id: "initial"
    commit id: "second commit"

    branch feature/your-feature
    checkout feature/your-feature
    commit id: "feature work"
    commit id: "add tests"

    checkout main
    merge feature/your-feature id: "merge feature" tag: "v1.0"

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

Kanban Board

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: kanban Best for: Task status boards, workflow columns, work-in-progress visualization, sprint status When NOT to use: Task timelines/dependencies (use Gantt), process logic (use Flowchart)

⚠️ Accessibility: Kanban boards do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Kanban board showing the current sprint's work items distributed across four workflow columns, with emoji indicating column status:_

kanban
Backlog
  task1[🔐 Upgrade auth library]
  task2[🛡️ Add rate limiting]
  task3[📚 Write API docs]
In Progress
  task4[📊 Build dashboard]
  task5[🐛 Fix login bug]
In Review
  task6[💰 Refactor payments]
Done
  task7[📊 Deploy monitoring]
  task8[⚙️ Update CI pipeline]

⚠️ Tip: Each task gets ONE domain emoji at the start — this is your primary visual signal for categorization. Column emoji indicates workflow state.

---

Tips

• Name columns with status emoji for instant visual scanning
• Add domain emoji to tasks for quick categorization
• Keep to 3–5 columns
• Limit to 3–4 items per column (representative, not exhaustive)
• Items are simple text descriptions — keep concise
• Good for sprint snapshots in documentation
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the workflow columns and what the board represents. Always show all 6 columns:_

kanban
Backlog
  task1[🔧 Task description]
  task2[📝 Task description]
In Progress
  task3[⚙️ Task description]
In Review
  task4[👀 Task description]
Done
  task5[🚀 Task description]
Blocked
  task6[⛔ Task description]
Won't Do
  task7[❌ Task description]

⚠️ Always include all 6 columns — Backlog, In Progress, In Review, Done, Blocked, Won't Do. Even if a column is empty, include a placeholder item like [No items yet] to make the structure explicit.

---

Complex Example

_Sprint W07 board for the Payments Team showing a realistic distribution of work items across all six columns, including blocked items:_

kanban
Backlog
  b1[📊 Add pool monitoring to auth]
  b2[🔍 Evaluate PgBouncer]
  b3[📝 Update runbook for pool alerts]
In Progress
  ip1[📊 Build merchant dashboard MVP]
  ip2[📚 Write v2 API migration guide]
  ip3[🔐 Add OAuth2 PKCE flow]
In Review
  r1[🛡️ Request validation middleware]
Done
  d1[🛡️ Rate limiting on /v2/charges]
  d2[🐛 Fix pool exhaustion errors]
  d3[📊 Pool utilization alerts]
Blocked
  bl1[🔄 Auth service pool config]
Won't Do
  w1[❌ Mobile SDK in this sprint]

Tips for complex kanban diagrams:

• Add a Blocked column to surface stalled work — this is the highest-signal column on any board
• Keep items to 3–4 per column max even in complex boards — the diagram is a summary, not an exhaustive list
• Use the same emoji per domain across columns for visual tracking (📊 = dashboards, 🛡️ = security, 🐛 = bugs)
• Always show all 6 columns — use placeholder items like [No items] when a column is empty

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

Mindmap

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: mindmap Best for: Brainstorming, concept organization, knowledge hierarchies, topic breakdown When NOT to use: Sequential processes (use Flowchart), timelines (use Timeline)

⚠️ Accessibility: Mindmaps do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Mindmap showing a platform engineering team's key responsibility areas organized into infrastructure, developer experience, security, and observability domains:_

mindmap
    root((🏗️ Platform Engineering))
        ☁️ Infrastructure
            Kubernetes clusters
            Service mesh
            Load balancing
            Auto-scaling
        🔧 Developer Experience
            CI/CD pipelines
            Local dev environments
            Internal CLI tools
            Documentation
        🔐 Security
            Secret management
            Network policies
            Vulnerability scanning
            Access control
        📊 Observability
            Metrics collection
            Log aggregation
            Distributed tracing
            Alerting rules

---

Tips

• Keep to 3–4 main branches with 3–5 sub-items each
• Use emoji on branch headers for visual distinction
• Don't nest deeper than 3 levels
• Root node uses (( )) for circle shape
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of what this mindmap shows and the key categories it covers:_

mindmap
    root((🎯 Central Concept))
        📋 Branch One
            Sub-item A
            Sub-item B
            Sub-item C
        🔧 Branch Two
            Sub-item D
            Sub-item E
        📊 Branch Three
            Sub-item F
            Sub-item G
            Sub-item H

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

Packet Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: packet-beta Best for: Network protocol headers, data structure layouts, binary format documentation, bit-level specifications When NOT to use: General data models (use ER), system architecture (use C4 or Architecture)

⚠️ Accessibility: Packet diagrams do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Packet diagram showing the structure of a simplified TCP header with field sizes in bits:_

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"
    96-99: "Data Offset"
    100-105: "Reserved"
    106-111: "Flags (URG,ACK,PSH,RST,SYN,FIN)"
    112-127: "Window Size"
    128-143: "Checksum"
    144-159: "Urgent Pointer"

---

Tips

• Ranges are start-end: in bits (0-indexed)
• Keep field labels concise — abbreviate if needed
• Use for any fixed-width binary format, not just network packets
• Row width defaults to 32 bits — fields wrap naturally
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the protocol or data format and its field structure:_

packet-beta
    0-7: "Field A"
    8-15: "Field B"
    16-31: "Field C"
    32-63: "Field D"

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

Pie Chart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: pie Best for: Simple proportional breakdowns, budget allocation, composition, survey results When NOT to use: Trends over time (use XY Chart), exact comparisons (use a table), more than 7 categories

---

Exemplar Diagram

pie
    accTitle: Engineering Time Allocation
    accDescr: Pie chart showing how engineering team time is distributed across feature work, tech debt, bug fixes, on-call, and learning

    title 📊 Engineering Time Allocation
    "🔧 Feature development" : 45
    "🔄 Tech debt reduction" : 20
    "🐛 Bug fixes" : 20
    "📱 On-call & support" : 10
    "📚 Learning & growth" : 5

---

Tips

• Values are proportional — they don't need to sum to 100
• Use descriptive labels with emoji prefix for visual distinction
• Limit to 7 slices maximum — group small ones into "📦 Other"
• Always include a title with relevant emoji
• Order slices largest to smallest for readability

---

Template

pie
    accTitle: Your Title Here
    accDescr: Describe what proportions are being shown

    title 📊 Your Chart Title
    "📋 Category A" : 40
    "🔧 Category B" : 30
    "📦 Category C" : 20
    "🗂️ Other" : 10

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

Quadrant Chart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: quadrantChart Best for: Prioritization matrices, risk assessment, two-axis comparisons, effort/impact analysis When NOT to use: Time-based data (use Gantt or XY Chart), simple rankings (use a table)

⚠️ Accessibility: Quadrant charts do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Priority matrix plotting engineering initiatives by effort required versus business impact, helping teams decide what to build next:_

quadrantChart
    title 🎯 Engineering Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Plan Carefully
    quadrant-3 Reconsider
    quadrant-4 Quick Wins
    Upgrade auth library: [0.3, 0.9]
    Migrate to new DB: [0.9, 0.8]
    Fix typos in docs: [0.1, 0.2]
    Add dark mode: [0.4, 0.6]
    Rewrite legacy API: [0.95, 0.95]
    Update CI cache: [0.15, 0.5]
    Add unit tests: [0.5, 0.7]

---

Tips

• Label axes with Low X --> High X format
• Name all four quadrants with actionable labels
• Plot items as Name: [x, y] with values 0.0–1.0
• Limit to 5–10 items — more becomes cluttered
• Quadrant numbering: 1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the two axes and what the quadrant placement means:_

quadrantChart
    title 🎯 Your Matrix Title
    x-axis Low X Axis --> High X Axis
    y-axis Low Y Axis --> High Y Axis
    quadrant-1 High Both
    quadrant-2 High Y Only
    quadrant-3 Low Both
    quadrant-4 High X Only
    Item A: [0.3, 0.8]
    Item B: [0.7, 0.6]
    Item C: [0.2, 0.3]

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

Radar Chart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: radar-beta Mermaid version: v11.6.0+ Best for: Multi-dimensional comparisons, skill assessments, performance profiles, competitive analysis When NOT to use: Time series data (use XY Chart), simple proportions (use Pie)

⚠️ Accessibility: Radar charts do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Radar chart comparing two engineering candidates across six core competency areas, showing complementary strengths:_

radar-beta
    title Team Skill Assessment
    axis sys["System Design"], algo["Algorithms"], comms["Communication"], team["Teamwork"], ops["DevOps"], acq["Domain Knowledge"]
    curve candidate_a["Candidate A"]{4, 3, 5, 5, 2, 3}
    curve candidate_b["Candidate B"]{2, 5, 3, 3, 5, 4}
    max 5
    graticule polygon
    ticks 5
    showLegend true

---

Tips

• Define axes with axis id["Label"] — use short labels (1–2 words)
• Define curves with curve id["Label"]{val1, val2, ...} matching axis order
• Set max to normalize all values to the same scale
• graticule options: circle (default) or polygon
• ticks controls the number of concentric rings (default 5)
• showLegend true adds a legend for multiple curves
• Keep to 5–8 axes and 2–4 curves for readability
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of what dimensions are being compared across which entities:_

radar-beta
    title Your Radar Title
    axis dim1["Dimension 1"], dim2["Dimension 2"], dim3["Dimension 3"], dim4["Dimension 4"], dim5["Dimension 5"]
    curve series_a["Series A"]{3, 4, 2, 5, 3}
    curve series_b["Series B"]{5, 2, 4, 3, 4}
    max 5
    showLegend true

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

Requirement Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: requirementDiagram Best for: System requirements traceability, compliance mapping, formal requirements engineering When NOT to use: Informal task tracking (use Kanban), general relationships (use ER)

---

Exemplar Diagram

requirementDiagram

    requirement high_availability {
        id: 1
        text: System shall maintain 99.9 percent uptime
        risk: high
        verifymethod: test
    }

    requirement data_encryption {
        id: 2
        text: All data at rest shall be AES-256 encrypted
        risk: medium
        verifymethod: inspection
    }

    requirement session_timeout {
        id: 3
        text: Sessions expire after 30 minutes idle
        risk: low
        verifymethod: test
    }

    element auth_service {
        type: service
        docref: auth-service-v2
    }

    element crypto_module {
        type: module
        docref: crypto-lib-v3
    }

    auth_service - satisfies -> high_availability
    auth_service - satisfies -> session_timeout
    crypto_module - satisfies -> data_encryption

---

Tips

• Each requirement needs: id, text, risk, verifymethod
• `id` must be numeric — use id: 1, id: 2, etc. (dashes like REQ-001 can cause parse errors)
• Risk levels: low, medium, high (all lowercase)
• Verify methods: analysis, inspection, test, demonstration (all lowercase)
• Use element for design components that satisfy requirements
• Relationship types: - satisfies ->, - traces ->, - contains ->, - derives ->, - refines ->, - copies ->
• Keep to 3–5 requirements per diagram
• Avoid special characters in text fields — spell out symbols (e.g., "99.9 percent" not "99.9%")
• Use 4-space indentation inside { } blocks

---

Template

requirementDiagram

    requirement your_requirement {
        id: 1
        text: The requirement statement here
        risk: medium
        verifymethod: test
    }

    element your_component {
        type: service
        docref: component-ref
    }

    your_component - satisfies -> your_requirement

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

Sankey Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: sankey-beta Best for: Flow magnitude visualization, resource distribution, budget allocation, traffic routing When NOT to use: Simple proportions (use Pie), process steps (use Flowchart)

⚠️ Accessibility: Sankey diagrams do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Sankey diagram showing how a $100K monthly cloud budget flows from the total allocation through service categories (compute, storage, networking, observability) to specific AWS services, with band widths proportional to cost:_

sankey-beta

Cloud Budget,Compute,45000
Cloud Budget,Storage,25000
Cloud Budget,Networking,15000
Cloud Budget,Observability,10000
Cloud Budget,Security,5000

Compute,EC2 Instances,30000
Compute,Lambda Functions,10000
Compute,ECS Containers,5000

Storage,S3 Buckets,15000
Storage,RDS Databases,10000

Networking,CloudFront CDN,8000
Networking,API Gateway,7000

Observability,CloudWatch,6000
Observability,Datadog,4000

---

Tips

• Format: Source,Target,Value — one flow per line
• Values determine the width of each flow band
• Keep to 3 levels maximum (source → category → destination)
• Blank lines between groups improve source readability
• Good for answering "where does the 💰 go?" questions
• No emoji in node names (parser limitation) — use descriptive text
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of what flows from where to where and what the magnitudes represent:_

sankey-beta

Source,Category A,500
Source,Category B,300
Source,Category C,200

Category A,Destination 1,300
Category A,Destination 2,200

Category B,Destination 3,300

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

Sequence Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: sequenceDiagram Best for: API interactions, temporal flows, multi-actor communication, request/response patterns When NOT to use: Simple linear processes (use Flowchart), static relationships (use Class or ER)

---

Exemplar Diagram

sequenceDiagram
    accTitle: OAuth 2.0 Authorization Code Flow
    accDescr: Step-by-step OAuth flow between user browser, app server, and identity provider showing the token exchange and error path

    participant U as 👤 User Browser
    participant A as 🖥️ App Server
    participant I as 🔐 Identity Provider

    U->>A: Click Sign in
    A-->>U: Redirect to IdP

    U->>I: Enter credentials
    I->>I: 🔍 Validate credentials

    alt ✅ Valid credentials
        I-->>U: Redirect with auth code
        U->>A: Send auth code
        A->>I: Exchange code for token
        I-->>A: 🔐 Access + refresh token
        A-->>U: ✅ Set session cookie
        Note over U,A: 🔒 User is now authenticated
    else ❌ Invalid credentials
        I-->>U: ⚠️ Show error message
    end

---

Tips

• Limit to 4–5 participants — more becomes unreadable
• Solid arrows (->>) for requests, dashed (-->>) for responses
• Use alt/else/end for conditional branches
• Use Note over X,Y: for contextual annotations with emoji
• Use par/end for parallel operations
• Use loop/end for repeated interactions
• Emoji in message text works great for status clarity (✅, ❌, ⚠️, 🔐)

Common Patterns

Parallel calls:

par 📥 Fetch user
    A->>B: GET /user
and 📥 Fetch orders
    A->>C: GET /orders
end

Loops:

loop ⏰ Every 30 seconds
    A->>B: Health check
    B-->>A: ✅ 200 OK
end

---

Template

sequenceDiagram
    accTitle: Your Title Here
    accDescr: Describe the interaction between participants and what the sequence demonstrates

    participant A as 👤 Actor
    participant B as 🖥️ System
    participant C as 💾 Database

    A->>B: 📤 Request action
    B->>C: 🔍 Query data
    C-->>B: 📥 Return results
    B-->>A: ✅ Deliver response

---

Complex Example

A microservices checkout flow with 6 participants grouped in box regions. Shows parallel calls, conditional branching, error handling with break, retry logic, and contextual notes — the full toolkit for complex sequences.

sequenceDiagram
    accTitle: Microservices Checkout Flow
    accDescr: Multi-service checkout sequence showing parallel inventory and payment processing, error recovery with retries, and async notification dispatch across client, gateway, and backend service layers

    box rgb(237,233,254) 🌐 Client Layer
        participant browser as 👤 Browser
    end

    box rgb(219,234,254) 🖥️ API Layer
        participant gw as 🌐 API Gateway
        participant order as 📋 Order Service
    end

    box rgb(220,252,231) ⚙️ Backend Services
        participant inventory as 📦 Inventory
        participant payment as 💰 Payment
        participant notify as 📤 Notifications
    end

    browser->>gw: 🛒 Submit checkout
    gw->>gw: 🔐 Validate JWT token
    gw->>order: 📋 Create order

    Note over order: 📊 Order status: PENDING

    par ⚡ Parallel validation
        order->>inventory: 📦 Reserve items
        inventory-->>order: ✅ Items reserved
    and
        order->>payment: 💰 Authorize card
        payment-->>order: ✅ Payment authorized
    end

    alt ✅ Both succeeded
        order->>payment: 💰 Capture payment
        payment-->>order: ✅ Payment captured
        order->>inventory: 📦 Confirm reservation

        Note over order: 📊 Order status: CONFIRMED

        par 📤 Async notifications
            order->>notify: 📧 Send confirmation email
        and
            order->>notify: 📱 Send push notification
        end

        order-->>gw: ✅ Order confirmed
        gw-->>browser: ✅ Show confirmation page

    else ❌ Inventory unavailable
        order->>payment: 🔄 Void authorization
        order-->>gw: ⚠️ Items out of stock
        gw-->>browser: ⚠️ Show stock error

    else ❌ Payment declined
        order->>inventory: 🔄 Release reservation

        loop 🔄 Retry up to 2 times
            order->>payment: 💰 Retry authorization
            payment-->>order: ❌ Still declined
        end

        order-->>gw: ❌ Payment failed
        gw-->>browser: ❌ Show payment error
    end

Why this works

• `box` grouping clusters participants by architectural layer — readers instantly see which services are client-facing vs backend
• `par` blocks show parallel inventory + payment checks happening simultaneously, which is how real checkout systems work for performance
• Nested `alt`/`else` covers the happy path AND two distinct failure modes, each with proper cleanup (void auth, release reservation)
• `loop` for retry logic shows the payment retry pattern without cluttering the happy path
• Emoji in messages makes scanning fast — 📦 for inventory, 💰 for payment, ✅/❌ for outcomes

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

State Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: stateDiagram-v2 Best for: State machines, lifecycle flows, status transitions, object lifecycles When NOT to use: Sequential processes with many steps (use Flowchart), timing-critical interactions (use Sequence)

---

Exemplar Diagram

stateDiagram-v2
    accTitle: Order Fulfillment Lifecycle
    accDescr: State machine for an e-commerce order from placement through payment, fulfillment, and delivery with cancellation paths

    [*] --> Placed: 📋 Customer submits

    Placed --> PaymentPending: 💰 Initiate payment
    PaymentPending --> PaymentFailed: ❌ Declined
    PaymentPending --> Confirmed: ✅ Payment received

    PaymentFailed --> Placed: 🔄 Retry payment
    PaymentFailed --> Cancelled: 🚫 Customer cancels

    Confirmed --> Picking: 📦 Warehouse picks
    Picking --> Shipped: 🚚 Carrier collected
    Shipped --> Delivered: ✅ Proof of delivery
    Delivered --> [*]: 🏁 Complete

    Cancelled --> [*]: 🏁 Closed

    note right of Confirmed
        📋 Inventory reserved
        💰 Invoice generated
    end note

---

Tips

• Always start with [*] (initial state) and end with [*] (terminal)
• Label transitions with emoji + action for visual clarity
• Use note right of / note left of for contextual details
• State names: CamelCase (Mermaid convention for state diagrams)
• Use nested states sparingly: state "name" as s1 { ... }
• Keep to 8–10 states maximum

---

Template

stateDiagram-v2
    accTitle: Your Title Here
    accDescr: Describe the entity lifecycle and key transitions between states

    [*] --> InitialState: ⚡ Trigger event

    InitialState --> ActiveState: ▶️ Action taken
    ActiveState --> CompleteState: ✅ Success
    ActiveState --> FailedState: ❌ Error

    CompleteState --> [*]: 🏁 Done
    FailedState --> [*]: 🏁 Closed

---

Complex Example

A CI/CD pipeline modeled as a state machine with 3 composite (nested) states, each containing internal substates. Shows how source changes flow through build, test, and deploy phases with failure recovery and rollback transitions.

stateDiagram-v2
    accTitle: CI/CD Pipeline State Machine
    accDescr: Composite state diagram for a CI/CD pipeline showing source detection, build and test phases with parallel scanning, and a three-stage deployment with approval gate and rollback path

    [*] --> Source: ⚡ Commit pushed

    state "📥 Source" as Source {
        [*] --> Idle
        Idle --> Fetching: 🔄 Poll detected change
        Fetching --> Validating: 📋 Checkout complete
        Validating --> [*]: ✅ Config valid
    }

    Source --> Build: ⚙️ Pipeline triggered

    state "🔧 Build & Test" as Build {
        [*] --> Compiling
        Compiling --> UnitTests: ✅ Build artifact ready
        UnitTests --> IntegrationTests: ✅ Unit tests pass
        IntegrationTests --> SecurityScan: ✅ Integration pass
        SecurityScan --> [*]: ✅ No vulnerabilities

        note right of Compiling
            📦 Docker image built
            🏷️ Tagged with commit SHA
        end note
    }

    Build --> Deploy: 📦 Artifact published
    Build --> Failed: ❌ Build or test failure

    state "🚀 Deployment" as Deploy {
        [*] --> Staging
        Staging --> WaitApproval: ✅ Staging healthy
        WaitApproval --> Production: ✅ Approved
        WaitApproval --> Cancelled: 🚫 Rejected
        Production --> Monitoring: 🚀 Deployed
        Monitoring --> [*]: ✅ Stable 30 min

        note right of WaitApproval
            👤 Requires team lead approval
            ⏰ Auto-reject after 24h
        end note
    }

    Deploy --> Rollback: ❌ Health check failed
    Rollback --> Deploy: 🔄 Revert to previous
    Deploy --> Complete: 🏁 Pipeline finished
    Failed --> Source: 🔧 Fix pushed
    Cancelled --> [*]: 🏁 Pipeline aborted
    Complete --> [*]: 🏁 Done

    state Failed {
        [*] --> AnalyzeFailure
        AnalyzeFailure --> NotifyTeam: 📤 Alert sent
        NotifyTeam --> [*]
    }

    state Rollback {
        [*] --> RevertArtifact
        RevertArtifact --> RestorePrevious: 🔄 Previous version
        RestorePrevious --> VerifyRollback: 🔍 Health check
        VerifyRollback --> [*]
    }

Why this works

• Composite states group pipeline phases — Source, Build & Test, and Deployment each contain their internal flow, readable in isolation or as part of the whole
• Failure and rollback are first-class states — not just transition labels. The Failed and Rollback states have their own internal substates showing what actually happens during recovery
• Notes on key states add operational context — the approval gate has timeout rules, the compile step documents the artifact format. This is the kind of detail operators need.
• Transitions between composite states are the high-level flow (Source → Build → Deploy → Complete), while transitions within composites are the detailed steps. Two levels of reading for two audiences.

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

Timeline

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: timeline Best for: Chronological events, historical progression, milestones over time, release history When NOT to use: Task durations/dependencies (use Gantt), detailed project plans (use Gantt)

⚠️ Accessibility: Timelines do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_Timeline of a startup's growth milestones from founding through Series A, organized by year and quarter:_

timeline
    title 🚀 Startup Growth Milestones
    section 2024
        Q1 : 💡 Founded : Built MVP
        Q2 : 🧪 Beta launch : 100 users
        Q3 : 📈 Product-market fit : 1K users
        Q4 : 💰 Seed round : $2M raised
    section 2025
        Q1 : 👥 Team of 10 : Hired engineering lead
        Q2 : 🌐 Public launch : 10K users
        Q3 : 🏢 Enterprise tier : First B2B deal
        Q4 : 📊 $1M ARR : Series A prep
    section 2026
        Q1 : 🚀 Series A : $15M raised

---

Tips

• Use section to group by year, quarter, or phase
• Each entry can have multiple items separated by :
• Keep items concise — 2–4 words each
• Emoji at the start of key items for visual anchoring
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the timeline and the period it covers:_

timeline
    title 📋 Your Timeline Title
    section Period 1
        Event A : Detail one : Detail two
        Event B : Detail three
    section Period 2
        Event C : Detail four
        Event D : Detail five : Detail six

---

Complex Example

_Multi-year technology platform evolution tracking a startup's journey from monolith through microservices to AI-powered platform. Six sections span 2020-2025, each capturing key technical milestones and business metrics that drove architecture decisions:_

timeline
    title 🚀 Platform Architecture Evolution
    section 2020 — Monolith Era
        Q1 : 💡 Founded company : Rails monolith launched : 10 engineers
        Q3 : ⚠️ Hit scaling ceiling : 50K concurrent users : Database bottleneck
    section 2021 — Breaking Apart
        Q1 : 🔐 Extracted auth service : 🐳 Adopted Docker : CI/CD pipeline live
        Q3 : 📦 Split order processing : ⚡ Added Redis cache : 200K users
    section 2022 — Microservices
        Q1 : ⚙️ 8 services in production : ☸️ Kubernetes migration : Service mesh pilot
        Q3 : 📥 Event-driven architecture : 📊 Observability stack : 500K users
    section 2023 — Platform Maturity
        Q1 : 🌐 Multi-region deployment : 🛡️ Zero-trust networking : 50 engineers
        Q3 : 🔄 Canary deployments : 📈 99.99% uptime SLA : 2M users
    section 2024 — AI Integration
        Q1 : 🧠 ML recommendation engine : ⚡ Real-time personalization
        Q3 : 🔍 AI-powered search : 📊 Predictive analytics : 5M users
    section 2025 — Next Generation
        Q1 : ☁️ Edge computing rollout : 🤖 AI agent platform : 10M users

Why this works

• 6 sections are eras, not just years — "Monolith Era", "Breaking Apart", "Microservices" tell the story of _why_ the architecture changed, not just _when_
• Business metrics alongside tech milestones — user counts and team size appear next to architecture decisions. This shows the _pressure_ that drove each evolution (50K users → scaling ceiling → extracted services)
• Multiple items per time point — each quarter packs 2-3 items separated by :, giving a dense but scannable view of everything happening in parallel
• Emoji anchors the scan — eyes land on 🧠 ML, 🌐 Multi-region, ⚡ Redis before reading the text. For a quick skim, the emoji alone tells the story

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

Treemap Diagram

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: treemap-beta Mermaid version: v11.12.0+ Best for: Hierarchical data proportions, budget breakdowns, disk usage, portfolio composition When NOT to use: Simple flat proportions (use Pie), flow-based hierarchy (use Sankey)

⚠️ Accessibility: Treemap diagrams do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

>

⚠️ GitHub support: Treemap is very new — verify it renders on your target GitHub version before using.

---

Exemplar Diagram

_Treemap showing annual cloud infrastructure costs broken down by service category and specific service, with rectangle sizes proportional to spend:_

treemap-beta
"Compute"
    "EC2 Instances": 45000
    "Lambda Functions": 12000
    "ECS Containers": 8000
"Storage"
    "S3 Buckets": 18000
    "RDS Databases": 15000
    "DynamoDB": 6000
"Networking"
    "CloudFront CDN": 9000
    "API Gateway": 7000
"Observability"
    "CloudWatch": 5000
    "Datadog": 8000

---

Tips

• Parent nodes (sections) use quoted text: "Section Name"
• Leaf nodes add a value: "Leaf Name": 123
• Hierarchy is created by indentation (spaces or tabs)
• Values determine the size of each rectangle — larger value = larger area
• Keep to 2–3 levels of nesting for clarity
• Use classDef and :::class syntax for styling nodes
• Always pair with a Markdown text description above for screen readers

---

Template

_Description of the hierarchical data and what the proportions represent:_

treemap-beta
"Category A"
    "Sub A1": 40
    "Sub A2": 25
"Category B"
    "Sub B1": 20
    "Sub B2": 15

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

User Journey

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: journey Best for: User experience mapping, customer journey, process satisfaction scoring, onboarding flows When NOT to use: Simple processes without satisfaction data (use Flowchart), chronological events (use Timeline)

---

Exemplar Diagram

journey
    accTitle: New Developer Onboarding Experience
    accDescr: Journey map tracking a new developer through day-one setup, first-week integration, and month-one productivity with satisfaction scores at each step

    title 👤 New Developer Onboarding
    section 📋 Day 1 Setup
        Read onboarding doc       : 3 : New Dev
        Clone repositories        : 4 : New Dev
        Configure local env       : 2 : New Dev
        Run into setup issues     : 1 : New Dev
    section 🤝 Week 1 Integration
        Meet the team             : 5 : New Dev
        Pair program on first PR  : 4 : New Dev, Mentor
        Navigate codebase         : 2 : New Dev
        First PR merged           : 5 : New Dev
    section 🚀 Month 1 Productivity
        Own a small feature       : 4 : New Dev
        Participate in code review: 4 : New Dev
        Ship to production        : 5 : New Dev

---

Tips

• Scores: 1 = 😤 frustrated, 3 = 😐 neutral, 5 = 😄 delighted
• Assign actors after the score: 5 : Actor1, Actor2
• Use section with emoji prefix to group by time period or phase
• Focus on pain points (low scores) — that's where the insight is
• Keep to 3–4 sections with 3–4 steps each

---

Template

journey
    accTitle: Your Title Here
    accDescr: Describe the user journey and what experience insights it reveals

    title 👤 Journey Title
    section 📋 Phase 1
        Step one           : 3 : Actor
        Step two           : 4 : Actor
    section 🔧 Phase 2
        Step three         : 2 : Actor
        Step four          : 5 : Actor

---

Complex Example

A multi-persona e-commerce journey comparing a New Customer vs Returning Customer across 5 phases. The two actors experience the same flow with different satisfaction scores, revealing exactly where first-time UX needs investment.

journey
    accTitle: E-Commerce Customer Journey Comparison
    accDescr: Side-by-side journey map comparing new customer and returning customer satisfaction across discovery, shopping, checkout, fulfillment, and post-purchase phases to identify first-time experience gaps

    title 👤 E-Commerce Customer Journey Comparison
    section 🔍 Discovery
        Find the product         : 3 : New Customer, Returning Customer
        Read reviews             : 4 : New Customer, Returning Customer
        Compare alternatives     : 3 : New Customer
        Go to saved favorite     : 5 : Returning Customer
    section 🛒 Shopping
        Add to cart              : 4 : New Customer, Returning Customer
        Apply coupon code        : 2 : New Customer
        Use stored coupon        : 5 : Returning Customer
        Choose shipping option   : 3 : New Customer, Returning Customer
    section 💰 Checkout
        Enter payment details    : 2 : New Customer
        Use saved payment        : 5 : Returning Customer
        Review and confirm       : 4 : New Customer, Returning Customer
        Receive confirmation     : 5 : New Customer, Returning Customer
    section 📦 Fulfillment
        Track shipment           : 3 : New Customer, Returning Customer
        Receive delivery         : 5 : New Customer, Returning Customer
        Unbox product            : 5 : New Customer, Returning Customer
    section 🔄 Post-Purchase
        Leave a review           : 2 : New Customer
        Contact support          : 1 : New Customer
        Reorder same item        : 5 : Returning Customer
        Recommend to friend      : 3 : Returning Customer

Why this works

• Two personas on the same map — instead of two separate diagrams, both actors appear in each step. The satisfaction gap between New Customer (2-3) and Returning Customer (4-5) is immediately visible in checkout and post-purchase.
• 5 sections follow the real funnel — discovery → shopping → checkout → fulfillment → post-purchase. Each section tells a story about where the experience breaks down for new users.
• Some steps are persona-specific — "Compare alternatives" is only New Customer, "Reorder same item" is only Returning Customer. This shows divergent paths within the shared journey.
• Low scores are the actionable insight — New Customer scores 1-2 on payment entry, coupon application, and support contact. These are the specific UX investments that would improve conversion.

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

XY Chart

Back to [Style Guide](../mermaid_style_guide.md) — Read the style guide first for emoji, color, and accessibility rules.

Syntax keyword: xychart-beta Best for: Numeric data visualization, trends over time, bar/line comparisons, metric dashboards When NOT to use: Proportional breakdowns (use Pie), qualitative comparisons (use Quadrant)

⚠️ Accessibility: XY charts do not support accTitle/accDescr. Always place a descriptive _italic_ Markdown paragraph directly above the code block.

---

Exemplar Diagram

_XY chart comparing monthly revenue growth (bars) versus customer acquisition cost (line) over six months, showing improving unit economics as revenue rises while CAC steadily decreases:_

xychart-beta
    title "📈 Revenue vs Customer Acquisition Cost"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Thousands ($)" 0 --> 120
    bar [20, 35, 48, 62, 78, 95]
    line [50, 48, 45, 40, 35, 30]

---

Tips

• Combine bar and line to show different metrics on the same chart
• Use emoji in the title for visual flair: "📈 Revenue Growth"
• Use quoted title and axis labels
• Define axis range with min --> max
• Keep data points to 6–12 for readability
• Multiple bar or line entries create grouped series
• Always pair with a detailed Markdown text description above for screen readers

---

Template

_Description of what the X axis, Y axis, bars, and lines represent and the key insight:_

xychart-beta
    title "📊 Your Chart Title"
    x-axis [Label1, Label2, Label3, Label4]
    y-axis "Unit" 0 --> 100
    bar [25, 50, 75, 60]
    line [30, 45, 70, 55]