Skip to main content

AI Reference

This document is a complete reference for generating Mermaid diagrams that work inside the Apportunity: Mermaid Diagrams app for Confluence and Jira.

Use this document as context when asking an AI assistant (Claude, Gemini, ChatGPT, etc.) to generate diagrams:

Here is the reference: [link to this file]. Create a Mermaid diagram for [your task].

App Overview​

The Mermaid Diagrams app is available as two separate Atlassian Marketplace products:

  • Apportunity: Mermaid Diagrams Macro for Confluence — insert diagrams as macros on any Confluence page using the Insert (+) → Mermaid Diagram menu.
  • Apportunity: Mermaid Diagrams for Jira — view and create diagrams in the Diagrams panel on any Jira Work Item detail view.

Both apps support all 16 diagram types listed in this document. Each diagram is defined entirely as text (Mermaid syntax), with no external tools or image uploads required.

Choosing the Right Diagram Type​

Use the table below to match your Atlassian scenario to the best diagram type.

ScenarioRecommended Diagram
Document a process, decision tree, or workflowflowchart
Illustrate API call sequences, authentication flows, or service interactionssequenceDiagram
Plan a sprint, release schedule, or project timelinegantt
Model a codebase's class structure or data schemaclassDiagram
Document Jira workflow states and transitionsstateDiagram-v2
Model database relationships or data entitieserDiagram
Map a user's experience across touchpointsjourney
Show percentage breakdown (budget, issues by type, test results)pie
Prioritize initiatives on a 2×2 effort/impact matrixquadrantChart
Document system or compliance requirementsrequirementDiagram
Visualize a Git branching strategygitGraph
Brainstorm topics or organize knowledge hierarchicallymindmap
Show a product or technology history chronologicallytimeline
Visualize resource or energy flow between categoriessankey-beta
Plot bar or line data (KPIs, sprint velocity, metrics)xychart-beta
Lay out system architecture with precise block placementblock-beta

Diagram Types — Core (Full Reference)​

1. Flowchart (flowchart)​

Best for: Decision trees, process flows, escalation paths, runbooks, onboarding guides.

In Jira: Attach acceptance criteria decision trees, bug triage flows, or escalation processes to a Work Item.

In Confluence: Use in incident response playbooks, process documentation, or onboarding pages.

Syntax​

flowchart TD
    A[Start] --> B{Is it critical?}
    B -->|Yes| C[Escalate to On-Call]
    B -->|No| D[Add to Backlog]
    C --> E[Create P0 Jira Issue]
    D --> F[Triage in Sprint Planning]

Direction options: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Node shapes:

  • A[Text] — rectangle
  • B(Text) — rounded rectangle
  • C{Text} — diamond (decision)
  • D((Text)) — circle
  • E([Text]) — stadium / pill
  • F[[Text]] — subroutine

Edge types:

  • --> — arrow
  • --- — open line
  • -->|Label| — labeled arrow
  • -.-> — dotted arrow
  • ==> — thick arrow

Subgraphs:

flowchart LR
    subgraph Team A
        A1[Design] --> A2[Build]
    end
    subgraph Team B
        B1[QA] --> B2[Deploy]
    end
    A2 --> B1

Atlassian Example: Bug escalation process​

flowchart TD
    A[Bug Reported] --> B{Severity?}
    B -->|Critical| C[Page On-Call Engineer]
    B -->|High| D[Assign to Current Sprint]
    B -->|Low| E[Add to Backlog]
    C --> F[Create P0 Jira Issue]
    D --> G[Assign to Team Lead]
    E --> H[Label: needs-triage]

2. Sequence Diagram (sequenceDiagram)​

Best for: API call flows, authentication sequences, microservice interactions, feature design.

In Jira: Attach to feature issues or bug reports to illustrate request/response flows.

In Confluence: Use in technical design documents, API documentation, or architecture decision records (ADRs).

Syntax​

sequenceDiagram
    participant User
    participant Frontend
    participant AuthService
    participant DB

    User->>Frontend: Submit credentials
    Frontend->>AuthService: POST /login
    AuthService->>DB: Validate user
    DB-->>AuthService: User record
    AuthService-->>Frontend: JWT token
    Frontend-->>User: Redirect to dashboard

