oracle-architect

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