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 |
references/clean-architecture.md
View on GitHub# Clean Architecture
## Core Principle
**The Dependency Rule:** Source code dependencies must point only inward, toward higher-level policies.
```
┌─────────────────────────────────────────────────────────────┐
│ Frameworks & Drivers │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Interface Adapters │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Application Business Rules │ │ │
│ │ │ ┌─────────────────────────────────────┐ │ │ │
│ │ │ │ Enterprise Business Rules │ │ │ │
│ │ │ │ (Entities) │ │ │ │
│ │ │ └─────────────────────────────────────┘ │ │ │
│ │ │ (Use Cases) │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ (Controllers, Gateways, Presenters) │ │
│ └─────────────────────────────────────────────────────┘ │
│ (Web, DB, Devices, UI, External) │
└─────────────────────────────────────────────────────────────┘
```
## The Four Layers
### 1. Entities (Enterprise Business Rules)
The innermost circle. Contains:
- Business objects with critical business rules
- Could be used by many applications in the enterprise
- Least likely to change when something external changes
```typescript
// Entity example
class Order {
private readonly items: OrderItem[];
private status: OrderStatus;
// Business rule: orders can only be cancelled if not shipped
cancel(): void {
if (this.status === OrderStatus.Shipped) {
throw new OrderCannotBeCancelledError();
}
this.status = OrderStatus.Cancelled;
}
// Business rule: total includes tax
get total(): Money {
return this.items
.reduce((sum, item) => sum.add(item.subtotal), Money.zero())
.withTax(this.taxRate);
}
}
```
### 2. Use Cases (Application Business Rules)
Contains application-specific business rules:
- Orchestrate flow of data to/from entities
- Direct entities to use their business rules
- Encapsulate all use cases of the system
```typescript
// Use case example
class PlaceOrderUseCase {
constructor(
private orderRepository: OrderRepository,
private inventoryService: InventoryService,
private paymentGateway: PaymentGateway
) {}
async execute(command: PlaceOrderCommand): Promise<PlaceOrderResult> {
// 1. Validate inventory
await this.inventoryService.reserve(command.items);
// 2. Process payment
const payment = await this.paymentGateway.charge(command.payment);
// 3. Create order (entity does validation)
const order = Order.create(command.items, payment);
// 4. Persist
await this.orderRepository.save(order);
return { orderId: order.id };
}
}
```
### 3. Interface Adapters
Convert data between use cases/entities and external formats:
- Controllers (handle incoming requests)
- Presenters (format outgoing responses)
- Gateways (abstract external services)
```typescript
// Controller example
class OrderController {
constructor(private placeOrder: PlaceOrderUseCase) {}
async handlePost(req: Request): Promise<Response> {
// Convert HTTP request to use case command
const command = this.parseRequest(req);
// Execute use case
const result = await this.placeOrder.execute(command);
// Convert result to HTTP response
return this.formatResponse(result);
}
}
```
### 4. Frameworks & Drivers
The outermost layer:
- Database implementations
- Web frameworks
- UI frameworks
- External services
**Key insight:** This layer is where all the details go. The web is a detail. The database is a detail.
## Crossing Boundaries
Data crosses boundaries via simple data structures:
- DTOs (Data Transfer Objects)
- Request/Response models
**Never pass entity objects across boundaries.** Convert to DTOs.
```typescript
// Crossing boundary example
interface OrderDTO {
id: string;
items: ItemDTO[];
total: number;
status: string;
}
class OrderPresenter {
present(order: Order): OrderDTO {
return {
id: order.id.value,
items: order.items.map(this.presentItem),
total: order.total.amount,
status: order.status.toString()
};
}
}
```
## What Belongs Where
| Layer | Contains | Depends On |
|-------|----------|------------|
| Entities | Domain models, business rules | Nothing |
| Use Cases | Application workflows, orchestration | Entities |
| Adapters | Controllers, repositories, gateways | Use Cases, Entities |
| Frameworks | Implementations, configuration | All inner layers |
## Testing Benefits
Clean Architecture makes testing straightforward:
| Layer | Test Type | Mocking |
|-------|-----------|---------|
| Entities | Unit | None needed |
| Use Cases | Unit | Mock ports |
| Adapters | Integration | Mock external services |
| Frameworks | E2E | Full system |
## Common Violations
1. **Entity depends on framework**
- Bad: Entity uses ORM decorators
- Good: Entity is pure, repository handles mapping
2. **Use case knows about HTTP**
- Bad: Use case returns Response object
- Good: Use case returns domain result, controller formats
3. **Business logic in controller**
- Bad: Controller has if/else business rules
- Good: Controller delegates to use case
4. **Database leaking into domain**
- Bad: Entity has `@Column()` decorator
- Good: Entity is pure, mapper handles DB
## Key Insight
> "The center of your application is not the database. Nor is it one or more of the frameworks you may be using. The center of your application is the use cases of your application."
> — Robert C. Martin
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 |