Diagram driven design

Diagram-Driven Design

Overview

A diagram is the densest requirements document that exists. When a user hands you a draw.io or Mermaid diagram of their infrastructure — current state or target state — they have already answered half the interview: the components, the boundaries, the flows. Your job is to read it rigorously, extract the architecture, find what's missing, and convert it into a Mission Brief that routes the rest of the lifecycle.

The diagram is a hypothesis, not gospel. Users draw what they think they have (current state often drifts from reality) and what they hope to build (target state often skips the unglamorous parts: backups, secrets, monitoring, HA). Treat the diagram as the primary input, then verify and complete it.

Out of the diagram comes the same Mission Brief that interview-me produces — objective, workload, constraints, impediments, success criteria, recommended route. Two entry doors, one destination: the Define phase of the cycle.

When to Use

• The user uploads or pastes a draw.io file (.drawio, .xml, exported mxGraph XML)
• The user pastes Mermaid source (flowchart, graph, C4Context, architecture diagrams)
• The user describes a topology in structured text ("users hit an ALB, then two EC2s, then RDS") that can be treated as an inline diagram
• A repository contains architecture diagrams that should drive design work

When NOT to use:

• No diagram and no topology description exists → offer interview-me instead
• The diagram is of application code structure, not infrastructure → out of scope
• A live incident is in progress → mitigate first (incident-response-and-postmortems)

The Process

Step 1: Ingest and parse

draw.io — the XML is the truth, not the rendered picture:

<mxGraphModel>
  <root>
    <mxCell id="alb" value="Application Load Balancer" style="...;shape=mxgraph.aws4.elb;" vertex="1" parent="vpc"/>
    <mxCell id="vpc" value="VPC 10.0.0.0/16" style="...;fillColor=none;strokeColor=#248814;" vertex="1" parent="1"/>
    <mxCell id="flow1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="alb" target="ec2a"/>
  </root>
</mxGraphModel>

• mxCell with vertex="1" → a component (the value is its label; parent gives containment = boundaries)
• mxCell with edge="1" → a flow (source → target; the value often holds the protocol/port label)
• Containment chains (parent) reveal boundaries: regions, VPCs/VNets, subnets, accounts, clusters, namespaces
• AWS/Azure/GCP stencil styles (mxgraph.aws4.*, mxgraph.azure.*) identify the intended service even when the label is vague

Mermaid — parse structurally:

flowchart LR
  subgraph VPC["VPC 10.0.0.0/16"]
    subgraph PUB["Public subnets"]
      ALB[Application Load Balancer]
    end
    subgraph PRIV["Private subnets"]
      A[App pod] --> DB[(PostgreSQL)]
    end
    ALB --> A
  end
  U[Users] -->|HTTPS 443| ALB

• subgraph → boundaries (accounts, VPCs, clusters, namespaces, zones)
• X[...], X(...), X[(...)] → components (rectangles = services, cylinders = data stores)
• -->, ---, -.-> → flows; edge labels (|HTTPS 443|) carry protocols
• Direction (LR, TD) hints at traffic flow; dashed lines often mean async/optional/management paths

Structured text descriptions — treat each sentence as nodes and edges and proceed identically.

Step 2: Build the component inventory

Extract and tabulate:

COMPONENT INVENTORY
- Compute:      [VMs, pods, functions, app services — with counts if shown]
- Data:         [databases, caches, queues, buckets — engine and statefulness]
- Edge:         [load balancers, ingress, CDNs, DNS, VPN/bastion entry points]
- Identity:     [IAM boundaries, shown or absent]
- Boundaries:   [accounts/subscriptions/projects, VPCs, clusters, namespaces, regions]
- Flows:        [protocol + direction per edge; note any unlabeled edges]
- External:     [third-party APIs, SaaS, internet exposure]

Every unlabeled edge is a question. "Users → App" with no protocol means you must ask or flag it.

Step 3: Classify the workload

From the inventory, determine per component: stateless / stateful / batch, runtime hints, traffic path, data sensitivity (PII? payments?), and blast radius if it fails. This feeds the Mission Brief's workload line.

Step 4: Gap and risk analysis — what's NOT in the diagram

This is where the skill earns its place. Check systematically:

PRESENT IN DIAGRAM?  IF ABSENT →
□ Backups / snapshots          → data loss exposure; route backup-dr-and-capacity
□ Secrets management           → where do credentials live? route secrets-management-and-identity
□ Monitoring / logging / alerts→ flying blind; route observability-and-alerting
□ CI/CD path                   → how does code reach this? route ci-cd-pipeline-engineering
□ Redundancy (multi-AZ/replica)→ single points of failure; flag in Ground/Design
□ TLS at every external edge   → plaintext exposure; flag in Secure
□ Network segmentation         → flat network = lateral movement; flag in Ground
□ IaC ownership                → is any of this codified? route terraform-infrastructure-as-code
□ Cost signals                 → NAT gateways, multi-region, idle replicas: flag budget questions

