DocsTemplates

Templates

10 min read

Ready-to-use architecture templates: three-tier web app, microservices, auth flows, C4, ER diagrams, state machines, CI/CD, and event-driven patterns.

Ready-to-use architecture templates. Click Open in Archgram on any code block to load it directly into the editor, or copy the code and paste it manually.

Three-Tier Web Application

Classic presentation → application → data tier pattern. Good starting point for any web service.

graph TD
    User([Browser / Mobile]) --> CDN[CDN / Edge Cache]
    CDN --> LB[Load Balancer]
    LB --> App1[App Server A]
    LB --> App2[App Server B]
    App1 & App2 --> Cache[(Redis Cache)]
    App1 & App2 --> DB[(PostgreSQL Primary)]
    DB --> DBR[(Read Replica)]
    App1 & App2 --> S3[Object Storage]

    subgraph Presentation
      CDN
    end
    subgraph Application Tier
      LB
      App1
      App2
    end
    subgraph Data Tier
      Cache
      DB
      DBR
      S3
    end

Microservices Platform

API gateway + domain services + async messaging. Suitable for platform and e-commerce architectures.

graph LR
    Client([Client Apps]) --> GW[API Gateway]
    GW --> Auth[Auth Service]
    GW --> Orders[Order Service]
    GW --> Catalog[Catalog Service]
    GW --> Users[User Service]

    Orders --> Bus([Kafka])
    Bus --> Notify[Notification Service]
    Bus --> Billing[Billing Service]
    Bus --> Inventory[Inventory Service]

    Auth --> AuthDB[(Auth DB)]
    Orders --> OrderDB[(Order DB)]
    Catalog --> CatalogDB[(Catalog DB)]
    Users --> UserDB[(User DB)]
    Billing --> BillingDB[(Billing DB)]

    subgraph Core Services
      Auth
      Orders
      Catalog
      Users
    end
    subgraph Async Consumers
      Notify
      Billing
      Inventory
    end

API Authentication Flow

OAuth 2.0 / JWT login sequence — useful for security review and onboarding docs.

sequenceDiagram
    autonumber
    actor User
    participant App as React SPA
    participant GW as API Gateway
    participant Auth as Auth Service
    participant DB as User Store
    participant Cache as Token Cache

    User->>App: Enter credentials
    App->>GW: POST /auth/login
    GW->>Auth: Forward request
    Auth->>DB: Look up user by email
    DB-->>Auth: User record + hashed password
    Auth->>Auth: bcrypt.compare(password, hash)
    alt Invalid credentials
      Auth-->>GW: 401 Unauthorized
      GW-->>App: 401
      App-->>User: Show error
    else Valid credentials
      Auth->>Auth: Sign JWT (15 min) + refresh token (7 days)
      Auth->>Cache: Store refresh token hash
      Auth-->>GW: 200 {access_token, refresh_token}
      GW-->>App: 200 tokens
      App->>App: Store tokens in memory / HttpOnly cookie
      App-->>User: Redirect to dashboard
    end

C4 System Context — SaaS Product

Level 1 C4 diagram showing external actors and system boundaries. Always draw this first.

C4Context
  title System Context — Archgram SaaS

  Person(architect, "Solution Architect", "Creates and maintains architecture diagrams")
  Person(dev, "Developer", "Views diagrams linked in PRs and ADRs")
  Person(admin, "Platform Admin", "Manages teams, billing, and AI config")

  System(archgram, "Archgram", "AI-powered architecture diagramming and delivery orchestration platform")

  System_Ext(github, "GitHub", "Stores .mmd diagram files; triggers PR review workflow")
  System_Ext(ai, "AI Provider", "LLM API used for diagram generation, refinement, and explanation")
  System_Ext(stripe, "Stripe", "Handles subscription billing and plan management")
  System_Ext(email, "Email / SMTP", "Sends invite, notification, and billing emails")

  Rel(architect, archgram, "Creates diagrams, runs AI features, manages Flow")
  Rel(dev, archgram, "Views shared diagrams, reviews architecture changes")
  Rel(admin, archgram, "Manages users, configures AI provider, monitors usage")
  Rel(archgram, github, "Reads / writes .mmd files via GitHub API")
  Rel(archgram, ai, "Calls LLM API for generation, refinement, explain")
  Rel(archgram, stripe, "Creates subscriptions, webhooks for payment events")
  Rel(archgram, email, "Sends transactional emails")

C4 Container — API Platform

Level 2 view showing the major deployable containers and their interactions.

C4Container
  title Container Diagram — Archgram Platform

  Person(user, "Architect / Developer")

  Container_Boundary(frontend, "Frontend") {
    Container(spa, "React SPA", "Vite + React + Tailwind", "Editor, docs, blog, admin console")
  }

  Container_Boundary(backend, "Backend") {
    Container(edge, "Edge Functions", "Supabase Edge (Deno)", "AI generation, file processing, webhooks")
    ContainerDb(db, "PostgreSQL", "Supabase Postgres", "Diagrams, users, orgs, flow data, audit log")
    ContainerDb(storage, "Object Storage", "Supabase Storage", "Exported SVG/PNG assets, handoff packs")
    Container(realtime, "Realtime", "Supabase Realtime", "Live collaboration presence and cursors")
  }

  System_Ext(ai, "AI Provider (LLM API)")
  System_Ext(github, "GitHub API")
  System_Ext(stripe, "Stripe API")

  Rel(user, spa, "Uses", "HTTPS")
  Rel(spa, db, "CRUD via PostgREST", "HTTPS / RLS")
  Rel(spa, edge, "Invokes AI features", "HTTPS")
  Rel(spa, realtime, "Subscribes to changes", "WebSocket")
  Rel(spa, storage, "Uploads / downloads assets", "HTTPS")
  Rel(edge, ai, "LLM completions", "HTTPS")
  Rel(edge, github, "Reads / writes .mmd files", "HTTPS")
  Rel(edge, stripe, "Manages subscriptions", "HTTPS")
  Rel(edge, db, "Service-role writes", "Internal")

