software-design

Core Engineering Patterns

The canonical source of architectural patterns and principles for consistent, high-quality code.

Iron Law

NEVER THROW IN BUSINESS LOGIC [1][11]

All operations that can fail MUST return Result types. Exceptions are allowed ONLY at system boundaries (API handlers, database adapters). Any throw statement in business logic is a violation. No exceptions.

Philosophy

1. Functional Core, Imperative Shell [11] — Pure business logic, side effects at boundary
2. Explicit Error Handling [1][8] — Result types, no exceptions in business logic
3. Immutability by Default [7][14] — Return new objects, never mutate
4. Dependency Injection [3] — All deps injected, nothing instantiated internally
5. Make Illegal States Unrepresentable [4][2] — Types enforce invariants at compile time
6. Parse, Don't Validate [12] — Schema transforms at boundaries

---

Pattern 1: Result Types [1][5][6][18]

type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

function createUser(data: unknown): Result<User, ValidationError> {
  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
  return Ok(buildUser(data));
}
// Libraries: neverthrow [18], ts-results [19]. Theory: Moggi [5] + Wadler [6].

Pattern 2: Dependency Injection [3]

class UserService {
  constructor(private db: Database, private emailer: EmailService) {}
  // Test: new UserService(mockDb, mockEmailer) — never new Database() inside [3]
}

Pattern 3: Immutability [7][14]

// New object, never mutate input; copy before .sort() [7][14]
function updateUser(user: User, changes: Partial<User>): User {
  return { ...user, ...changes };
}

Pattern 4: Functional Core, Imperative Shell [11]

// PURE CORE: no I/O, deterministic [11]
function calculateTotal(items: Item[], taxRate: number): number {
  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
}
// IMPERATIVE SHELL: I/O at boundary only [11]
async function processOrder(id: string): Promise<Result<Order, Error>> {
  const order = await db.getOrder(id);
  return Ok(await db.save({ ...order, total: calculateTotal(order.items, 0.1) }));
}