system-design

System Design Through EventStorming

Overview

Transform requirements into navigable design catalogs using EventStorming methodology and Mermaid diagrams.

Core principle: Progressive elaboration through event-driven thinking, producing token-efficient visual artifacts in standardized catalog structure.

Announce at start: "I'm using the system-design skill to create a design catalog for your system."

When to Use

Use when:

• User wants to design a new system
• Requirements exist but design doesn't
• Need structured thinking before implementation
• Team needs shared visual artifacts

Don't use when:

• Adding features to existing system (consider brainstorming instead)
• Implementation already started
• User wants code, not design

Quick Reference

Phase	Key Activities	Output Files
1. Requirements	Ask questions, identify actors/constraints	requirements.md
2. Big Picture	EventStorming timeline with events/commands	big-picture.mmd
3. Processes	Zoom into critical processes, add aggregates	process-{name}.mmd
4. Data & Flows	ERD, state charts, sequences	erd.mmd, state-{entity}.mmd, sequence-{flow}.mmd
5. Integration	Generate catalog README	README.md

The Iron Laws

Law 1: ASK QUESTIONS - No Assumptions

NEVER make "industry-standard assumptions" without asking the user first.

• Ask about actors, constraints, scale, budget, timeline
• Use AskUserQuestion tool for architectural choices
• Mark unclear areas as hotspots instead of assuming

Bad:

❌ "I'll assume standard PostgreSQL for data storage"
❌ "Proceeding with industry-standard assumptions"
❌ "I'll design for moderate scale (10K users)"

Good:

✅ "What database are you currently using?" (AskUserQuestion with options)
✅ "What scale are you targeting?" (AskUserQuestion: 100 users / 10K / 100K+)
✅ "Budget constraints for infrastructure?" (Ask directly)

Law 2: MERMAID ONLY - No ASCII Diagrams

All diagrams MUST use Mermaid format. NO exceptions.

• No ASCII art
• No text-based diagrams
• No "version control friendly" excuses for avoiding Mermaid

Bad:

❌ ASCII art entity relationships
❌ Text-based flowcharts
❌ "I'll create ASCII diagrams because they're universal"

Good:

✅ Mermaid ER diagrams
✅ Mermaid flowcharts
✅ Mermaid sequence diagrams
✅ Mermaid state charts

Law 3: EVENTSTORMING - Event-Driven Thinking

Use EventStorming methodology for Phases 2-3. Required.

• Identify domain events (what happens in the system)
• Add commands (what triggers events)
• Add actors (who initiates)
• Add systems (external integrations)
• Mark hotspots (unclear/risky areas)

Bad:

❌ "Using traditional waterfall analysis"
❌ "Creating use cases and functional specs"
❌ "Based on proven patterns" (without events)

Good:

✅ "Let's identify key business events" (EventStorming)
✅ "What triggers each event?" (Commands)
✅ "What data changes when this event happens?" (Aggregates)

Law 4: CATALOG STRUCTURE - Standardized Organization

All artifacts go into docs/design-catalog/ with specific structure.

docs/design-catalog/
  README.md              # Navigation hub
  requirements.md
  big-picture.mmd
  processes/
    process-{name}.mmd
  data/
    erd.mmd
    state-{entity}.mmd
  flows/
    sequence-{flow}.mmd

No random file names. No mixed concerns.

Law 5: DESIGN NOT IMPLEMENTATION

Stay at design abstraction. NO implementation details in design phase.

Forbidden in design artifacts:

• ❌ Database schemas (SQL, migrations)
• ❌ Deployment guides (Docker, Kubernetes)
• ❌ CI/CD pipelines
• ❌ Specific technology choices (unless user specified)
• ❌ Implementation timelines (16-week plans)
• ❌ Team structure recommendations
• ❌ Code examples (API endpoints, controllers, services, functions)
• ❌ Configuration files (YAML, JSON, ENV)

Allowed:

• ✅ Entity relationships (conceptual)
• ✅ State transitions (conceptual)
• ✅ Event flows (conceptual)
• ✅ Integration points (generic)
• ✅ Hotspots for technical decisions

Law 6: TOKEN EFFICIENCY - Diagrams Over Prose

Prefer Mermaid diagrams over lengthy text descriptions.

Token targets by project complexity:

• Simple (single service, 5-10 entities): < 10K tokens
• Medium (2-3 services, 10-20 entities): < 20K tokens
• Complex (multiple services, 20+ entities): < 35K tokens

If exceeding targets, check:

• Are you writing prose that diagrams could show?
• Are you repeating information across files?
• Are you including implementation details?

Bad:

❌ 4,000 lines of documentation
❌ Verbose explanations of every decision
❌ Repeating information across files
❌ "This is complex so 50K tokens is reasonable"

Good:

✅ Mermaid diagram with annotations
✅ Cross-reference: "See big-picture.mmd for event flow"
✅ Tables for entity attributes
✅ Minimal prose, maximum visual clarity