ER Diagram — E-Commerce Schema

Core tables for an order management system. Good reference for domain modelling discussions.

erDiagram
    USER {
      uuid id PK
      string email
      string name
      string role
      timestamptz created_at
    }
    ADDRESS {
      uuid id PK
      uuid user_id FK
      string line1
      string city
      string country
      string postcode
    }
    PRODUCT {
      uuid id PK
      string sku UK
      string name
      text description
      numeric price
      int stock_qty
    }
    ORDER {
      uuid id PK
      uuid user_id FK
      uuid shipping_address_id FK
      string status
      numeric total_amount
      timestamptz placed_at
    }
    ORDER_LINE {
      uuid id PK
      uuid order_id FK
      uuid product_id FK
      int quantity
      numeric unit_price
    }
    PAYMENT {
      uuid id PK
      uuid order_id FK
      string provider
      string provider_ref
      string status
      numeric amount
      timestamptz paid_at
    }

    USER ||--o{ ADDRESS : "has"
    USER ||--o{ ORDER : "places"
    ADDRESS ||--o{ ORDER : "ships to"
    ORDER ||--|{ ORDER_LINE : "contains"
    PRODUCT ||--o{ ORDER_LINE : "included in"
    ORDER ||--o| PAYMENT : "settled by"

Order Lifecycle State Machine

State diagram for an order — shows all transitions and terminal states clearly.

stateDiagram-v2
    [*] --> Draft : Customer adds items

    Draft --> PendingPayment : Checkout initiated
    Draft --> Cancelled : Abandoned (TTL expired)

    PendingPayment --> PaymentProcessing : Payment submitted
    PendingPayment --> Cancelled : Payment abandoned

    PaymentProcessing --> Confirmed : Payment authorised
    PaymentProcessing --> PaymentFailed : Payment declined

    PaymentFailed --> PendingPayment : Customer retries
    PaymentFailed --> Cancelled : Max retries exceeded

    Confirmed --> Picking : Warehouse receives order
    Picking --> Packed : All items picked
    Packed --> Dispatched : Carrier collected

    Dispatched --> InTransit : Carrier scanned
    InTransit --> Delivered : Delivery confirmed
    InTransit --> ReturnInitiated : Delivery failed 3×

    Delivered --> ReturnInitiated : Customer requests return
    ReturnInitiated --> ReturnReceived : Item received at warehouse
    ReturnReceived --> Refunded : Refund processed

    Delivered --> [*]
    Refunded --> [*]
    Cancelled --> [*]

CI/CD Pipeline

Modern trunk-based delivery pipeline with quality gates and staged rollout.

graph TD
    PR[Pull Request] --> Lint[Lint & Type-check]
    Lint --> UnitTest[Unit Tests]
    UnitTest --> Build[Build + Bundle]
    Build --> IntTest[Integration Tests]
    IntTest --> SecurityScan[SAST / Dependency Scan]

    SecurityScan -->|Pass| Preview[Deploy Preview Env]
    SecurityScan -->|Fail| Block([Block merge])

    Preview --> E2E[E2E Tests — Playwright]
    E2E -->|Pass| Approve{Code Review Approved?}
    E2E -->|Fail| Block

    Approve -->|Yes| Merge[Merge to main]
    Approve -->|No| Block

    Merge --> StagingDeploy[Deploy → Staging]
    StagingDeploy --> SmokeTest[Smoke Tests]
    SmokeTest -->|Pass| ProdDeploy[Deploy → Production 10%]
    SmokeTest -->|Fail| Rollback([Rollback])

    ProdDeploy --> Canary{Canary healthy?}
    Canary -->|Yes| FullRollout[Full rollout 100%]
    Canary -->|No| Rollback

    FullRollout --> Monitor[Monitor — errors, latency, apdex]

Event-Driven Architecture

Event sourcing + CQRS pattern — shows commands, events, projections, and read models.

graph LR
    Client([Client]) --> CmdAPI[Command API]

    CmdAPI --> CmdHandler[Command Handler]
    CmdHandler --> DomainModel[Domain Model]
    DomainModel --> EventStore[(Event Store)]

    EventStore --> EventBus([Event Bus / Kafka])

    EventBus --> Proj1[Order Projection]
    EventBus --> Proj2[Inventory Projection]
    EventBus --> Proj3[Analytics Projection]
    EventBus --> Saga[Saga Orchestrator]

    Proj1 --> OrderReadDB[(Order Read Model)]
    Proj2 --> InvReadDB[(Inventory Read Model)]
    Proj3 --> AnalyticsDB[(Analytics Store)]

    Saga --> CmdAPI

    QueryAPI[Query API] --> OrderReadDB
    QueryAPI --> InvReadDB
    Client --> QueryAPI

    subgraph Write Side
      CmdAPI
      CmdHandler
      DomainModel
      EventStore
    end
    subgraph Read Side
      QueryAPI
      OrderReadDB
      InvReadDB
      AnalyticsDB
    end

PreviousC4 Model

Next Export & Sharing