software-designlisted

# 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] ```typescript 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] ```typescript class UserService { constructor(private db: Database, private emailer: EmailService) {} // Test: new Use