# Architecture Patterns

> Use when selecting architecture patterns (MVC, hexagonal, clean, microservices) for a new project.

- Skill: `ankurjain1121/architecture-patterns` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ankurjain1121/architecture-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ankurjain1121/architecture-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ankurjain1121 (https://skillmd.com/u/ankurjain1121)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ankurjain1121/architecture-patterns

---


# 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)

```
┌─────────────────────────────────────┐
│            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:**
```
src/
├── controllers/
│   ├── userController.ts
│   └── taskController.ts
├── models/
│   ├── User.ts
│   └── Task.ts
└── views/
    └── (templates or React components)
```

---

### Layered Architecture

```
┌─────────────────────────────────────┐
│       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)

```
                    ┌─────────────────┐
                    │   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

```
┌──────────┐  ┌──────────┐  ┌──────────┐
│  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

```
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:
1. Analyze project complexity
2. Consider team size and experience
3. Research pattern options
4. Document decision as ADR
5. Create module hierarchy based on pattern
6. Update dependency graph