Each gap becomes either an interview question (if intent is unclear) or a design requirement in the brief (if the answer is obvious from context).

Step 5: Produce the Mission Brief

Identical format to interview-me — one confirmed artifact regardless of entry door:

MISSION BRIEF (from diagram)

- Source:           <draw.io file / Mermaid / description; current-state or target-state>
- Objective:        <one line — what this infrastructure must achieve>
- Workload:         <component classes, statefulness, traffic profile>
- Current state:    <what exists per the diagram; flag drift risk if "current">
- Success:          <measurable done — reachability, SLOs, compliance gates>
- Binding constraints: <inferred from diagram + user answers: cloud, regions, compliance, access>
- Gaps to close:    <the Step 4 findings: backups, secrets, observability, HA…>
- Out of scope:     <explicitly not doing>
- Recommended route: <phase sequence, e.g.: Ground (cloud-platform-foundations)
                      → Deploy (terraform → kubernetes → gitops)
                      → Secure (secrets → supply-chain) → Observe>

Yes / no / refine?

Step 6: Confirm, then route

Present the brief for explicit confirmation — including the gaps you added. The user may say "no backups needed, it's ephemeral" (fine, record it in Out of scope) or "I forgot monitoring" (added to route). On explicit yes, hand the Recommended route to the lifecycle: typically cloud-platform-foundations (Ground) first, then the phase sequence.

If the diagram describes a current environment, add a verification step early in the route: compare the diagram against reality (cloud inventory, kubectl get all -A, Terraform state list) before designing on top of it. Diagrams of existing systems drift; designing on drifted assumptions builds on sand.

Output

The deliverable is the confirmed Mission Brief (from diagram) plus the structured component inventory and gap list. Downstream skills consume the brief exactly as they consume the interview-me brief. For multi-session work, offer to save all three artifacts to docs/briefs/[topic].md — only after confirmation.

Interaction with Other Skills

• interview-me: sibling entry mode. Diagram-first users skip most of the interview; interview-first users skip parsing. Both converge on the Mission Brief. If the diagram leaves intent unclear, run targeted interview-me questions for just those gaps.
• cloud-platform-foundations: first downstream stop for the design (Ground phase) once the brief is confirmed.
• All Deploy/Secure/Observe skills: consume the brief's route and gap list.
• backup-dr-and-capacity, observability-and-alerting, secrets-management-and-identity: invoked by the gap analysis whenever the diagram omitted them (it usually does).

Common Rationalizations

Rationalization	Reality
"The diagram is clear enough, no need to confirm"	Diagrams omit intent and constraints: no arrow tells you the RPO, the budget, or who can apply changes. The brief still needs explicit confirmation — especially the gaps you inferred.
"The user drew it, so it's what they want"	Users draw the happy path. Backups, secrets, monitoring, and failure domains are almost never drawn — and are always needed. Step 4 is mandatory, not optional.
"It's the current diagram, so it's accurate"	Current-state diagrams drift from reality within weeks of being drawn. Verify against inventory before designing on top.
"Unlabeled arrows don't matter"	An unlabeled edge is an unknown protocol, port, and trust boundary. It's either a question or a flagged assumption — never silently ignored.
"I'll start writing Terraform from the boxes"	Boxes are wishes; the brief is the contract. Convert first, confirm, then design — or you'll codify the user's sketch including its gaps.
"Mermaid/draw.io is just documentation"	In this pack it's a machine-readable requirements source. Parse the source (XML/mmd), not the rendered image — the source has structure the picture loses.

Red Flags

• Parsing the rendered picture instead of the diagram source (XML / Mermaid text)
• A Mission Brief produced without confirming the Step 4 gap list with the user
• Unlabeled edges silently assumed ("probably HTTPS")
• Designing on a "current state" diagram without a drift check against real inventory
• The route skips Ground (architecture design) and jumps straight to Terraform
• No Out of scope line — the diagram shows what to build, never what not to
• Backup/secrets/observability absent from both diagram and brief (the two places they must appear)

Verification

• The diagram source (draw.io XML / Mermaid / structured text) was parsed — not eyeballed from a rendering
• A component inventory exists: compute, data, edge, identity, boundaries, flows, external
• Every unlabeled edge was either answered or explicitly flagged as an assumption
• The gap analysis ran through the full checklist (backups, secrets, observability, CI/CD, HA, TLS, segmentation, IaC, cost)
• The Mission Brief was confirmed explicitly, gaps included, with Out of scope and Recommended route
• For current-state diagrams: a drift check against real inventory is in the route before design work
• Downstream skill invocations follow the brief's Recommended route