aiskillstore/marketplace / skills/aaronabuusama/system-design
system-design
VerifiedCTO's deputy for software architecture using Clean/Hexagonal Architecture principles. Socratic approach - asks probing questions to help YOU make informed design decisions. Guides through Discovery → Modeling → Boundaries → Scaffolding phases. Outputs TypeScript scaffolds with ports, adapters, and domain layers. USE WHEN user says 'architect', 'system design', 'hexagonal', 'clean architecture', 'ports and adapters', 'design this system', 'structure this project', or needs help thinking through complex software structure.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/clean-architecture.md | markdown | 6.6 KB |
| references/common-mistakes.md | markdown | 8.4 KB |
| references/dependency-inversion.md | markdown | 7.1 KB |
| references/domain-modeling.md | markdown | 6.9 KB |
| references/hexagonal-architecture.md | markdown | 7.5 KB |
| skill-report.json | config | 159.4 KB |
| templates/adr-template.md | markdown | 6.2 KB |
| templates/controller-template.md | markdown | 10.2 KB |
| templates/entity-template.md | markdown | 8.5 KB |
| templates/port-adapter-interface.md | markdown | 7.8 KB |
| templates/repository-template.md | markdown | 10.0 KB |
| templates/ts-hexagonal-scaffold.md | markdown | 5.9 KB |
| templates/use-case-template.md | markdown | 8.5 KB |
| templates/value-object-template.md | markdown | 9.0 KB |
| workflows/01-discovery.md | markdown | 2.4 KB |
| workflows/02-modeling.md | markdown | 3.3 KB |
| workflows/03-boundaries.md | markdown | 5.8 KB |
| workflows/04-scaffolding.md | markdown | 5.2 KB |
workflows/02-modeling.md
View on GitHub# Phase 2: Domain Modeling
**Goal:** Identify the core concepts, their relationships, and the ubiquitous language.
## Prerequisites
- Phase 1 Discovery completed
- Problem statement and actors defined
## Entry Questions
### 1. Core Concepts
- "What are the main 'things' in this domain?"
- "If you had to explain this to a new team member, what nouns would you use?"
- "What's the most important entity? The one everything else relates to?"
### 2. Relationships
- "How do these concepts relate to each other?"
- "Which relationships are required vs optional?"
- "Are there any many-to-many relationships?" (complexity signal)
### 3. Behaviors
- "What actions can be performed on/by each entity?"
- "What changes state in this system?"
- "What are the key workflows/processes?"
### 4. Invariants
- "What rules must ALWAYS be true?"
- "What would be a 'corrupted' state?"
- "What constraints does the business enforce?"
## Domain Modeling Techniques
### Entity Extraction
Listen for nouns in user descriptions. Candidates for entities:
- Have identity (unique identifier)
- Have lifecycle (created, modified, deleted)
- Are referenced by other concepts
### Value Object Identification
Concepts that:
- Are defined by their attributes, not identity
- Are immutable
- Examples: Money, Address, DateRange, Email
### Aggregate Boundaries
Ask: "If I delete [X], what else must be deleted with it?"
- Things deleted together = same aggregate
- Things that can exist independently = separate aggregates
## Mermaid Diagram Output
Generate a domain model diagram:
```mermaid
erDiagram
ENTITY_A ||--o{ ENTITY_B : "relationship"
ENTITY_A {
string id PK
string name
datetime createdAt
}
ENTITY_B {
string id PK
string entityAId FK
string status
}
```
## Ubiquitous Language
Build a glossary as you model:
| Term | Definition | Example |
|------|------------|---------|
| [Domain Term] | [What it means in THIS context] | [Concrete example] |
**Critical:** Use the same terms everywhere - code, docs, conversations.
## Probing Questions
| If they describe... | Ask... |
|--------------------|--------|
| A complex entity | "Can this be broken into smaller concepts?" |
| Overlapping concepts | "Are these the same thing with different names?" |
| Vague relationships | "Is this 1:1, 1:many, or many:many?" |
| Missing behaviors | "Who/what triggers this change?" |
## Red Flags
- **God entities** - one entity that everything relates to
- **Anemic domain** - entities with no behaviors
- **Leaky abstractions** - technical terms in domain model (e.g., "DatabaseRecord")
- **Missing aggregates** - no clear boundaries
## Modeling Outputs
Before moving to Phase 3:
```markdown
## Core Entities
- [Entity]: [Purpose]
## Value Objects
- [ValueObject]: [What it represents]
## Aggregates
- [Aggregate Root]: [Entities it contains]
## Key Relationships
- [Entity A] → [Entity B]: [Nature of relationship]
## Invariants/Business Rules
- [Rule 1]
- [Rule 2]
## Ubiquitous Language
| Term | Definition |
|------|------------|
```
## Transition to Phase 3
When modeling is complete:
1. Present the domain model diagram
2. Walk through each aggregate
3. Confirm ubiquitous language
4. Ask: "Ready to define the system boundaries?"
Then: `read ./workflows/03-boundaries.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |