Back to Guides

/gcloud-kit:diagram

Generate Mermaid architecture diagrams from service design artifacts.

Overview

Creates a set of architecture diagrams in Mermaid syntax by reading the service design, SDD, and supplier profile. Diagrams visualise service boundaries, technical layers, data flows, and deployment topology. GitHub renders Mermaid natively in markdown preview.

Usage

/gcloud-kit:diagram My Cloud Platform

Arguments: Service name (must match an existing service directory).

Prerequisites

  • Service design (services/{name}/service-design.md) — required
  • SDD (services/{name}/sdd.md) — optional, improves technical detail
  • Supplier profile (services/supplier/supplier-profile.md) — optional, adds infrastructure context

Output

services/{name}/diagrams.md

What it does

  1. Loads context from service design, SDD, and supplier profile
  2. Asks which diagrams to generate (all, or individual selection)
  3. Generates up to 4 diagram types:
    • Service Overview (flowchart TD) — buyer organisations, service boundaries, and integration points
    • Technical Architecture (flowchart TD) — presentation, application, data, and infrastructure layers with actual technology stack
    • Data Flow (flowchart LR) — data ingress, processing, encryption controls, storage, and egress paths with UK data residency
    • Deployment View (flowchart TD) — UK regions, cloud providers, redundancy, failover paths, and backup strategy
  4. Customises each diagram using data from the loaded documents
  5. Adds descriptive notes and rendering instructions
  6. Writes the assembled diagrams document

Diagram rendering

  • GitHub / GitLab: Renders Mermaid natively in markdown preview
  • VS Code: Install "Markdown Preview Mermaid Support" extension
  • CLI: npx @mermaid-js/mermaid-cli -i diagrams.md -o diagrams.pdf
  • Online: Paste at mermaid.live

Lot-specific behaviour

  • Lot 1 (Cloud Hosting): Emphasises infrastructure layers, compute topology, and storage architecture
  • Lot 2 (Cloud Software): Emphasises application layers, user interfaces, and integration APIs
  • Lot 3 (Cloud Support): May show service delivery model (remote/on-site/hybrid) rather than infrastructure

Related commands