Skip to main content

How to Create Architecture Diagrams in Confluence (3 Tools Compared)

· 14 min read
NGPilot
NGPilot
NGPilot

Architecture diagrams are the backbone of technical documentation. They show how services communicate, where data flows, and which infrastructure components underpin your system. When a new engineer joins your team, the first thing they look for is an architecture diagram. When something breaks in production, the incident response starts at the same diagram.

Yet many teams store their architecture diagrams in external tools -- draw.io, Lucidchart, or even desktop applications -- detached from the documentation where they matter most. Confluence is where your runbooks live, where architecture decision records are written, and where post-mortem discussions happen. Keeping your architecture diagrams inside Confluence eliminates context-switching and ensures diagrams evolve alongside the written documentation they illustrate.

This guide walks through three ways to create architecture diagrams directly in Confluence, using NGPILOT apps designed for different workflows. Every Mermaid example is copy-paste ready, so you can insert it into a Confluence page and see the result immediately.

Why Confluence is the right place for architecture diagrams​

Before diving into the tools, it is worth understanding why embedding diagrams in Confluence matters more than linking to an external diagramming tool.

Single source of truth. When architecture diagrams live on the same page as the design docs, ADRs, and runbooks that reference them, everything stays synchronized. You edit the diagram and the surrounding documentation in one place.

Access control built in. Confluence space permissions already govern who can view and edit your documentation. Diagrams embedded as macros inherit those same permissions. No separate account provisioning or license management for an external diagramming service.

Search and discovery. Confluence's full-text search indexes page content, including macro content. Team members searching for "payment service" or "Kubernetes cluster" will find the pages containing those diagrams.

No file attachment drift. Exported PNG and SVG files attached to Confluence pages go stale the moment the architecture changes. Embedded macros always render the current version of the diagram.

Collaborative editing. Multiple team members can edit a Confluence page and its embedded diagrams. Changes are tracked in the page history, making it easy to see when and how the architecture evolved.

Step-by-step tutorial: Creating architecture diagrams in Confluence​

Step 1 -- Choose your architecture diagram tool​

Three NGPILOT apps support architecture diagrams in Confluence, each with a different approach:

  • Mermaid Plus for Confluence -- Write architecture diagrams in text-based Mermaid syntax. Best for teams that want versionable, diffable diagrams they can maintain alongside code. Supports flowcharts, C4 diagrams, and the dedicated architecture-beta diagram type.

  • Excalidraw Plus for Confluence -- Draw architecture diagrams visually on a freeform canvas with drag-and-drop shapes. Ships with 220+ shape libraries including AWS, Azure, and GCP icon packs. Best for teams that prefer visual editing and want pixel-perfect cloud architecture diagrams.

  • Diagram Duo for Confluence -- Combines both Excalidraw and Mermaid in a single macro. Switch between a visual canvas and a text-based code editor depending on which part of the architecture you are documenting. Best for teams that want maximum flexibility.

Step 2 -- Install the app from Atlassian Marketplace​

Go to the Atlassian Marketplace and search for your chosen app:

  • Search Mermaid Plus for Confluence for the text-based workflow
  • Search Excalidraw Plus for Confluence for the visual drawing workflow
  • Search Diagram Duo for Confluence for the combined workflow

Click Get App and follow the installation prompts. If your organization requires admin approval for marketplace apps, contact your Confluence administrator.

All three apps support Confluence Cloud and Confluence Data Center.

Step 3 -- Insert the macro on a Confluence page​

Open any Confluence page in edit mode and use the slash command for your app:

  • Type /mermaid and select Mermaid Plus for Confluence
  • Type /excalidraw and select Excalidraw Plus for Confluence
  • For Diagram Duo, type /excalidraw or /mermaid to insert the respective editor

The macro editor opens, and you can start building your diagram immediately.

Step 4 -- Build your architecture diagram​

The workflow differs depending on which tool you chose:

With Mermaid Plus, write or paste Mermaid syntax in the code editor. The live preview on the left renders your diagram in real time. Use subgraphs to group related services, and use the architecture-beta or C4Context diagram types for structured architecture views.

