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"