How to: Document a System Architecture

A workflow for documenting a software system using three diagram types on a single Confluence page - flowchart for the high-level overview, sequence diagram for interactions, and ERD for the data model.

Page Structure

Architecture Page
├── Section 1: System Overview (Flowchart)
├── Section 2: Request Flow (Sequence Diagram)
└── Section 3: Data Model (ERD)

Step 1 - System Overview Flowchart

1. Edit the Confluence page, type / → UML Diagrams → insert

2. In the Source panel, write a top-down flowchart:

   flowchart TD
       Client([Web / Mobile Client])
       API[API Gateway]
       Auth[Auth Service]
       DB[(Primary Database)]
       Cache[(Redis Cache)]
   
       Client --> API
       API --> Auth
       Auth -->|valid| API
       API --> Cache
       Cache -->|miss| DB
       DB --> Cache
       Cache --> API
       API --> Client
   

3. Verify preview, click Save, then add a heading above it: "System Overview"

→ Diagrams Macro

Step 2 - Request Sequence Diagram

1. Below the flowchart section, insert another UML Diagrams macro

2. Write the sequence diagram:

   sequenceDiagram
       participant Client
       participant Gateway as API Gateway
       participant Auth as Auth Service
       participant DB as Database
   
       Client->>Gateway: POST /api/resource
       activate Gateway
       Gateway->>Auth: Validate token
       Auth-->>Gateway: 200 OK
       Gateway->>DB: INSERT resource
       DB-->>Gateway: resource_id
       Gateway-->>Client: 201 Created {id}
       deactivate Gateway
   

3. Save, add heading: "Request Flow"

Step 3 - Data Model ERD

1. Insert another UML Diagrams macro

2. Write the ERD:

   erDiagram
       USER {
           int id PK
           string email
           string name
           datetime created_at
       }
       PROJECT {
           int id PK
           string name
           int owner_id FK
       }
       RESOURCE {
           int id PK
           string title
           int project_id FK
           int created_by FK
       }
   
       USER ||--o{ PROJECT : "owns"
       PROJECT ||--o{ RESOURCE : "contains"
       USER ||--o{ RESOURCE : "creates"
   

3. Save, add heading: "Data Model"

Step 4 - Publish and Maintain

1. Publish the page
2. To update a diagram: hover over it in view mode → click Edit in the hover toolbar
3. Source is preserved - edit and re-save

→ Diagram Types Reference · Examples Library