Architect Skill

Domain-Driven Design and hexagonal architecture with functional core pattern for feature design.

Architecture Model

Unified view of functional core and effectful edge:

      Effectful Edge (IO)              Functional Core (Pure)

┌─────────────────────────────────┐ ┌──────────────────────────┐ │ Router → request parsing │ │ Service → orchestration│ │ Consumer → event handling │───▶│ Entity → domain rules │ │ Client → external APIs │ │ → validation │ │ Producer → event publishing │◀───│ → transforms │ │ Repository→ data persistence │ │ │ └─────────────────────────────────┘ └──────────────────────────┘

Key Principle: Business logic lives in the functional core (Service + Entity). IO operations live in the effectful edge. Core defines interfaces; edge implements them (dependency inversion).

Functional Core

Pure, deterministic components containing all business logic.

Service Layer

Responsibility: Orchestrate business operations, coordinate between entities and repositories.

Characteristics:

• Pure functions that take data and return results

• No IO operations (database, HTTP, file system)

• Calls repositories through interfaces (dependency injection)

• Composes entity operations into workflows

• Returns success/error results

Example:

class OrderService { async createOrder(request: CreateOrderRequest): Promise<Result<Order>> { // Validate with entity const order = Order.fromRequest(request); const validation = order.validate(); if (!validation.ok) return validation;

// Check business rules
const inventory = await this.inventoryRepo.checkAvailability(order.items);
if (!inventory.available) return Err('Items not available');

// Coordinate persistence
await this.inventoryRepo.reserve(order.items);
const saved = await this.orderRepo.save(order.toRecord());

return Ok(Order.fromRecord(saved));

} }

Entity Layer

Responsibility: Domain models, validation, business rules, data transformations.

Characteristics:

• Pure data structures with behavior

• All validation logic

• Data transformations (fromRequest, toRecord, toResponse)

• Business rules and invariants

• No IO, no framework dependencies

Example:

class Order { constructor( public readonly id: string, public readonly customerId: string, public readonly items: OrderItem[], public readonly status: OrderStatus, public readonly total: number ) {}

static fromRequest(req: CreateOrderRequest): Order { return new Order( generateId(), req.customerId, req.items.map(i => new OrderItem(i)), 'pending', req.items.reduce((sum, i) => sum + i.price * i.quantity, 0) ); }

toRecord(): OrderRecord { return { id: this.id, customer_id: this.customerId, items: JSON.stringify(this.items), status: this.status, total: this.total }; }

validate(): Result<Order> { if (this.items.length === 0) { return Err('Order must have at least one item'); } if (this.total < 0) { return Err('Order total cannot be negative'); } return Ok(this); }

canCancel(): boolean { return ['pending', 'confirmed'].includes(this.status); } }

Effectful Edge

IO-performing components that interact with the outside world.

Router

Responsibility: HTTP request handling, parsing, response formatting.

Characteristics:

• Parses HTTP requests into domain types

• Calls service layer with parsed data

• Formats service results into HTTP responses

• Handles HTTP-specific concerns (status codes, headers)

• No business logic

Example:

router.post('/orders', async (req, res) => { const result = await orderService.createOrder(req.body);

if (result.ok) { res.status(201).json(result.value.toResponse()); } else { res.status(400).json({ error: result.error }); } });

Repository

Responsibility: Data persistence and retrieval.

Characteristics:

• Implements data access interface used by services

• Converts between domain entities and database records

• Handles database queries and transactions

• No business logic or validation

Example:

class OrderRepository { async save(record: OrderRecord): Promise<OrderRecord> { return await db.orders.create(record); }

async findById(id: string): Promise<OrderRecord | null> { return await db.orders.findOne({ id }); } }

Component Matrix

Quick reference for where things belong:

Concern Component Layer Testability

Domain model Entity Core Unit test (pure)

Validation Entity Core Unit test (pure)

Business rules Entity Core Unit test (pure)

Orchestration Service Core Unit test (stub repos)

Data transforms Entity Core Unit test (pure)

HTTP parsing Router Edge Integration test

Data access Repository Edge Integration test

External APIs Client Edge Integration test

Event handling Consumer Edge Integration test

Event publishing Producer Edge Integration test

Task Breakdown

Bottom-Up Dependency Ordering

Implementation order follows dependency chain:

1. Entity → Domain models, validation, transforms
2. Repository → Data access interfaces and implementations
3. Service → Business logic orchestration
4. Router → HTTP endpoints

Rationale: Each layer depends on layers below. Can't implement service without entity, can't implement router without service.

Task Granularity

One task per layer:

• Implement Order entity with validation

• Implement OrderRepository with data access

• Implement OrderService with business logic

• Implement order API endpoints

For complex features, break down further:

• Entity: Order, OrderItem, OrderStatus

• Repository: OrderRepository, InventoryRepository

• Service: OrderService, PaymentService

• Router: Order routes, Payment routes

Architect → Testing Flow

Architectural decisions inform testing strategy:

Architect Outputs → Testing Inputs ──────────────────────────────────────────────── Component responsibilities → What to test Layer boundaries → Where to test Pure vs effectful → Unit vs integration Entity transformations → Property-based tests Service orchestration → Stub-driven tests

The testing skill uses architectural structure to determine:

• What gets unit tested (core) vs integration tested (edge)

• Where to place test boundaries

• What to stub and what to test for real

• What test cases validate business rules

Reference Materials

For detailed patterns and examples:

• See references/ddd-patterns.md - Aggregates, Value Objects, Domain Events, Bounded Contexts, composition patterns

• See references/data-modeling.md - Entity design principles, schema patterns, access pattern optimization, data transformation

• See references/api-design.md - REST conventions, request/response contracts, error handling, versioning patterns