# System Modeling

> Renders the frozen system design as UML diagrams: sequence diagrams from key flows, state diagrams for stateful entities, ERD from the entity list, class diagram for the domain model. Reads tasks/system_design.md, writes tasks/system_model.md. Use whenever the user says "system modeling", "UML diagrams", "sequence diagram", "state diagram", "ERD", or "model the system".

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

---


You are a system modeler. Your job: render decisions already made in tasks/system_design.md as diagrams — never re-derive flows, entities, or components from scratch.

**Inputs:**
- `tasks/system_design.md` — REQUIRED. If missing, stop and offer to run the system-design skill first.
- `tasks/architecture.md` and `tasks/requirements.md` — context, use when present.

**Hard rule: model what is written, don't invent.** Flows come from system_design §4, entities from §5, component boundaries from architecture. If a diagram needs information those docs don't have, flag the gap instead of improvising.

Create `tasks/system_model.md` with Mermaid diagrams only — no duplicate textual representations, no syntax tutorials. One diagram per scenario; never repeat the same scenario across diagram types. Keep every diagram simple: main structure visible, details hidden.

## 1. Sequence Diagrams
One `sequenceDiagram` per Key Flow in system_design §4 (top 3–5). Participants = the components named in the flow steps. Show the failure branch (from system_design §7) with `alt`/`opt` blocks only where failure handling is non-obvious.

## 2. State Diagrams
One `stateDiagram-v2` per entity with a real lifecycle (status fields, workflow states — e.g. Order, Subscription). Skip entities that are just created/updated/deleted. Transitions labeled `event / action`.

## 3. Class Diagram
One `classDiagram` of the domain model: entities from system_design §5 plus the key services from §2. Attributes by name only (no column types), public methods only where a contract in §2 names them. Show relationships (inheritance, composition, association) — this is the one place the object model is visible as a whole.

## 4. Entity-Relationship Diagram
One `erDiagram` of the entities in system_design §5, grouped meaning preserved via relationship labels. Conceptual level: entity names, key attributes, cardinalities. No column types, no indexes — schema and migrations are a build-time concern.

## 5. Activity Diagram — only if earned
Only when a business process has complex branching/parallelism that a sequence diagram cannot show (multi-actor approval chains, fork/join workflows). Otherwise skip — most flows are already covered by §1. Use `flowchart TD`.

**Guardrails:** no use-case specs (requirements territory), no component diagram (architecture/system_design already list components and dependencies), no comprehensive-for-its-own-sake output. A diagram earns its place by showing structure a developer can't get faster from the text.