With Excalidraw Plus, open the shape library panel and search for the cloud provider or infrastructure category you need. Drag AWS, Azure, or GCP shapes onto the canvas, connect them with arrows, and add labels. The freeform canvas lets you position elements exactly where you want them.

With Diagram Duo, switch between the Excalidraw tab and the Mermaid tab as needed. Start with a visual sketch on the Excalidraw canvas, then formalize parts of the architecture in Mermaid syntax -- or work in whichever mode suits the current section of the diagram.

Step 5 -- Save and share with your team​

Click Save on the macro to persist your diagram, then Publish the Confluence page. The diagram renders inline when anyone views the page. Team members with edit permissions can click the macro and select Edit to modify the architecture diagram directly.

Diagrams support dark mode automatically. When a viewer has Confluence dark mode enabled, the diagram adapts its colors for readability.

3 Mermaid architecture diagram examples (copy-paste ready)​

These three examples cover the most common architecture diagram patterns. Copy the code block, paste it into the Mermaid Plus macro in Confluence, and adjust the service names and connections to match your system.

Example 1 -- Microservices architecture​

This diagram shows a typical microservices deployment with an API gateway, multiple backend services, shared infrastructure, and asynchronous event-driven communication. Use this as a starting point for documenting any service-oriented architecture.

graph TB
    subgraph Clients
        Web[Web Application]
        Mobile[Mobile App]
        CLI[CLI Tools]
    end

    subgraph Gateway
        APIGW[API Gateway<br/>Rate Limiting & Auth]
    end

    subgraph Services
        UserSvc[User Service]
        OrderSvc[Order Service]
        CatalogSvc[Catalog Service]
        PaymentSvc[Payment Service]
        NotifySvc[Notification Service]
    end

    subgraph Data Layer
        UserDB[(User DB<br/>PostgreSQL)]
        OrderDB[(Order DB<br/>PostgreSQL)]
        CatalogDB[(Catalog DB<br/>MongoDB)]
        Redis[(Redis Cache)]
    end

    subgraph Messaging
        EventBus[Event Bus<br/>Kafka]
    end

    subgraph External
        Stripe[Stripe API]
        SendGrid[SendGrid API]
    end

    Web --> APIGW
    Mobile --> APIGW
    CLI --> APIGW

    APIGW --> UserSvc
    APIGW --> OrderSvc
    APIGW --> CatalogSvc

    UserSvc --> UserDB
    UserSvc --> Redis

    OrderSvc --> OrderDB
    OrderSvc --> Redis
    OrderSvc --> PaymentSvc
    OrderSvc --> EventBus

    CatalogSvc --> CatalogDB
    CatalogSvc --> Redis

    PaymentSvc --> Stripe
    PaymentSvc --> EventBus

    EventBus --> NotifySvc
    NotifySvc --> SendGrid

How to customize this diagram:

  • Add or remove services in the Services subgraph to match your architecture
  • Change database labels to reflect your actual technology choices (MySQL, DynamoDB, Cosmos DB, etc.)
  • Add connection labels with arrow syntax: OrderSvc -->|gRPC| PaymentSvc
  • Use style directives to color-code services by team ownership or criticality

Example 2 -- AWS cloud architecture​

This diagram models a production AWS deployment with a VPC, public and private subnets, load balancing, container orchestration, and managed database services. It uses the Mermaid flowchart syntax with labeled subgraphs to represent AWS regions and VPCs.

graph TB
    subgraph AWS["AWS Cloud"]
        subgraph VPC["VPC 10.0.0.0/16"]
            subgraph Public["Public Subnet"]
                ALB[Application Load Balancer]
                NAT[NAT Gateway]
                Bastion[Bastion Host]
            end

            subgraph Private["Private Subnet"]
                subgraph ECS["ECS Cluster"]
                    TaskA[API Service<br/>Fargate Task]
                    TaskB[Worker Service<br/>Fargate Task]
                end
            end

            subgraph Data["Data Subnet"]
                RDS[(RDS PostgreSQL<br/>Multi-AZ)]
                ElastiCache[(ElastiCache<br/>Redis Cluster)]
            end
        end

        subgraph Global["Global Services"]
            Route53[Route 53<br/>DNS]
            CloudFront[CloudFront<br/>CDN]
            S3[S3 Bucket<br/>Static Assets]
            SQS[SQS Queue]
            Secrets[Secrets Manager]
        end
    end

    Users[Users / Clients] --> Route53
    Route53 --> CloudFront
    CloudFront --> ALB
    CloudFront --> S3

    ALB --> TaskA
    TaskA --> ElastiCache
    TaskA --> RDS
    TaskA --> SQS
    TaskA --> Secrets

    SQS --> TaskB
    TaskB --> RDS
    TaskB --> Secrets

    NAT --> TaskA
    NAT --> TaskB

