---
name: "diagram-workflow"
description: "Create architecture diagrams (C4 Context, C4 Container, AWS Technical Architecture) in Lucid. Use when a DD/SD/TD workflow requires a diagram step, or when the user explicitly requests a diagram."
license: "MIT"
metadata:
  author: "Srinivas K, Mahesvaran S, Srikanth Y, Thirukumaran V, Vignesh V R"
  version: "1.0.0"
---

# Diagram Workflow

## Overview

Shared workflow for creating architecture diagrams in Lucid. Called by DD, SD, and TD workflows at their diagram step, or directly by the user. All diagrams follow the organisation's C4 diagramming standards with specific colour conventions for system lifecycle, design impact, and interactions.

## Prerequisites Checklist

- [ ] Lucid MCP server available
- [ ] Design content from the calling workflow (or user-provided content)
- [ ] Diagramming standards understood (see [Diagramming Standards](references/diagramming-standards.md))

## When to Use

- Called from dd-workflow (C1 Context diagram)
- Called from sd-workflow (C2 Container diagram)
- Called from td-workflow (AWS Technical Architecture diagram)
- User explicitly requests: "Create a diagram for this design"

## Step-by-Step Guide

### Step 1: Determine Diagram Type

| Caller | Diagram Type | Level |
|--------|-------------|-------|
| DD Workflow | C4 Context (C1) | System context with actors and external systems |
| SD Workflow | C4 Container (C2) | Containers, data stores, interactions (includes Tech Stack) |
| TD Workflow | AWS Tech Architecture | AWS services, VPCs, data flows |
| Direct user request | Ask user | Determine from conversation |

---

### Step 2: Extract Diagram Elements

From the design document content, extract elements and classify each one per the diagramming standards.

#### Classification Rules

**System Lifecycle Stage** (determines fill colour):
- Strategic → #c3f7c8 (Pistachio)
- Emerging → #cfe4ff (Sky) — ONLY for components that directly use AI/GenAI technology
- Contained → #fff7a1 (Banana)
- Retiring → #ffd9d9 (Rose)
- External → No fill

**Design Impact** (determines outline colour):
- New → #1071e5 dotted (Sapphire)
- No change → #008a0e solid (Emerald)
- Modify → #fc9432 dotted (Orange)
- Decomm → #e81313 dotted (Red)

**Interaction Type** (determines arrow colour):
- New → #1071e5 solid (Sapphire)
- No change → #008a0e solid (Emerald)
- Modify → #fc9432 solid (Orange)
- Decomm → #e81313 solid (Red)
- Manual → #000000 dotted (Black)

#### C1 Abstraction Level Rules
- C1 diagrams show **Business Applications and Actors** only
- Do NOT include infrastructure components (AWS Cognito, Bedrock, DynamoDB, etc.) in C1
- Technology components belong in C2/TD diagrams only

#### Element Labels
Each system block MUST include:
1. System name
2. Classification + change status in brackets
3. IDP (if applicable)
4. Tech Stack (C2 level only)
5. Short summary
6. PII indicator when applicable

---

### Step 3: Propose Diagram Structure

Present the proposed diagram to the user:

```
Proposed diagram ({type}):

Systems/Components:
- [name] — [lifecycle stage] [design impact] — [summary]
  Fill: [colour], Outline: [colour/style]

Interactions:
- [source] → [target] — [label] — [interaction type]
  Arrow: [colour/style]

Layout:
- Actors: left edge
- Internal systems: centre
- External systems: right edge

Shall I create this diagram in Lucid?
```

Wait for user confirmation or adjustments.

---

### Step 4: Create Diagram in Lucid

Use Lucid MCP tools to create the diagram:

1. Create the document with title: `{artifact-name} - {diagram-type}`
2. Add shapes with correct fill colour, outline colour/style, and labels
3. Add connections with correct arrow colour, line style, and text labels
4. Apply layout (left-to-right flow, actors left, internal centre, external right)

---

### Step 5: Validate and Present

#### Validation Checklist
- [ ] Every system block has correct fill (lifecycle stage) and outline (design impact)
- [ ] Every arrow has correct colour (interaction type) and a text label
- [ ] External systems are visually distinct (no fill)
- [ ] PII clearly indicated where applicable
- [ ] Tech Stack labels included (C2 level only)
- [ ] Arrow direction is caller/producer → callee/consumer
- [ ] Layout follows left-to-right flow guidance

#### Present Result
```
✅ Diagram created: [Lucid document link]

Type: {diagram-type}
Elements: {count} shapes, {count} connections
Standards: Diagramming standards applied

You can edit this directly in Lucid or ask me to make changes.
```

## Troubleshooting

### Issue: Diagram too complex for single page
**Solution:** Suggest splitting into multiple diagram pages.

### Issue: Lucid MCP not available
**Solution:** Inform the user. Offer to describe the diagram in text format instead.

### Issue: AWS diagram — namedShape text renders below icon
**Solution:** Use "rectangle" shapes with AWS service colours, or confirm with the user which approach they prefer.

## Best Practices

- Always propose the diagram structure before creating — don't create without confirmation
- Keep diagrams clean and readable — avoid overcrowding
- Use consistent naming between the design document and diagram labels
- Do NOT change fill colour to express change status — change status is outline-only
- Every arrow MUST include a short text label