Imported from frankxai/arcanea-ai-app (
.claude/skills/oss/architecture-patterns/SKILL.md). Install upstream withnpx skills add frankxai/arcanea-ai-app --skill architecture-patterns. Copyright stays with the author.
The Architecture Patterns Codex
"Architecture is the art of making the complex manageable. Choose patterns that reveal intent, not hide it."
The Architecture Philosophy
Why Architecture Matters
CODE is what the system DOES.
ARCHITECTURE is what the system IS.
Bad architecture makes good code hard to write.
Good architecture makes bad code easy to fix.
Architecture decisions are expensive to change.
Choose wisely. Change reluctantly.
The Pattern Categories
Structural Patterns
╔═══════════════════════════════════════════════════════════════════╗
║ STRUCTURAL PATTERNS ║
╠═══════════════════════════════════════════════════════════════════╣
║ ║
║ LAYERED │ Horizontal separation of concerns ║
║ HEXAGONAL │ Ports and adapters, domain-centric ║
║ CLEAN │ Dependencies point inward ║
║ VERTICAL SLICE │ Feature-based organization ║
║ MODULAR MONOLITH │ Bounded contexts in single deployment ║
║ ║
╚═══════════════════════════════════════════════════════════════════╝
Distributed Patterns
╔═══════════════════════════════════════════════════════════════════╗
║ DISTRIBUTED PATTERNS ║
╠═══════════════════════════════════════════════════════════════════╣
║ ║
║ MICROSERVICES │ Independent deployable services ║
║ EVENT-DRIVEN │ Async communication via events ║
║ CQRS │ Separate read and write models ║
║ EVENT SOURCING │ Store events, derive state ║
║ SAGA │ Distributed transactions ║
║ ║
╚═══════════════════════════════════════════════════════════════════╝
Pattern Deep Dives
The Layered Architecture
┌─────────────────────────────────────┐
│ PRESENTATION LAYER │ ← UI, Controllers, Views
├─────────────────────────────────────┤
│ APPLICATION LAYER │ ← Use Cases, Services
├─────────────────────────────────────┤
│ DOMAIN LAYER │ ← Business Logic, Entities
├─────────────────────────────────────┤
│ INFRASTRUCTURE LAYER │ ← Database, External APIs
└─────────────────────────────────────┘
RULES:
• Dependencies flow DOWN only
• Each layer knows only layer below
• Domain layer has ZERO dependencies
When to Use:
✓ Traditional business applications
✓ CRUD-heavy systems
✓ Teams familiar with MVC patterns
✓ Moderate complexity
✗ Highly dynamic requirements
✗ Event-heavy systems
✗ Complex business logic
The Hexagonal Architecture (Ports & Adapters)
┌───────────────┐
│ PRIMARY │
│ ADAPTERS │
│ (Controllers) │
└───────┬───────┘
│
┌───────▼───────┐
│ │
┌───────┤ PORTS ├───────┐
│ │ (Interfaces) │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ │ │
│ │ DOMAIN │ │
│ │ (Core) │ │
│ │ │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ │ │
└───────┤ PORTS ├───────┘
│ (Interfaces) │
└───────┬───────┘
│
┌───────▼───────┐
│ SECONDARY │
│ ADAPTERS │
│ (Repositories)│
└───────────────┘
CORE INSIGHT:
Domain knows nothing about the outside world.
Adapters translate between domain and infrastructure.
When to Use:
✓ Domain-driven design projects
✓ Systems needing high testability
✓ Multiple input/output channels
✓ Long-lived business applications
✗ Simple CRUD applications
✗ Rapid prototypes
✗ Small teams with tight deadlines
The Clean Architecture
┌─────────────────────────────────────────────────────────────┐
│ FRAMEWORKS & DRIVERS │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ INTERFACE ADAPTERS │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ APPLICATION LAYER │ │ │
│ │ │ ┌─────────────────────────────────────────┐ │ │ │
│ │ │ │ DOMAIN LAYER │ │ │ │
│ │ │ │ (Entities & Rules) │ │ │ │
│ │ │ └─────────────────────────────────────────┘ │ │ │
│ │ │ (Use Cases) │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ │ (Controllers, Gateways, Presenters) │ │
│ └───────────────────────────────────────────────────────┘ │
│ (Web, UI, DB, External Interfaces) │
└─────────────────────────────────────────────────────────────┘
THE DEPENDENCY RULE:
Dependencies point INWARD only.
Inner circles know nothing about outer circles.
Vertical Slice Architecture
Traditional (Layered): Vertical Slice:
┌──────────────────┐ ┌─────┬─────┬─────┐
│ Controllers │ │ F │ F │ F │
├──────────────────┤ │ E │ E │ E │
│ Services │ │ A │ A │ A │
├──────────────────┤ → │ T │ T │ T │
│ Repositories │ │ U │ U │ U │
├──────────────────┤ │ R │ R │ R │
│ Database │ │ E │ E │ E │
└──────────────────┘ │ 1 │ 2 │ 3 │
└─────┴─────┴─────┘
INSIGHT:
Group by FEATURE, not by layer.
Each slice is independent and complete.
When to Use:
✓ Feature teams
✓ Rapid iteration
✓ Varying complexity per feature
✓ CQRS systems
✗ Highly shared logic
✗ Small applications
✗ Strong layer conventions required
Distributed Architecture Patterns
Microservices
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Service │ │ Service │ │ Service │
│ A │────▶│ B │────▶│ C │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ DB A │ │ DB B │ │ DB C │
└─────────┘ └─────────┘ └─────────┘
PRINCIPLES:
1. Single responsibility per service
2. Own your data
3. Communicate via well-defined APIs
4. Deploy independently
5. Design for failure
The Microservices Decision:
CONSIDER MICROSERVICES WHEN:
• Multiple teams need autonomy
• Different scaling requirements per component
• Polyglot persistence needed
• Independent deployment critical
• Organization is distributed
AVOID MICROSERVICES WHEN:
• Small team (< 10 developers)
• Simple domain
• Tight deadlines
• Limited DevOps capability
• Unknown domain boundaries
Event-Driven Architecture
┌──────────┐ ┌─────────────┐ ┌──────────┐
│ Producer │────────▶│ Event Bus │────────▶│ Consumer │
└──────────┘ │ (Kafka/RMQ) │ └──────────┘
└─────────────┘
│
┌─────┴─────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ Consumer │ │ Consumer │
└──────────┘ └──────────┘
EVENT TYPES:
• Domain Events: Something happened (OrderPlaced)
• Integration Events: Cross-boundary communication
• Commands: Request to do something
• Queries: Request for information
CQRS (Command Query Responsibility Segregation)
┌─────────────────────────────────────────────┐
│ Client │
└─────────────────┬───────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ COMMANDS │ │ QUERIES │
│ (Write) │ │ (Read) │
└───────┬───────┘ └───────┬───────┘
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Write Model │ │ Read Model │
│ (Normalized) │──▶│ (Optimized) │
└───────────────┘ └───────────────┘
INSIGHT:
Reads and writes have different needs.
Optimize each independently.
Architecture Decision Framework
The SOLID Principles in Architecture
S - Single Responsibility
Each component has one reason to change
O - Open/Closed
Open for extension, closed for modification
L - Liskov Substitution
Components should be replaceable
I - Interface Segregation
Clients shouldn't depend on unused interfaces
D - Dependency Inversion
Depend on abstractions, not concretions
Choosing Your Architecture
START HERE:
┌────────────────────────────────────────────────────────────┐
│ What is your team size? │
├────────────────────────────────────────────────────────────┤
│ < 5 developers → Consider Modular Monolith │
│ 5-15 developers → Consider Vertical Slices │
│ 15+ developers → Consider Microservices │
└────────────────────────────────────────────────────────────┘
THEN ASK:
□ How complex is the domain? (Simple → Layered)
□ How testable must it be? (High → Hexagonal/Clean)
□ How often does it change? (Often → Vertical Slices)
□ How independent are components? (Very → Microservices)
□ What are the scaling needs? (Variable → CQRS)
The Strangler Fig Pattern
For migrating from legacy:
PHASE 1: Create new system alongside old
┌──────────┐ ┌──────────┐
│ Legacy │ │ New │
│ System │ │ System │
└──────────┘ └──────────┘
PHASE 2: Route new features to new system
┌──────────┐ ┌──────────┐
│ Legacy │◀───▶│ New │
│ (shrink) │ │ (grows) │
└──────────┘ └──────────┘
PHASE 3: Migrate remaining features
┌──────────┐
│ New │
│ System │
└──────────┘
PRINCIPLE: Never big-bang rewrite.
Gradually strangle the old with the new.
Common Anti-Patterns
The Big Ball of Mud
SYMPTOMS:
• No clear structure
• Everything depends on everything
• Changes have unpredictable effects
• Only original authors understand it
CAUSES:
• No upfront design
• Deadline pressure
• Lack of refactoring
• Knowledge silos
SOLUTION:
• Identify bounded contexts
• Extract modules gradually
• Establish clear interfaces
• Apply Strangler Fig
The Distributed Monolith
SYMPTOMS:
• Microservices that must deploy together
• Shared databases
• Synchronous call chains
• Coupled release cycles
CAUSES:
• Wrong service boundaries
• Shared data without events
• Missing async patterns
SOLUTION:
• Merge tightly coupled services
• Introduce event-driven communication
• Apply domain-driven design
Quick Reference
Architecture Checklist
□ Clear separation of concerns
□ Dependencies point in one direction
□ Domain logic isolated
□ External dependencies abstracted
□ Components independently testable
□ Scaling strategy defined
□ Failure modes understood
□ Monitoring and observability planned
Pattern Selection Matrix
| Need | Pattern |
|-------------------------|----------------------|
| Simple CRUD | Layered |
| Complex domain | Hexagonal/Clean |
| Feature teams | Vertical Slices |
| Team autonomy | Microservices |
| Read/write separation | CQRS |
| Audit trail | Event Sourcing |
| Distributed txns | Saga |
| Legacy migration | Strangler Fig |
"The best architecture is the one that makes the right thing easy and the wrong thing hard."