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/04-scaffolding.md
View on GitHub# Phase 4: Scaffolding
**Goal:** Generate a TypeScript project structure implementing the architectural decisions.
## Prerequisites
- Phase 1 Discovery completed
- Phase 2 Domain Model defined
- Phase 3 Boundaries defined
- ADR drafted (or in progress)
## Pre-Scaffold Checklist
Before generating any code, confirm:
```
[ ] Problem statement is clear
[ ] Domain model is approved
[ ] All ports are identified
[ ] Adapter technologies are chosen
[ ] Layer structure is decided
[ ] Naming conventions agreed
```
## Scaffold Structure
Generate this folder structure:
```
src/
├── domain/ # Pure business logic, no dependencies
│ ├── entities/ # Domain entities and aggregate roots
│ │ └── [Entity].ts
│ ├── value-objects/ # Immutable value types
│ │ └── [ValueObject].ts
│ ├── events/ # Domain events
│ │ └── [Event].ts
│ └── errors/ # Domain-specific errors
│ └── [Error].ts
│
├── application/ # Use cases, orchestration
│ ├── ports/ # Interface definitions
│ │ ├── inbound/ # Primary/driving ports
│ │ │ └── [UseCase].ts
│ │ └── outbound/ # Secondary/driven ports
│ │ └── [Repository].ts
│ ├── use-cases/ # Use case implementations
│ │ └── [UseCase].ts
│ └── services/ # Application services
│ └── [Service].ts
│
├── infrastructure/ # External world implementations
│ ├── persistence/ # Database adapters
│ │ └── [Repository]Impl.ts
│ ├── external/ # External API adapters
│ │ └── [Gateway]Impl.ts
│ └── config/ # Configuration
│ └── index.ts
│
├── interfaces/ # Entry points (driving adapters)
│ ├── http/ # REST/HTTP controllers
│ │ ├── routes/
│ │ └── controllers/
│ ├── cli/ # CLI commands (if applicable)
│ └── events/ # Event handlers (if applicable)
│
└── shared/ # Shared utilities
├── types/ # Shared type definitions
└── utils/ # Pure utility functions
```
## File Generation Order
Generate files in this order to maintain valid TypeScript:
1. **Value Objects** - No dependencies
2. **Entities** - Depend on value objects
3. **Domain Events** - Depend on entities
4. **Outbound Ports** - Interface definitions
5. **Inbound Ports** - Use case interfaces
6. **Use Cases** - Implement inbound, use outbound
7. **Adapters** - Implement outbound ports
8. **Controllers** - Use inbound ports
## Template References
Use these templates when generating:
| Component | Template |
|-----------|----------|
| Entity | `read ../templates/entity-template.md` |
| Value Object | `read ../templates/value-object-template.md` |
| Port Interface | `read ../templates/port-adapter-interface.md` |
| Use Case | `read ../templates/use-case-template.md` |
| Repository | `read ../templates/repository-template.md` |
| Controller | `read ../templates/controller-template.md` |
## Scaffold Questions
Before generating each component, ask:
| Component | Ask |
|-----------|-----|
| Entity | "What's the identity? What mutations are allowed?" |
| Value Object | "What makes two instances equal?" |
| Repository | "What queries are needed beyond CRUD?" |
| Use Case | "What are the error cases?" |
| Controller | "What's the HTTP method and path?" |
## Generated File Checklist
For each generated file, ensure:
- [ ] Single responsibility
- [ ] Dependencies only point inward
- [ ] Interfaces over implementations
- [ ] Error handling defined
- [ ] TypeScript strict mode compatible
## Post-Scaffold Tasks
After generating the scaffold:
1. **Dependency verification**
```
domain/ → (no imports from other layers)
application/ → domain/
infrastructure/ → application/, domain/
interfaces/ → application/, domain/
```
2. **Create index files** for clean imports
3. **Add placeholder tests** for each use case
4. **Generate ADR** documenting the architecture
## ADR Generation
Finalize the Architecture Decision Record:
```markdown
# ADR-001: [System Name] Architecture
## Status
Accepted
## Context
[Problem from Phase 1]
## Decision
[Architectural decisions from Phases 2-3]
## Consequences
### Positive
- [Benefits]
### Negative
- [Tradeoffs]
### Risks
- [What could go wrong]
```
Template: `read ../templates/adr-template.md`
## Completion Checklist
Before declaring the scaffold complete:
```
[ ] All folders created
[ ] All port interfaces defined
[ ] All entity skeletons created
[ ] All use case stubs created
[ ] Dependency rule verified
[ ] ADR generated
[ ] User has reviewed and approved
```
## Next Steps for User
After scaffolding, suggest:
1. "Start implementing the core use case first"
2. "Write tests for domain logic before infrastructure"
3. "Implement one full vertical slice end-to-end"
4. "Then expand to remaining features"
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 |