# Architecture Diagrams

> Interactive, visual architecture and sequence diagrams as code. Generates beautiful, self-contained SVG/HTML diagrams with motion, clear component boundaries, and verifiable data flows.

- Skill: `kok-o/architecture-diagrams` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kok-o/architecture-diagrams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kok-o/architecture-diagrams/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kok-o (https://skillmd.com/u/kok-o)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kok-o/architecture-diagrams

---

# architecture-diagrams

## Overview

Visual architecture engineering skill inspired by [tt-a1i/archify](https://github.com/tt-a1i/archify). Replaces static ASCII art and rigid default diagrams with crisp, self-contained SVG and responsive HTML diagrams featuring modern dark-mode palettes, pulse animations for event flows, and strict C4-model component boundaries.

## When to Use

Activate whenever:

- Designing or explaining distributed systems, microservices, or full-stack architectures.
- Visualizing complex auth flows (OAuth2, PKCE), multi-step payment sagas, or CDC outbox data pipelines.
- User requests an architecture diagram, flow chart, sequence diagram, or visual system design.

## Rules & Patterns

### 1. Diagram Types Supported

1. **System Landscape / C4 Container Diagram**:
   - Clients (Web, Mobile, Third-party) → API Gateway / CDN → Microservices / Serverless → Storage / Event Brokers.
2. **Sequence Flow Diagram**:
   - Step-by-step lifecycles with synchronous requests, asynchronous pub/sub events, and compensating transactions.
3. **Data Pipeline & Event-Driven Topology**:
   - Primary DB → Transactional Outbox → CDC (Debezium) → Kafka Topic → Consumers → Materialized Views.

### 2. Aesthetic & Visual Invariants

- **Dark Theme by Default**: Surface `#0B0F19`, containers `#1E293B`, borders `#334155`, text `#F8FAFC`.
- **Semantic Component Accents**:
  - Client / Frontend: Sky Blue (`#38BDF8`)
  - API Gateway / Router: Indigo (`#818CF8`)
  - Business Services: Emerald Green (`#34D399`)
  - Databases / Storage: Amber / Orange (`#F59E0B`)
  - Message Brokers / Event Buses: Purple (`#A855F7`)
- **Active Data-Flow Motion**: Use subtle CSS `@keyframes` on SVG stroke dashes (`stroke-dasharray`, `stroke-dashoffset`) to show active direction of messages and data streams.

---

## Code Examples

### Standalone Animated SVG Data-Flow Pattern

```html
<svg viewBox="0 0 800 200" xmlns="http://www.w3.org/2000/svg" class="bg-slate-950 rounded-xl p-4 w-full">
  <defs>
    <style>
      .flow-line { stroke: #38BDF8; stroke-width: 2; stroke-dasharray: 6,6; animation: flow 1.5s linear infinite; }
      @keyframes flow { to { stroke-dashoffset: -12; } }
      .box { fill: #1E293B; stroke: #334155; stroke-width: 1.5; rx: 8; }
      .text-title { fill: #F8FAFC; font-family: sans-serif; font-size: 14px; font-weight: 600; }
      .text-sub { fill: #94A3B8; font-family: monospace; font-size: 11px; }
    </style>
  </defs>

  <!-- Client Node -->
  <rect x="30" y="70" width="160" height="60" class="box" />
  <text x="110" y="96" text-anchor="middle" class="text-title">Next.js Client</text>
  <text x="110" y="114" text-anchor="middle" class="text-sub">React 19 / RSC</text>

  <!-- Data Flow -->
  <line x1="190" y1="100" x2="330" y2="100" class="flow-line" />

  <!-- API Gateway -->
  <rect x="330" y="70" width="160" height="60" class="box" />
  <text x="410" y="96" text-anchor="middle" class="text-title">API Gateway</text>
  <text x="410" y="114" text-anchor="middle" class="text-sub">Auth & Rate Limiting</text>

  <!-- Flow to Database -->
  <line x1="490" y1="100" x2="630" y2="100" class="flow-line" />

  <!-- Database -->
  <rect x="630" y="70" width="140" height="60" class="box" />
  <text x="700" y="96" text-anchor="middle" class="text-title">PostgreSQL</text>
  <text x="700" y="114" text-anchor="middle" class="text-sub">Prisma / Outbox</text>
</svg>
```

---

## Validation Checklist

- [ ] Diagram clearly identifies all component boundaries, ports, and protocols.
- [ ] Visual hierarchy is unambiguous (clients on left/top, storage on right/bottom).
- [ ] Motion/animation is purposeful and lightweight (no heavy canvas frameworks).
- [ ] Accessible: nodes include semantic labels and readable color contrast.

---

## Common Mistakes

- **Messy cross-overs**: Laying out 20 boxes with overlapping lines instead of grouping into clean C4 layers.
- **Unlabeled connections**: Lines without protocol (HTTPS, gRPC, WSS) or event payload descriptions.
- **Overwhelming detail**: Drawing internal class diagrams when the user asked for a system-level overview.

---

## Integration Notes

- Triggers during `system-design` and `microservices` planning phases.
- Used to generate visual architecture artifacts in Markdown walkthroughs and specs.
- Pairs with `ui-ux-pro` for consistent aesthetic styling.