Arrow types:

  • ->> — solid arrow (synchronous call)
  • -->> — dashed arrow (return / async response)
  • -) — async message (open arrow)
  • --)— async return

Activation boxes: activate / deactivate

sequenceDiagram
    User->>+Server: Request
    Server->>+DB: Query
    DB-->>-Server: Result
    Server-->>-User: Response

Notes:

sequenceDiagram
    Note over Alice,Bob: Token expires in 24h
    Alice->>Bob: Refresh token

Loop, alt, opt blocks:

sequenceDiagram
    loop Every 30s
        Client->>Server: Heartbeat
    end

    alt Token valid
        Server-->>Client: 200 OK
    else Token expired
        Server-->>Client: 401 Unauthorized
    end

Atlassian Example: Confluence page creation via API​

sequenceDiagram
    participant Script as Script Console
    participant API as Confluence REST API
    participant DB as Confluence Storage

    Script->>API: POST /wiki/api/v2/pages
    API->>DB: Persist page content
    DB-->>API: Page ID
    API-->>Script: 200 OK + page object
    Script->>Script: console.log(page.id)

3. Gantt Chart (gantt)​

Best for: Sprint planning, release roadmaps, project milestone tracking.

In Confluence: Use in project planning pages, sprint roadmaps, or release schedules.

In Jira: Attach to an Epic or project-level issue to document the planned schedule.

Syntax​

gantt
    title Q3 Feature Release
    dateFormat YYYY-MM-DD
    excludes weekends

    section Design
        UX Research       :a1, 2024-07-01, 14d
        Wireframes        :after a1, 7d

    section Development
        Backend API       :2024-07-15, 21d
        Frontend          :2024-07-22, 14d

    section QA
        Testing           :2024-08-05, 10d
        Bug Fixes         :2024-08-15, 7d

Rules:

  • dateFormat is required — always specify it (YYYY-MM-DD is the most common format).
  • Task duration: use Nd for days, Nw for weeks, Nh for hours.
  • Reference a previous task with after <taskId> for sequential dependencies.
  • Mark milestones: append :milestone, before the date.
  • Mark tasks as done: prefix with done, — e.g., done, a1, 2024-07-01, 14d.
  • Mark critical tasks: prefix with crit,.

Atlassian Example: Jira Epic delivery plan​

gantt
    title Epic: User Authentication Revamp
    dateFormat YYYY-MM-DD

    section Discovery
        Requirements       :done, r1, 2024-06-01, 5d
        Tech Design        :done, r2, after r1, 5d

    section Build
        Backend OAuth      :b1, 2024-06-14, 10d
        Frontend Login UI  :b2, after b1, 7d
        Token Management   :b3, after b1, 5d

    section Release
        QA & Testing       :t1, after b2, 7d
        Deploy to Prod     :milestone, after t1, 1d

4. Class Diagram (classDiagram)​

Best for: Modeling object-oriented code, database schemas, domain models.

In Confluence: Use in technical design docs, API documentation, or architecture pages.

In Jira: Attach to feature or architecture issues to illustrate data model changes.

Syntax​

classDiagram
    class User {
        +String id
        +String email
        +String role
        +login()
        +logout()
    }

    class Project {
        +String id
        +String name
        +List~Issue~ issues
        +addIssue(issue)
    }

    class Issue {
        +String key
        +String status
        +User assignee
        +transition(status)
    }

    User "1" --> "many" Project : manages
    Project "1" *-- "many" Issue : contains
    Issue --> User : assigned to

Relationship types:

  • <|-- — inheritance
  • *-- — composition
  • o-- — aggregation
  • --> — association
  • ..> — dependency
  • ..|> — realization

Visibility modifiers: + public, - private, # protected, ~ package

Generic types: List~String~, Map~String, Int~

Atlassian Example: Jira data model​

classDiagram
    class JiraIssue {
        +String key
        +String summary
        +String status
        +String priority
        +transition(targetStatus)
    }
    class JiraUser {
        +String accountId
        +String displayName
        +String email
    }
    class JiraProject {
        +String key
        +String name
        +List~JiraIssue~ issues
    }
    JiraProject "1" *-- "many" JiraIssue : contains
    JiraIssue --> JiraUser : assigned to
    JiraIssue --> JiraUser : reported by