The 5 Phases

REQUIRED: Use TodoWrite to track phase progress.

Copy this checklist:

System Design Progress:
- [ ] Phase 1: Requirements (actors, constraints, goals identified)
- [ ] Phase 2: Big Picture (EventStorming timeline created)
- [ ] Phase 3: Processes (Critical processes detailed)
- [ ] Phase 4: Data & Flows (ERD, state charts, sequences created)
- [ ] Phase 5: Integration (Catalog assembled, next steps planned)

Phase 1: Requirements Understanding

Goal: Understand context before designing

Activities:

1. Ask questions ONE at a time (following brainstorming pattern)
2. Use AskUserQuestion for architectural choices with trade-offs
3. Identify: business goals, constraints, key actors, success criteria

Questions to ask:

• "What problem does this system solve?"
• "Who are the primary users/actors?"
• "What are the critical constraints?" (performance, scale, budget, timeline)
• "How do you define success?"
• "What systems need to integrate?"

Output: Create docs/design-catalog/requirements.md

Validation: Present requirements summary, ask: "Does this capture the scope?"

Phase 2: EventStorming Big Picture

Goal: Understand business process through events

Announce: "Let's explore the business process through EventStorming."

Activities:

1. Ask: "What are the key business events that happen in this system?"
2. Build timeline collaboratively (add events as user describes)
3. Ask: "Who triggers each event? What commands cause them?"
4. Add actors and commands
5. Ask: "Are there external systems involved?"
6. Add external systems
7. Mark hotspots for unclear areas (DON'T assume, MARK AS HOTSPOT)

EventStorming Color Conventions (Mermaid):

flowchart LR
    %% Style definitions
    classDef event fill:#ff9800,stroke:#e65100,color:#000
    classDef command fill:#2196f3,stroke:#0d47a1,color:#fff
    classDef actor fill:#ffeb3b,stroke:#f57f17,color:#000
    classDef system fill:#9c27b0,stroke:#4a148c,color:#fff
    classDef aggregate fill:#4caf50,stroke:#1b5e20,color:#fff
    classDef hotspot fill:#f44336,stroke:#b71c1c,color:#fff

    Actor[Customer]:::actor
    Cmd1[Place Order]:::command
    Evt1[Order Placed]:::event
    Agg1[Order]:::aggregate
    Sys1[Payment Gateway]:::system
    Hot1[? Refund policy unclear]:::hotspot

    Actor --> Cmd1
    Cmd1 --> Evt1
    Evt1 --> Agg1
    Agg1 --> Sys1
    Evt1 -.question.- Hot1

Output: Create docs/design-catalog/big-picture.mmd

Validation: Present diagram, ask: "Does this capture the high-level flow?"

Phase 3: Process EventStorming

Goal: Detail specific processes from big picture

Activities:

1. Identify 2-4 critical processes to detail (not more)
2. For each process:
   • Ask: "Let's detail the {process name} process"
   • Ask: "What aggregates (data entities) are involved?"
   • Ask: "What state changes happen at each event?"
   • Build detailed process diagram with color coding

Criteria for "critical" processes:

• Touches multiple aggregates
• Has complex business rules
• High business value or risk
• User specifically mentioned as important

Output: Create docs/design-catalog/processes/process-{name}.mmd (one per process)

Validation: Review each process diagram before moving to next

Phase 4: System Design Artifacts

Goal: Model data, state, and interactions

4.1 Entity-Relationship Diagram

• Extract entities from process diagrams
• Ask: "What are the relationships between these entities?"
• Define attributes (but NOT database schema)
• Use Mermaid ER diagram syntax

Output: docs/design-catalog/data/erd.mmd

4.2 State Charts

• Identify entities with complex lifecycles
• Ask: "Which entities have important state transitions?"
• Map states, transitions, triggers
• Annotate data changes per transition
• Use Mermaid stateDiagram-v2
• Limit: 2-4 entities max (only entities with complex lifecycles)

Output: docs/design-catalog/data/state-{entity}.mmd (one per entity)

4.3 Sequence Diagrams

• Ask: "Which flows need detailed interaction modeling?"
• Select critical/complex flows
• Map actor/system interactions
• Show success AND error paths
• Use Mermaid sequenceDiagram
• Limit: 2-4 flows max (only critical/complex flows)

Output: docs/design-catalog/flows/sequence-{flow}.mmd (one per flow)

Don't diagram everything - focus on what adds clarity.

Validation: Present all artifacts, ask: "Does this design feel complete?"

Phase 5: Integration & Next Steps

Goal: Assemble catalog and plan next actions

Activities:

1. Generate catalog README with:
   • Project overview
   • Links to all artifacts
   • EMBED ALL DIAGRAMS (copy full Mermaid content from each .mmd file)
   • Navigation to processes, states, flows
   • All diagrams must be visible in README for easy preview
2. Present complete design catalog
3. Ask: "Ready to proceed with implementation planning?"

**C

---

Content truncated.