For more detailed AWS diagrams with precise icon representations, use Excalidraw Plus for Confluence with the AWS shape library. Excalidraw provides pixel-accurate AWS architecture icons that match the official AWS Architecture Center diagrams.

Example 3 -- C4 model system context​

The C4 model provides four levels of architecture abstraction: Context, Container, Component, and Code. Mermaid supports C4 diagrams natively through the C4Context and C4Container diagram types. This example shows a system context diagram for a SaaS product.

C4Context
    title System Context Diagram - Order Management Platform

    Person(customer, "Customer", "Places orders and tracks deliveries")
    Person(admin, "Admin", "Manages products and monitors system health")
    Person(support, "Support Agent", "Handles customer inquiries and refunds")

    System(omp, "Order Management Platform", "Core platform handling orders, inventory, and payments")

    System_Ext(payment, "Payment Gateway", "Processes credit card and PayPal transactions")
    System_Ext(email, "Email Service", "Sends order confirmations and shipping notifications")
    System_Ext(wms, "Warehouse Management", "Tracks physical inventory and shipping")
    System_Ext(analytics, "Analytics Platform", "Collects events for business intelligence")

    Enterprise_Boundary(enterprise, "Organization Boundary") {
        System(bi, "BI Dashboard", "Internal reporting and metrics")
    }

    Rel(customer, omp, "Places orders via", "HTTPS/Web")
    Rel(admin, omp, "Manages catalog via", "HTTPS/Web")
    Rel(support, omp, "Looks up orders via", "HTTPS/Web")

    Rel(omp, payment, "Charges customers via", "REST API")
    Rel(omp, email, "Sends notifications via", "SMTP/API")
    Rel(omp, wms, "Syncs inventory via", "REST API")
    Rel(omp, analytics, "Publishes events via", "Kafka")
    Rel(bi, analytics, "Queries data from", "SQL")

Tips for C4 diagrams in Mermaid:

  • Start with C4Context for the broadest view, then drill into C4Container for individual system internals
  • Use System_Ext for external dependencies your team does not control
  • Use Enterprise_Boundary to distinguish internal and external systems
  • Add Rel connections with technology labels to document integration protocols

Comparison: Mermaid vs Excalidraw vs Diagram Duo for architecture diagrams​

Each of the three tools has distinct strengths for architecture documentation. The right choice depends on your team's workflow and the type of architecture diagram you need.

CriteriaMermaid PlusExcalidraw PlusDiagram Duo
Input methodText syntax (code editor)Visual canvas (drag and drop)Both in one macro
Cloud provider shapesText labels with subgraphs220+ shape libraries (AWS, Azure, GCP)Both approaches available
C4 model supportNative C4Context and C4Container typesManual arrangement of shapesCan combine C4 Mermaid with visual annotations
Auto-layoutYes -- Mermaid handles positioningNo -- manual placementMermaid tab auto-layouts; Excalidraw tab is manual
Version control / diffsExcellent -- text-based, easy to diff in page historyLimited -- binary diagram dataMermaid parts are diffable; Excalidraw parts are not
Collaboration styleEdit code and preview side by sideDirect visual manipulation on canvasChoose mode per editing session
Learning curveModerate -- need to learn Mermaid syntaxLow -- drag and drop is intuitiveModerate -- learn both workflows
Best forStructured architecture docs, C4 diagrams, change-tracked diagramsCloud architecture diagrams with provider icons, whiteboard-style architecture sessionsTeams that need both structured and freeform diagrams

When to choose Mermaid Plus​

Pick Mermaid Plus when your architecture diagrams are part of formal documentation that changes frequently and needs to be reviewed through diffs. The text-based approach means every change is visible in Confluence page history. It is also the best choice for C4 model diagrams, since Mermaid has native support for C4Context and C4Container syntax.

