Design Patterns

A technology-agnostic skill for software architecture and design patterns.

Architectural Patterns

Layered Architecture

pattern: layered_architecture
description: "Separation of concerns through horizontal layers"

layers:
  presentation:
    responsibility: "User interface and input handling"
    communicates_with: [application]

  application:
    responsibility: "Business logic orchestration"
    communicates_with: [domain, infrastructure]

  domain:
    responsibility: "Core business rules and entities"
    communicates_with: [none - pure domain logic]

  infrastructure:
    responsibility: "External systems, persistence, APIs"
    communicates_with: [domain]

rules:
  - "Dependencies point inward (presentation → domain)"
  - "Each layer only knows about adjacent layers"
  - "Domain layer has no external dependencies"

Clean Architecture

pattern: clean_architecture
description: "Dependency inversion with entities at center"

rings:
  entities:
    description: "Enterprise business rules"
    dependencies: none

  use_cases:
    description: "Application business rules"
    dependencies: [entities]

  interface_adapters:
    description: "Controllers, presenters, gateways"
    dependencies: [use_cases, entities]

  frameworks:
    description: "External frameworks and drivers"
    dependencies: [interface_adapters]

key_principle: "Dependencies always point inward"

Hexagonal Architecture (Ports & Adapters)

pattern: hexagonal_architecture
description: "Core logic isolated from external concerns"

components:
  core:
    description: "Domain logic, independent of I/O"
    contains: [entities, services, ports]

  ports:
    description: "Interfaces defining boundaries"
    types:
      - primary: "Driven by external (API, UI)"
      - secondary: "Driving external (DB, messaging)"

  adapters:
    description: "Implementations connecting to external systems"
    examples:
      - "REST controller (primary adapter)"
      - "Repository implementation (secondary adapter)"

benefit: "Core can be tested without external systems"

Component Design Patterns

Repository Pattern

pattern: repository
description: "Abstract data access behind collection-like interface"

structure:
  interface:
    methods:
      - "find(id): Entity"
      - "findAll(criteria): Entity[]"
      - "save(entity): void"
      - "delete(entity): void"

  implementation:
    responsibility: "Handle actual persistence"
    examples:
      - DatabaseRepository
      - InMemoryRepository
      - CacheDecoratorRepository

use_when:
  - "Separate domain from data access"
  - "Enable testing with in-memory implementations"
  - "Support multiple data sources"

Service Pattern

pattern: service
description: "Encapsulate business operations"

types:
  domain_service:
    description: "Operations that don't belong to a single entity"
    example: "TransferService for money transfers between accounts"

  application_service:
    description: "Orchestrate use cases"
    example: "OrderService coordinating payment, inventory, shipping"

  infrastructure_service:
    description: "External system interactions"
    example: "EmailService, PaymentGatewayService"

guidelines:
  - "Services are stateless"
  - "One public method per specific operation"
  - "Coordinate, don't contain business rules"

Factory Pattern

pattern: factory
description: "Encapsulate object creation logic"

types:
  simple_factory:
    use_when: "Creation logic is complex but static"
    example: "UserFactory.create(type)"

  factory_method:
    use_when: "Subclasses need to determine creation"
    example: "Abstract Document with createPage() method"

  abstract_factory:
    use_when: "Create families of related objects"
    example: "UIFactory creating buttons, dialogs, menus"

benefits:
  - "Centralize creation logic"
  - "Enforce invariants at creation"
  - "Support testing with mock factories"

Database Design Patterns

Entity Relationship Patterns

patterns:
  one_to_many:
    description: "Parent has many children"
    implementation:
      - "Foreign key in child table"
      - "ON DELETE CASCADE if children are owned"
    example: "User has many Posts"

  many_to_many:
    description: "Both sides have many of each other"
    implementation:
      - "Junction/pivot table"
      - "Consider if junction has attributes"
    example: "Users and Roles via user_roles table"

  one_to_one:
    description: "Exactly one on each side"
    implementation:
      - "Foreign key with unique constraint"
      - "Or same primary key in both tables"
    example: "User has one Profile"

Query Optimization Patterns

optimization_patterns:
  indexing:
    description: "Speed up queries on specific columns"
    guidelines:
      - "Index columns in WHERE, JOIN, ORDER BY"
      - "Consider composite indexes for multi-column queries"
      - "Avoid over-indexing (slows writes)"

  eager_loading:
    description: "Load related data in fewer queries"
    use_when: "Always need related data"
    avoid_when: "Related data rarely used"

  pagination:
    description: "Limit result set size"
    techniques:
      - "LIMIT/OFFSET for simple cases"
      - "Cursor-based for large datasets"

API Design Patterns

RESTful Resource Design

rest_patterns:
  resource_naming:
    rules:
      - "Use nouns, not verbs (/users, not /getUsers)"
      - "Use plural form (/users, not /user)"
      - "Use kebab-case for multi-word (/user-profiles)"
      - "Nest for relationships (/users/{id}/posts)"

  http_methods:
    GET: "Retrieve resource(s)"
    POST: "Create new resource"
    PUT: "Replace entire resource"
    PATCH: "Partial update"
    DELETE: "Remove resource"

  response_codes:
    200: "OK - Successful GET, PUT, PATCH"
    201: "Created - Successful POST"
    204: "No Content - Successful DELETE"
    400: "Bad Request - Invalid input"
    401: "Unauthorized - Auth required"
    403: "Forbidden - No permission"
    404: "Not Found - Resource doesn't exist"
    422: "Unprocessable - Validation failed"
    500: "Server Error - Unexpected failure"

Request/Response Patterns

patterns:
  envelope:
    description: "Wrap response in metadata"
    structure:
      data: "The actual response data"
      meta: "Pagination, timestamps, etc."
      errors: "Error details if applicable"

  hateoas:
    description: "Include links to related actions"
    example:
      data: {id: 1, name: "..."}
      links:
        self: "/users/1"
        posts: "/users/1/posts"
        delete: "/users/1"

Integration

Used By Agents

primary_users:
  - design-architect: "Pattern selection and application"

secondary_users:
  - code-developer: "Implementing designed patterns"
  - quality-reviewer: "Validating pattern compliance"