Skip to content

aiskillstore/marketplace / skills/aaronabuusama/system-design

system-design

Verified

CTO'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.

templates/ts-hexagonal-scaffold.md

View on GitHub
# TypeScript Hexagonal Scaffold

## Complete Folder Structure

```
src/
├── domain/
│   ├── entities/
│   │   ├── [EntityName].ts
│   │   └── index.ts
│   ├── value-objects/
│   │   ├── [ValueObjectName].ts
│   │   └── index.ts
│   ├── events/
│   │   ├── [DomainEvent].ts
│   │   └── index.ts
│   ├── errors/
│   │   ├── [DomainError].ts
│   │   └── index.ts
│   └── index.ts
│
├── application/
│   ├── ports/
│   │   ├── inbound/
│   │   │   ├── [UseCase].ts
│   │   │   └── index.ts
│   │   └── outbound/
│   │       ├── [Repository].ts
│   │       ├── [Gateway].ts
│   │       └── index.ts
│   ├── use-cases/
│   │   ├── [UseCaseName]/
│   │   │   ├── [UseCaseName].ts
│   │   │   ├── [UseCaseName].test.ts
│   │   │   └── index.ts
│   │   └── index.ts
│   └── index.ts
│
├── infrastructure/
│   ├── persistence/
│   │   ├── [Repository]Impl.ts
│   │   ├── mappers/
│   │   │   └── [EntityMapper].ts
│   │   └── index.ts
│   ├── external/
│   │   ├── [GatewayName]/
│   │   │   └── [GatewayName]Impl.ts
│   │   └── index.ts
│   └── index.ts
│
├── interfaces/
│   ├── http/
│   │   ├── routes.ts
│   │   ├── controllers/
│   │   │   └── [Controller].ts
│   │   └── index.ts
│   └── index.ts
│
├── shared/
│   ├── types/
│   │   └── index.ts
│   └── utils/
│       └── index.ts
│
├── config/
│   └── index.ts
│
└── main.ts
```

## Layer Dependencies

```typescript
// domain/ - NO imports from other src/ directories
// Only standard library and pure utilities

// application/ - Can import from domain/
import { Order } from '../domain/entities';

// infrastructure/ - Can import from domain/ and application/
import { Order } from '../domain/entities';
import { OrderRepository } from '../application/ports/outbound';

// interfaces/ - Can import from application/ (and domain/ for types)
import { PlaceOrderUseCase } from '../application/ports/inbound';
```

## Main Entry Point

```typescript
// src/main.ts
import { createServer } from './interfaces/http';
import { createContainer } from './config';

async function main() {
  // Composition root - wire all dependencies
  const container = createContainer();

  // Start server with injected dependencies
  const server = createServer(container);

  server.listen(3000, () => {
    console.log('Server running on port 3000');
  });
}

main().catch(console.error);
```

## Dependency Injection Setup

```typescript
// src/config/index.ts
import { PlaceOrderUseCase } from '../application/use-cases/PlaceOrder';
import { PostgresOrderRepository } from '../infrastructure/persistence/PostgresOrderRepository';
import { StripePaymentGateway } from '../infrastructure/external/stripe/StripePaymentGateway';
import { OrderController } from '../interfaces/http/controllers/OrderController';

export interface Container {
  // Ports (interfaces)
  orderRepository: OrderRepository;
  paymentGateway: PaymentGateway;

  // Use cases
  placeOrderUseCase: PlaceOrderUseCase;

  // Controllers
  orderController: OrderController;
}

export function createContainer(): Container {
  // Create driven adapters (outbound)
  const orderRepository = new PostgresOrderRepository(/* db config */);
  const paymentGateway = new StripePaymentGateway(/* stripe config */);

  // Create use cases
  const placeOrderUseCase = new PlaceOrderUseCase(
    orderRepository,
    paymentGateway
  );

  // Create driving adapters (inbound)
  const orderController = new OrderController(placeOrderUseCase);

  return {
    orderRepository,
    paymentGateway,
    placeOrderUseCase,
    orderController,
  };
}
```

## Index File Pattern

Each directory exports its contents cleanly:

```typescript
// src/domain/entities/index.ts
export { Order } from './Order';
export { OrderItem } from './OrderItem';
export { Customer } from './Customer';

// src/domain/index.ts
export * from './entities';
export * from './value-objects';
export * from './events';
export * from './errors';
```

## Bun-Specific Server Setup

```typescript
// src/interfaces/http/routes.ts
import type { Container } from '../../config';

export function createRoutes(container: Container) {
  return {
    '/api/orders': {
      POST: (req: Request) => container.orderController.create(req),
      GET: (req: Request) => container.orderController.list(req),
    },
    '/api/orders/:id': {
      GET: (req: Request) => container.orderController.get(req),
      DELETE: (req: Request) => container.orderController.cancel(req),
    },
  };
}

// src/interfaces/http/index.ts
import { createRoutes } from './routes';
import type { Container } from '../../config';

export function createServer(container: Container) {
  const routes = createRoutes(container);

  return Bun.serve({
    routes,
    development: {
      hmr: true,
    },
  });
}
```

## Test Structure

```
src/
├── domain/
│   └── entities/
│       ├── Order.ts
│       └── Order.test.ts      # Unit test - no mocks needed
│
├── application/
│   └── use-cases/
│       └── PlaceOrder/
│           ├── PlaceOrder.ts
│           └── PlaceOrder.test.ts  # Unit test - mock ports
│
├── infrastructure/
│   └── persistence/
│       ├── PostgresOrderRepository.ts
│       └── PostgresOrderRepository.test.ts  # Integration test
│
└── interfaces/
    └── http/
        └── controllers/
            ├── OrderController.ts
            └── OrderController.test.ts  # Integration test
```
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall