Architecture Patterns for Framework Development

This skill guides the selection of appropriate architecture patterns during Phase 2, providing decision criteria, trade-offs, and implementation guidance.

Pattern Decision Matrix

Pattern	Best For	Team Size	Complexity	Scalability
MVC	Simple CRUD apps	1-3	Low	Medium
Layered	Traditional enterprise	3-10	Medium	Medium
Hexagonal	Domain-focused apps	3-15	Medium-High	High
Clean	Complex business logic	5-20	High	High
Microservices	Large distributed systems	10+	Very High	Very High
Modular Monolith	Growing apps, unclear boundaries	3-10	Medium	Medium-High

Pattern Details

MVC (Model-View-Controller)

code

┌─────────────────────────────────────┐
│            Controller               │
│    (Handles requests, routes)       │
└────────────┬───────────┬────────────┘
             │           │
             ▼           ▼
      ┌──────────┐ ┌──────────┐
      │  Model   │ │   View   │
      │ (Data)   │ │   (UI)   │
      └──────────┘ └──────────┘

When to Use:

•Simple CRUD applications
•Quick prototypes
•Small team (1-3 developers)
•Short-lived projects

Pros:

•Simple to understand
•Fast to implement
•Well-documented pattern

Cons:

•Can become messy as app grows
•Tight coupling between layers
•Hard to test in isolation

Example Structure:

code

src/
├── controllers/
│   ├── userController.ts
│   └── taskController.ts
├── models/
│   ├── User.ts
│   └── Task.ts
└── views/
    └── (templates or React components)

Layered Architecture

code

┌─────────────────────────────────────┐
│       Presentation Layer            │
│    (Controllers, Views, DTOs)       │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│        Business Layer               │
│    (Services, Domain Logic)         │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│         Data Access Layer           │
│    (Repositories, ORM)              │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│           Database                  │
└─────────────────────────────────────┘

When to Use:

•Traditional enterprise apps
•Clear separation needed
•Team familiar with layers

Pros:

•Clear responsibilities
•Each layer independently deployable
•Easy to understand

Cons:

•Changes ripple through layers
•Can lead to anemic domain model
•Tight vertical coupling

Hexagonal Architecture (Ports & Adapters)

code

                    ┌─────────────────┐
                    │   REST API      │
                    │   (Adapter)     │
                    └────────┬────────┘
                             │
┌─────────────┐    ┌─────────▼─────────┐    ┌─────────────┐
│   CLI       │◄───│                   │───►│  PostgreSQL │
│ (Adapter)   │    │   DOMAIN CORE     │    │  (Adapter)  │
└─────────────┘    │                   │    └─────────────┘
                   │   (Business       │
┌─────────────┐    │    Logic)         │    ┌─────────────┐
│  Message    │◄───│                   │───►│   Redis     │
│  Queue      │    │   [Ports define   │    │  (Adapter)  │
│ (Adapter)   │    │    interfaces]    │    └─────────────┘
└─────────────┘    └───────────────────┘

When to Use:

•Domain logic is complex
•Need to swap infrastructure
•Long-lived applications
•Multiple input/output channels

Pros:

•Domain isolated from infrastructure
•Easy to test (mock adapters)
•Swap databases/frameworks easily
•Clear boundaries

Cons:

•More initial setup
•Can feel over-engineered for simple apps
•Learning curve

Example Structure: See references/pattern-examples.md for the complete directory structure showing domain (entities, services, ports) and adapters (primary/driving and secondary/driven) with dependency injection configuration.

Clean Architecture

See references/pattern-examples.md for the complete layer diagram. Clean Architecture uses concentric circles with dependencies pointing inward: Frameworks & Drivers (outermost) → Interface Adapters → Application Business (Use Cases) → Enterprise Business (Entities, innermost).

When to Use:

•Complex business rules
•Need extreme testability
•Long-term maintainability critical
•Large team

Pros:

•Highly testable
•Independent of frameworks
•Independent of UI
•Independent of database

Cons:

•Significant boilerplate
•Steep learning curve
•Over-engineering risk

Microservices

code

┌──────────┐  ┌──────────┐  ┌──────────┐
│  User    │  │  Order   │  │ Payment  │
│ Service  │  │ Service  │  │ Service  │
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     └──────┬──────┴──────┬──────┘
            │             │
       ┌────▼────┐   ┌────▼────┐
       │API GW   │   │Event Bus│
       └─────────┘   └─────────┘

When to Use:

•Large organization (10+ developers)
•Independent deployments needed
•Different scaling requirements
•Polyglot technology requirements

Pros:

•Independent deployment
•Technology flexibility
•Team autonomy
•Fault isolation

Cons:

•Network complexity
•Distributed transactions
•Operational overhead
•Hard to debug

When NOT to Use:

•Small team
•Simple application
•Unclear domain boundaries
•Limited DevOps capability

Modular Monolith

See references/pattern-examples.md for the structure diagram. Single deployable with independent modules (Users, Orders, Payment) each containing domain logic and API layer, sharing common infrastructure while maintaining clear boundaries.

When to Use:

•Growing application
•Unclear if microservices needed
•Want future flexibility
•Medium team (3-10)

Pros:

•Simpler than microservices
•Module boundaries enforced
•Easy to extract to microservice later
•Single deployment

Cons:

•Discipline needed to maintain boundaries
•Shared database can cause issues
•Not independently scalable

Decision Flowchart

code

START
  │
  ▼
Is the domain complex?
  │
  ├─ NO → Is it a simple CRUD app?
  │         │
  │         ├─ YES → MVC
  │         └─ NO → Layered Architecture
  │
  └─ YES → Do you need independent deployments?
            │
            ├─ YES → Do you have 10+ developers?
            │         │
            │         ├─ YES → Microservices
            │         └─ NO → Modular Monolith
            │
            └─ NO → Need to swap infrastructure easily?
                     │
                     ├─ YES → Hexagonal
                     └─ NO → Clean Architecture

Research Before Deciding

For each pattern considered:

markdown

### Pattern Research: [Name]

**Official Sources:**
- [URL to authoritative source]

**Pros for Our Project:**
- [Specific benefit]

**Cons for Our Project:**
- [Specific drawback]

**Team Familiarity:** Low | Medium | High

**Verdict:** SUITABLE | NOT SUITABLE | NEEDS DISCUSSION

Integration with Framework Developer

During Phase 2:

•Analyze project complexity
•Consider team size and experience
•Research pattern options
•Document decision as ADR
•Create module hierarchy based on pattern
•Update dependency graph