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/03-boundaries.md
View on GitHub# Phase 3: Boundaries
**Goal:** Define the ports (interfaces), adapters (implementations), and architectural layers.
## Prerequisites
- Phase 1 Discovery completed
- Phase 2 Domain Model defined
## Hexagonal Architecture Refresher
```
┌─────────────────────────────────────┐
│ DRIVING SIDE │
│ (things that USE the system) │
└─────────────────────────────────────┘
│
Inbound Ports
│
▼
┌─────────────┐ ┌─────────────────────┐ ┌─────────────┐
│ Driving │────────▶│ │◀────────│ Driven │
│ Adapters │ │ APPLICATION │ │ Adapters │
│ (Primary) │ │ CORE │ │ (Secondary) │
│ │ │ │ │ │
│ - REST API │ │ - Use Cases │ │ - Database │
│ - CLI │ │ - Domain Model │ │ - External │
│ - GraphQL │ │ - Business Rules │ │ APIs │
│ - Events │ │ │ │ - File Sys │
└─────────────┘ └─────────────────────┘ └─────────────┘
│
Outbound Ports
│
▼
┌─────────────────────────────────────┐
│ DRIVEN SIDE │
│ (things the system USES) │
└─────────────────────────────────────┘
```
## Entry Questions
### 1. Inbound Ports (How is the system used?)
- "How will users interact with this system?"
- "What are ALL the entry points?" (API, CLI, scheduled jobs, events)
- "Are there different interfaces for different user types?"
### 2. Outbound Ports (What does the system need?)
- "What external systems does this depend on?"
- "What data needs to be persisted?"
- "What notifications/events need to be sent?"
### 3. Layer Decisions
- "What belongs in the domain layer vs application layer?"
- "Where should validation live?"
- "Where does authorization happen?"
## Port Identification Checklist
### Inbound Ports (Primary/Driving)
| Port Type | Questions to Ask |
|-----------|------------------|
| HTTP/REST | What endpoints? What payloads? |
| CLI | What commands? What arguments? |
| Event Consumer | What events? From where? |
| Scheduled Jobs | What triggers? What frequency? |
| WebSocket | What real-time interactions? |
### Outbound Ports (Secondary/Driven)
| Port Type | Questions to Ask |
|-----------|------------------|
| Repository | What entities need persistence? Query patterns? |
| External API | What services? What's the contract? |
| Event Publisher | What events? Who consumes them? |
| File Storage | What files? What operations? |
| Notification | What channels? What triggers? |
## Defining Port Interfaces
For each port, define:
```typescript
// Example: Inbound Port (driving)
interface CreateOrderUseCase {
execute(command: CreateOrderCommand): Promise<OrderCreatedResult>;
}
// Example: Outbound Port (driven)
interface OrderRepository {
save(order: Order): Promise<void>;
findById(id: OrderId): Promise<Order | null>;
findByCustomer(customerId: CustomerId): Promise<Order[]>;
}
```
## Adapter Planning
For each port, plan the adapter:
| Port | Adapter | Implementation Notes |
|------|---------|---------------------|
| `OrderRepository` | `PostgresOrderRepository` | Uses Drizzle ORM |
| `CreateOrderUseCase` | `CreateOrderController` | REST POST /orders |
| `PaymentGateway` | `StripePaymentAdapter` | Stripe SDK |
## Probing Questions
| If they say... | Ask... |
|----------------|--------|
| "The API calls the database" | "What abstraction sits between them?" |
| "We'll use [Framework X]" | "What interface does your domain see?" |
| "It needs to be flexible" | "What specifically needs to change without rewriting core?" |
## Red Flags
- **Tight coupling** - domain knows about frameworks/infrastructure
- **Missing ports** - direct dependencies on external systems
- **Fat adapters** - business logic in adapters instead of domain
- **Leaky abstractions** - port interfaces expose implementation details
## Boundaries Output
Before moving to Phase 4:
```markdown
## Inbound Ports
| Port Name | Purpose | Methods |
|-----------|---------|---------|
## Outbound Ports
| Port Name | Purpose | Methods |
|-----------|---------|---------|
## Planned Adapters
| Port | Adapter | Technology |
|------|---------|------------|
## Layer Structure
- domain/: [What goes here]
- application/: [What goes here]
- infrastructure/: [What goes here]
- interfaces/: [What goes here]
## Dependency Rule Verification
[Confirm that dependencies point inward]
```
## Transition to Phase 4
When boundaries are defined:
1. Present the hexagonal diagram with actual ports/adapters
2. Verify dependency direction (always inward)
3. Confirm adapter technology choices
4. Ask: "Ready to generate the scaffold?"
Then: `read ./workflows/04-scaffolding.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 |