5. State Diagram (stateDiagram-v2)​

Best for: Documenting Jira workflow states and transitions, object lifecycle models (order states, user account states).

In Jira: Document how issues move through workflow states on a project or issue type.

In Confluence: Use in feature specifications, onboarding pages, or technical design documents.

Syntax​

stateDiagram-v2
    [*] --> ToDo

    ToDo --> InProgress : Start work
    InProgress --> InReview : Submit for review
    InReview --> InProgress : Request changes
    InReview --> Done : Approve
    Done --> [*]

Composite states (nested):

stateDiagram-v2
    [*] --> Active
    Active --> Inactive : Suspend
    Inactive --> Active : Resume
    state Active {
        [*] --> Idle
        Idle --> Processing : Request received
        Processing --> Idle : Done
    }

Concurrent states:

stateDiagram-v2
    [*] --> Running
    state Running {
        [*] --> Logging
        --
        [*] --> Monitoring
    }

Notes:

stateDiagram-v2
    Pending --> Approved : Manager approves
    note right of Approved
        Triggers Jira transition
        to Done status
    end note

Atlassian Example: Jira Service Management ticket lifecycle​

stateDiagram-v2
    [*] --> New
    New --> InProgress : Agent picks up
    InProgress --> Pending : Waiting on customer
    Pending --> InProgress : Customer responds
    InProgress --> Resolved : Issue fixed
    Resolved --> Closed : Auto-close after 5 days
    Resolved --> Reopened : Customer rejects resolution
    Reopened --> InProgress : Agent reassigned
    Closed --> [*]

Diagram Types — Additional​

These diagram types are supported by the app. Use the keyword and minimal example below to prompt AI for diagrams of this type.

Entity Relationship Diagram (erDiagram)​