Read the full documentation: Mermaid Plus for Confluence usage guide.

When to choose Excalidraw Plus​

Pick Excalidraw Plus when you need pixel-perfect cloud architecture diagrams that use official AWS, Azure, or GCP icons. The visual canvas is also better suited for architecture brainstorming sessions where the diagram evolves rapidly and team members need to move elements freely without worrying about syntax errors.

Excalidraw Plus ships with 220+ shape libraries. For architecture diagrams specifically, the AWS Architecture, Azure Icons, Google Cloud Platform, Kubernetes, and Network Diagram libraries are the most relevant.

Read the full documentation: Excalidraw Plus for Confluence usage guide.

When to choose Diagram Duo​

Pick Diagram Duo when your team has mixed preferences -- some engineers want to write Mermaid code, others want to draw visually. Diagram Duo gives you both editors in a single macro, so you can start with an Excalidraw whiteboard sketch during a meeting, then formalize the architecture in Mermaid afterward. Or use Excalidraw for the cloud infrastructure layer and Mermaid for the service interaction layer, all on the same diagram.

Read the full documentation: Diagram Duo for Confluence usage guide.

Best practices for architecture diagrams in Confluence​

Regardless of which tool you choose, these best practices will help you create architecture diagrams that are clear, maintainable, and useful to your team.

Start with the system context before diving into details​

The C4 model's philosophy is sound: begin with a context diagram that shows your system and its external dependencies, then progressively add detail. A context diagram fits on a single screen and gives readers the big picture before they encounter the complexity of container-level or component-level diagrams.

Use consistent naming conventions​

Establish a naming standard for services, databases, and external systems across all your architecture diagrams. If the payment service is called "Payment Service" in one diagram and "PaymentSvc" in another, readers will waste time wondering whether they are the same thing. Document your naming convention on a dedicated Confluence page and link to it from every architecture diagram.

Color-code by domain or team ownership​

Use colors to distinguish different ownership domains. For example, make all infrastructure components gray, all backend services blue, all data stores green, and all external integrations orange. This makes it immediately clear which parts of the architecture a given team owns and which cross team boundaries.

In Mermaid, use the style directive to apply colors:

style APIGW fill:#4A90D9,stroke:#2C5F8A,color:#fff
style OrderDB fill:#52B788,stroke:#2D6A4F,color:#fff
style Stripe fill:#F4A261,stroke:#E76F51,color:#fff

In Excalidraw, select shapes and apply fill colors directly from the color picker.

Keep diagrams to one level of abstraction​

Do not mix infrastructure details (subnets, load balancers) with application-level concepts (service boundaries, domain events) in the same diagram. If you need both views, create two diagrams and link between them on the Confluence page. A diagram that tries to show everything at once becomes unreadable.

Add a legend​

Every architecture diagram should include a brief legend that explains the color coding, shape meanings, and line styles used. In Mermaid, add a note block at the bottom of the diagram. In Excalidraw, place the legend in the corner of the canvas.

Version your diagrams with page history​

One of the underappreciated benefits of embedding diagrams in Confluence is that page history tracks every change. When someone asks "when did we add the cache layer?" you can answer precisely by looking at the page history. Make it a habit to include a brief change description when you publish updates to architecture diagram pages.

Create a two-way link between your architecture diagrams and the ADRs (Architecture Decision Records) that explain why the architecture looks the way it does. The diagram shows what the system looks like; the ADR explains why. Together, they give new team members the full picture.

Schedule regular reviews​

Architecture diagrams drift from reality faster than most teams realize. Set a quarterly calendar reminder to review your key architecture diagrams against the actual system. This is especially important for teams practicing continuous deployment, where infrastructure changes can happen daily.

Architecture diagrams are the most referenced documents in any engineering organization. By creating and maintaining them directly in Confluence, you ensure they are always accessible, always up to date, and always connected to the documentation that gives them context. Pick the tool that matches your team's workflow -- text-based Mermaid Plus, visual Excalidraw Plus, or the combined flexibility of Diagram Duo -- and start building architecture diagrams that your team will actually use.