Architecture

---
name: architecture
description: Generate system architecture .drawio diagrams — client, service, database, external systems with standard icons and clear connections.
user-invocable: true
argument-hint: "<system description> [--cloud aws|azure|gcp|generic]"
---

# /architecture — Generate Architecture Diagram (draw.io)

## When to use

Visualize system architecture (microservice, layered architecture, network topology) for design docs, ADRs, or stakeholder presentations.

## Input examples

```
/architecture TOPO system: Angular SPA → API Gateway → 3 microservices (Container, Booking, Auth) → SQL Server
/architecture --cloud azure deploy architecture: App Service, Azure SQL, Blob Storage, Front Door
/architecture integration flow with Customs system via REST API
```

## Workflow

### Phase 1 — Identify components & trust boundaries

List components by group:
- **Client**: web app, mobile app, external user (actor)
- **Edge**: load balancer, API gateway, CDN
- **Service**: backend service/microservice (process box)
- **Data**: database, cache, message queue (cylinder/tape)
- **External**: third-party system (cloud shape)

Identify trust boundaries (internet ↔ DMZ ↔ internal) — draw with container boxes `dashed=1;fillColor=none;`.

### Phase 2 — Layout (L3 preview)

Print a block diagram as table/ASCII before generating XML — confirm which groups sit inside which boundaries and the data-flow direction.

### Phase 3 — Generate XML

Use `_templates/architecture.drawio` as the frame:
- Default to **core shapes** (`ellipse+shape=cloud`, `shape=cylinder3`, `shape=umlActor`, `rounded=1`) — opens on any machine.
- If `--cloud aws|azure|gcp`: add matching stencils (`shape=mxgraph.aws4.*`, `shape=mxgraph.azure.*`) and **note clearly in the output** that the user must enable that shape library in draw.io.
- Group by trust boundary with surrounding container boxes.
- Primary data flow left→right or top→bottom, orthogonal arrows.

### Phase 4 — Approval L1 → Write

## Mandatory rules

- Every external system/3rd-party MUST be visually distinct with gray (`fillColor=#f5f5f5;strokeColor=#666666;`).
- Databases always use `shape=cylinder3` — NEVER use a rounded rectangle for storage.
- If there are > 10 components, group by layer/boundary with container boxes for readability instead of leaving all at the same level.
- Small legend in the lower corner if using > 3 color types, explaining each color.

## Output

`docs/diagrams/{feature}/architecture-{slug}.drawio`

## See also

Need real vendor icons (AWS/Azure/GCP, not core shapes), auto-layout for >15 components, draw from real Terraform/K8s/docker-compose, or export PNG/SVG/PDF → use `/diagram` (more powerful, requires draw.io desktop CLI).

## References

- @.claude/rules/drawio-conventions.md
- @.claude/rules/naming-conventions.md
- @.claude/rules/approval-gate.md
- @_templates/architecture.drawio
- Brain: `DRAWIO-BRAIN.md`