Architecture

Architecture Skill

Purpose: Apply proven architectural patterns for scalable, maintainable systems using industry-standard methodologies

Overview

This skill provides deep guidance for designing software architectures using Domain-Driven Design, Clean Architecture, the 12-Factor App methodology, event-driven patterns, and SOLID principles.

Architectural Patterns

1. Layered Architecture

┌─────────────────────────┐
│    Presentation Layer   │  ← Controllers, Views, API endpoints
├─────────────────────────┤
│    Application Layer    │  ← Use Cases, Services, Orchestration
├─────────────────────────┤
│      Domain Layer       │  ← Entities, Business Logic, Domain Events
├─────────────────────────┤
│   Infrastructure Layer  │  ← Database, External APIs, Messaging
└─────────────────────────┘

Rule: Each layer ONLY imports from the layer directly below it. Never skip layers.

2. Clean Architecture

                ┌─────────────┐
                │  Frameworks  │  ← Web, DB, UI (outermost)
              ┌─┤             ├─┐
              │ │  Adapters   │ │  ← Controllers, Gateways, Presenters
            ┌─┤ │             │ ├─┐
            │ │ │  Use Cases  │ │ │  ← Application business rules
          ┌─┤ │ │             │ │ ├─┐
          │ │ │ │  Entities   │ │ │ │  ← Core business objects (innermost)
          └─┤ │ │             │ │ ├─┘
            └─┤ │             │ ├─┘
              └─┤             ├─┘
                └─────────────┘

Dependency Rule: Source code dependencies ALWAYS point inward. Inner layers know nothing about outer layers.

3. Hexagonal Architecture (Ports & Adapters)

         ┌─────────────────┐
   ──────│     Ports       │──────
   Input │   (Interfaces)  │ Output
   Ports │                 │ Ports
         │  Domain Core    │
         │                 │
   ──────│    Adapters     │──────
   Input │  (Implementations)│ Output
   Adapters                  Adapters
         └─────────────────┘

Key Insight: The domain core defines ports (interfaces). Adapters implement them. This makes the domain testable without infrastructure.

Domain-Driven Design (DDD)

Strategic DDD — Bounded Contexts

Tactical DDD — Building Blocks

Aggregate Design Rules

1. Protect invariants within aggregate boundaries — All business rules enforced by the aggregate root
2. Reference other aggregates by ID only — Never hold direct object references across aggregate boundaries
3. One transaction per aggregate — Don't modify multiple aggregates in a single transaction
4. Design small aggregates — Smaller = less contention, better scalability
5. Use eventual consistency between aggregates — Domain events for cross-aggregate communication

12-Factor App Methodology

Event-Driven Architecture

Pattern Selection

Event Design Principles

1. Events are facts — Something that happened (past tense: OrderPlaced, not PlaceOrder)
2. Events are immutable — Never modify or delete events
3. Events carry sufficient data — Include everything consumers need (avoid callbacks)
4. Events have schemas — Version and validate event structures
5. Events are ordered within an aggregate — Global ordering is optional and expensive

Design Principles

SOLID — Applied

Additional Principles

• DRY: Don't Repeat Yourself — Extract shared logic, but avoid premature abstraction
• KISS: Keep It Simple — Prefer straightforward solutions over clever ones
• YAGNI: You Aren't Gonna Need It — Don't build for hypothetical future requirements

Module Structure (DDD-Aligned)

src/
├── domain/               # Core business logic (no framework imports)
│   ├── entities/         # Entities with identity
│   ├── value-objects/    # Immutable value types
│   ├── events/           # Domain events
│   ├── services/         # Domain services
│   └── repositories/     # Repository interfaces (ports)
├── application/          # Use cases / application services
│   ├── commands/         # Write operations
│   ├── queries/          # Read operations
│   └── handlers/         # Command/query handlers
├── infrastructure/       # External concerns (adapters)
│   ├── database/         # Repository implementations
│   ├── messaging/        # Event bus, message queues
│   ├── external-apis/    # Third-party integrations
│   └── config/           # Environment configuration
└── interfaces/           # Entry points (driving adapters)
    ├── http/             # REST/GraphQL controllers
    ├── events/           # Event consumers
    └── cli/              # CLI commands

Architecture Decision Records (ADRs)

When to Write an ADR

• Choosing between architectural approaches (monolith vs microservices)
• Selecting a technology (PostgreSQL vs MongoDB)
• Establishing a pattern (event sourcing vs CRUD)
• Making a trade-off (consistency vs availability)

ADR Template

# ADR-NNN: [Decision Title]

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date**: YYYY-MM-DD
**Context**: [What is the issue? What constraints exist?]
**Decision**: [What was decided?]
**Consequences**: [What are the trade-offs? What becomes easier/harder?]
**Alternatives Considered**: [What was rejected and why?]

Quick Reference