Cardinality syntax: ||--o{ (one-to-many optional), ||--|{ (one-to-many required), }|..|{ (many-to-many).

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Use when: Designing or documenting database schemas, API data models, or domain entities.

User Journey (journey)​

Rate steps from 1 (painful) to 5 (delightful). Multiple actors per step are allowed.

journey
    title User onboarding flow
    section Sign Up
        Visit landing page : 5: User
        Complete form      : 3: User
        Verify email       : 2: User
    section First Login
        Dashboard tour     : 4: User, Support
        Create first item  : 4: User

Use when: Mapping customer or user experience steps, identifying friction points in a product flow.

Pie Chart (pie)​

pie title Issues by Type
    "Bug"         : 42
    "Story"       : 35
    "Task"        : 18
    "Epic"        : 5

Use when: Showing proportions — sprint issue breakdown, test pass/fail ratio, budget allocation.

Quadrant Chart (quadrantChart)​

Points are placed at [x, y] coordinates between 0.0 and 1.0.

quadrantChart
    title Feature Prioritization
    x-axis Low Effort --> High Effort
    y-axis Low Value --> High Value
    quadrant-1 Quick wins
    quadrant-2 Major projects
    quadrant-3 Fill-ins
    quadrant-4 Thankless tasks
    Feature A: [0.2, 0.8]
    Feature B: [0.7, 0.9]
    Feature C: [0.8, 0.3]

Use when: Prioritizing features, risks, or campaigns on a 2×2 matrix.

Requirement Diagram (requirementDiagram)​

requirementDiagram
    requirement auth_req {
        id: REQ-01
        text: The system must support SSO via SAML 2.0.
        risk: high
        verifymethod: test
    }
    element auth_module {
        type: component
    }
    auth_module - satisfies -> auth_req

Use when: Documenting system, compliance, or product requirements and their traceability.

Gitgraph Diagram (gitGraph)​

gitGraph
    commit tag: "v1.0"
    branch develop
    checkout develop
    commit
    branch feature/login
    checkout feature/login
    commit
    commit
    checkout develop
    merge feature/login
    checkout main
    merge develop tag: "v1.1"

Use when: Explaining Git branching strategies (Git Flow, trunk-based development) in engineering wikis or Confluence ADRs.

Mindmap (mindmap)​

Indentation defines hierarchy. Use root((...)) for the central node.

mindmap
  root((Sprint Goal))
    Authentication
      SSO Integration
      MFA Setup
    Performance
      DB Query Optimization
      Caching Layer
    Docs
      API Reference
      Onboarding Guide

Use when: Brainstorming sprint themes, organizing knowledge, or mapping product areas.

Timeline (timeline)​

timeline
    title Product Launch History
    2022 : MVP Released
    2023 : Mobile App
         : API v2
    2024 : Enterprise Tier
    2025 : AI Features

Use when: Showing product history, roadmap milestones, or technology adoption over time.

Sankey Diagram (sankey-beta)​

Format: Source,Destination,Value (one flow per line, comma-separated, no header row).

sankey-beta
    Budget,Engineering,500
    Budget,Design,150
    Budget,Marketing,200
    Engineering,Backend,300
    Engineering,Frontend,200

Use when: Visualizing resource allocation, data flow, or energy/cost distribution between categories.

XY Chart (xychart-beta)​

xychart-beta
    title "Sprint Velocity"
    x-axis [S1, S2, S3, S4, S5, S6]
    y-axis "Story Points" 0 --> 60
    bar [32, 41, 38, 55, 49, 52]
    line [32, 41, 38, 55, 49, 52]

Use when: Plotting time-series or categorical data — KPIs, sprint velocity, test coverage trends.

Block Diagram (block-beta)​

Use columns N to define layout width. Useful when automatic flowchart layout produces unwanted placement.

block-beta
    columns 3
    Frontend["Web App"]
    API["REST API"]
    DB[("Database")]
    Frontend --> API
    API --> DB

Use when: Visualizing system architecture where you need precise control over block placement.

Theming​

Apply a theme using the %%{init}%% directive as the first line of the diagram. This directive is case-sensitive.

Built-in Themes​

ThemeBest for
defaultLight-mode Confluence pages
darkDark-mode pages or high-contrast
forestGreen-accented, nature themes
neutralSubtle grayscale, formal docs
baseFully customizable baseline
%%{init: {'theme': 'dark'}}%%
flowchart TD
    A[Deploy] --> B[Verify] --> C[Done]

Custom Colors​

Use base theme with themeVariables to override individual colors:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0052CC', 'primaryTextColor': '#ffffff', 'lineColor': '#172b4d'}}}%%
flowchart LR
    A[Jira Issue] --> B[In Review] --> C[Done]

Common themeVariables:

VariableControls
primaryColorNode fill color
primaryTextColorText inside nodes
primaryBorderColorNode border color
lineColorArrow and edge color
secondaryColorSecondary node fill
tertiaryColorSubgraph background
backgroundDiagram background

Rules for Generating Good Diagrams​

  1. Output raw Mermaid syntax only. Do not wrap the output in extra prose unless asked. The user pastes the code block directly into the app's editor.

  2. No HTML in node labels. The app disables htmlLabels for security. Use plain text inside node labels — no <b>, <br>, or other HTML tags. Use \n for line breaks where supported.

  3. No %%{securityLevel}%% directive. This is ignored by the app. Do not include it.

  4. Prefer shorter labels. Long labels in nodes make diagrams hard to read. Break content into multiple nodes rather than putting everything in one label.

  5. Split large diagrams. Diagrams with hundreds of nodes can render slowly or fail. Suggest breaking complex systems into multiple focused diagrams.

  6. Always specify dateFormat in Gantt charts. Without it the chart will not render. YYYY-MM-DD is the safest choice.

  7. Use stateDiagram-v2, not stateDiagram. The v2 variant is the current standard and has better layout support.

  8. Use flowchart over graph. Both work, but flowchart is the current standard keyword with full feature support.

  9. Validate syntax before providing. Common failure causes: missing closing brackets ] or }, wrong indentation in mindmap or timeline, mismatched subgraph end, or unsupported newer Mermaid features not yet in the app version.

  10. Use the %%{init}%% directive only when theming is requested. It adds visual noise when unnecessary. Default rendering already uses a clean theme matching the Atlassian UI.