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 |
templates/use-case-template.md
View on GitHub# Use Case Template
## Structure
```typescript
// src/application/use-cases/[UseCaseName]/[UseCaseName].ts
import type { [Entity] } from '../../../domain';
import type { [Repository] } from '../../ports/outbound';
// 1. Command (input)
export interface [UseCaseName]Command {
readonly /* input fields */;
}
// 2. Result (success output)
export interface [UseCaseName]Result {
readonly /* output fields */;
}
// 3. Error (failure cases)
export type [UseCaseName]Error =
| { type: 'ERROR_TYPE_1'; /* context */ }
| { type: 'ERROR_TYPE_2'; /* context */ };
// 4. Port interface (optional - can be in ports/inbound/)
export interface [UseCaseName]UseCase {
execute(command: [UseCaseName]Command): Promise<[UseCaseName]Result | [UseCaseName]Error>;
}
// 5. Implementation
export class [UseCaseName]Impl implements [UseCaseName]UseCase {
constructor(
private readonly /* injected ports */
) {}
async execute(command: [UseCaseName]Command): Promise<[UseCaseName]Result | [UseCaseName]Error> {
// 1. Validate command
// 2. Load required entities
// 3. Execute domain logic
// 4. Persist changes
// 5. Publish events
// 6. Return result
}
}
```
## Complete Example: PlaceOrder
```typescript
// src/application/use-cases/PlaceOrder/PlaceOrder.ts
import { Order, OrderId } from '../../../domain/entities';
import { Money } from '../../../domain/value-objects';
import type { OrderRepository, CustomerRepository, InventoryService, PaymentGateway, EventPublisher } from '../../ports/outbound';
// Command
export interface PlaceOrderCommand {
readonly customerId: string;
readonly items: ReadonlyArray<{
readonly productId: string;
readonly quantity: number;
}>;
readonly paymentMethodId: string;
}
// Result
export interface PlaceOrderResult {
readonly orderId: string;
readonly total: number;
readonly currency: string;
}
// Errors
export type PlaceOrderError =
| { type: 'CUSTOMER_NOT_FOUND' }
| { type: 'EMPTY_ORDER' }
| { type: 'PRODUCT_NOT_FOUND'; productId: string }
| { type: 'INSUFFICIENT_INVENTORY'; productId: string; available: number; requested: number }
| { type: 'PAYMENT_FAILED'; reason: string };
// Implementation
export class PlaceOrderUseCase {
constructor(
private readonly orderRepository: OrderRepository,
private readonly customerRepository: CustomerRepository,
private readonly inventoryService: InventoryService,
private readonly paymentGateway: PaymentGateway,
private readonly eventPublisher: EventPublisher
) {}
async execute(command: PlaceOrderCommand): Promise<PlaceOrderResult | PlaceOrderError> {
// 1. Validate command
if (command.items.length === 0) {
return { type: 'EMPTY_ORDER' };
}
// 2. Load customer
const customer = await this.customerRepository.findById(command.customerId);
if (!customer) {
return { type: 'CUSTOMER_NOT_FOUND' };
}
// 3. Check inventory
for (const item of command.items) {
const availability = await this.inventoryService.checkAvailability(
item.productId,
item.quantity
);
if (!availability.available) {
return {
type: 'INSUFFICIENT_INVENTORY',
productId: item.productId,
available: availability.currentStock,
requested: item.quantity,
};
}
}
// 4. Create order (domain logic)
const order = Order.create({
customerId: customer.id,
items: command.items,
});
// 5. Process payment
const paymentResult = await this.paymentGateway.charge({
amount: order.total,
method: { id: command.paymentMethodId },
idempotencyKey: order.id.value,
});
if (paymentResult.status === 'failed') {
return { type: 'PAYMENT_FAILED', reason: paymentResult.failureReason ?? 'Unknown' };
}
// 6. Mark order as paid
order.markPaid(paymentResult.transactionId);
// 7. Reserve inventory
await this.inventoryService.reserve(order.id, command.items);
// 8. Persist order
await this.orderRepository.save(order);
// 9. Publish domain events
await this.eventPublisher.publishAll(order.pullEvents());
// 10. Return result
return {
orderId: order.id.value,
total: order.total.amount,
currency: order.total.currency,
};
}
}
```
## Test Template
```typescript
// src/application/use-cases/PlaceOrder/PlaceOrder.test.ts
import { describe, test, expect, beforeEach } from 'bun:test';
import { PlaceOrderUseCase, PlaceOrderCommand } from './PlaceOrder';
import { FakeOrderRepository } from '../../../infrastructure/persistence/__fakes__/FakeOrderRepository';
import { FakeCustomerRepository } from '../../../infrastructure/persistence/__fakes__/FakeCustomerRepository';
import { FakeInventoryService } from '../../../infrastructure/external/__fakes__/FakeInventoryService';
import { FakePaymentGateway } from '../../../infrastructure/external/__fakes__/FakePaymentGateway';
import { FakeEventPublisher } from '../../../infrastructure/external/__fakes__/FakeEventPublisher';
describe('PlaceOrderUseCase', () => {
let useCase: PlaceOrderUseCase;
let orderRepository: FakeOrderRepository;
let customerRepository: FakeCustomerRepository;
let inventoryService: FakeInventoryService;
let paymentGateway: FakePaymentGateway;
let eventPublisher: FakeEventPublisher;
beforeEach(() => {
orderRepository = new FakeOrderRepository();
customerRepository = new FakeCustomerRepository();
inventoryService = new FakeInventoryService();
paymentGateway = new FakePaymentGateway();
eventPublisher = new FakeEventPublisher();
useCase = new PlaceOrderUseCase(
orderRepository,
customerRepository,
inventoryService,
paymentGateway,
eventPublisher
);
});
const validCommand: PlaceOrderCommand = {
customerId: 'customer-123',
items: [{ productId: 'product-1', quantity: 2 }],
paymentMethodId: 'pm-123',
};
test('successfully places order', async () => {
// Arrange
customerRepository.add({ id: 'customer-123', name: 'Test' });
inventoryService.setAvailable('product-1', 10);
paymentGateway.willSucceed();
// Act
const result = await useCase.execute(validCommand);
// Assert
expect('orderId' in result).toBe(true);
expect(orderRepository.savedOrders).toHaveLength(1);
expect(eventPublisher.publishedEvents).toHaveLength(1);
});
test('returns error when customer not found', async () => {
// Arrange - no customer added
// Act
const result = await useCase.execute(validCommand);
// Assert
expect(result).toEqual({ type: 'CUSTOMER_NOT_FOUND' });
});
test('returns error when inventory insufficient', async () => {
// Arrange
customerRepository.add({ id: 'customer-123', name: 'Test' });
inventoryService.setAvailable('product-1', 1); // Only 1 available, need 2
// Act
const result = await useCase.execute(validCommand);
// Assert
expect(result).toEqual({
type: 'INSUFFICIENT_INVENTORY',
productId: 'product-1',
available: 1,
requested: 2,
});
});
test('returns error when payment fails', async () => {
// Arrange
customerRepository.add({ id: 'customer-123', name: 'Test' });
inventoryService.setAvailable('product-1', 10);
paymentGateway.willFail('Card declined');
// Act
const result = await useCase.execute(validCommand);
// Assert
expect(result).toEqual({
type: 'PAYMENT_FAILED',
reason: 'Card declined',
});
});
});
```
## Fake Implementation Template
```typescript
// src/infrastructure/persistence/__fakes__/FakeOrderRepository.ts
import type { Order, OrderId } from '../../../domain';
import type { OrderRepository } from '../../../application/ports/outbound';
export class FakeOrderRepository implements OrderRepository {
public savedOrders: Order[] = [];
private orders = new Map<string, Order>();
async save(order: Order): Promise<void> {
this.savedOrders.push(order);
this.orders.set(order.id.value, order);
}
async findById(id: OrderId): Promise<Order | null> {
return this.orders.get(id.value) ?? null;
}
async findByCustomer(): Promise<Order[]> {
return Array.from(this.orders.values());
}
async findPending(): Promise<Order[]> {
return Array.from(this.orders.values()).filter(
o => o.status === 'pending'
);
}
async delete(id: OrderId): Promise<void> {
this.orders.delete(id.value);
}
async exists(id: OrderId): Promise<boolean> {
return this.orders.has(id.value);
}
// Test helpers
clear(): void {
this.savedOrders = [];
this.orders.clear();
}
}
```
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 |