architecture-patterns

Decision guide for choosing architectural approaches by project complexity, team size, and context. Orchestrates architectural thinking without coupling to specific patterns.

When to Use

• Deciding WHEN to apply architecture vs keeping it simple
• Choosing architectural approach by project complexity
• Planning strategic refactoring (module boundaries, layers)
• Understanding frontend vs backend architectural differences
• Evaluating architecture trade-offs

Don't use for:

• Learning specific patterns → use pattern-specific skills (solid, domain-driven-design, clean-architecture)
• Tactical refactoring (rename, extract, inline) → use code-refactoring skill
• Code review → use critical-partner skill

---

Critical Patterns

✅ REQUIRED: Complexity-Driven Architecture

Match architecture complexity to project size and team.

Small (1-3 devs, <10k LOC):
  → Keep simple — folder structure + code-conventions is enough
  → Apply: Basic separation (routes, components, utils)
  → Avoid: Layered architecture, DDD, Clean Architecture (overkill)

Medium (4-10 devs, 10k-100k LOC):
  → Modular architecture — clear module boundaries
  → Apply: Single responsibility per module, layer separation
  → Consider: Clean Architecture for testability

Large/Enterprise (10+ devs, >100k LOC, multiple teams):
  → Full architectural approach required
  → Apply: Strict boundaries, domain-driven modules, hexagonal for testability
  → Consider: DDD for complex business domains

Guideline: Start simple. Apply architecture when pain points emerge.

✅ REQUIRED: Recognize Architecture Pain Points

Apply architecture when you see these signals:

❌ Files >500 lines with mixed responsibilities
❌ Changing one feature breaks unrelated features
❌ Tests require 5+ mocks to test one unit
❌ New devs take >2 weeks to make first contribution
❌ Same bug fixed multiple times in different places

✅ REQUIRED: Frontend vs Backend Architecture

Different architectural concerns by platform:

Frontend architecture:
  → Component hierarchy and composition
  → State management boundaries (local vs global)
  → Data fetching and caching strategies
  → Route-based code splitting

Backend architecture:
  → Request/response flow layers
  → Business logic isolation from infrastructure
  → Database access patterns
  → API contract design

Common mistake: Applying backend patterns (repositories, use cases) to simple frontends. Most SPAs need state management + component composition, not full Clean Architecture.

✅ REQUIRED: Strategic vs Tactical Refactoring

Tactical (use code-refactoring skill):
  → Rename variables/functions
  → Extract small function
  → Inline variable

Strategic (THIS skill):
  → Define module boundaries
  → Separate layers (presentation, domain, data)
  → Extract entire modules
  → Redesign dependencies

When to refactor strategically:
  → Files >500 lines
  → Changing one feature breaks unrelated features
  → Tests require mocking 5+ dependencies

---

Decision Tree

Choosing architecture approach?
  → Small project (<10k LOC, 1-3 devs)?
    → Keep simple - folder structure + code-conventions
  → Medium project (10k-100k LOC, 4-10 devs)?
    → Apply modular architecture - clear module boundaries
  → Large project (>100k LOC, 10+ devs)?
    → Apply full architecture - strict boundaries, domain-driven

Frontend or backend?
  → Frontend → Focus: component composition, state management, data fetching
  → Backend → Focus: layer separation, business logic isolation, API contracts

Planning refactoring?
  → Tactical (rename, extract, inline)?  → Use code-refactoring skill
  → Strategic (modules, layers)?         → Use THIS skill

Need specific pattern knowledge?
  → SOLID principles              → solid skill
  → Clean Architecture            → clean-architecture skill
  → Domain-Driven Design          → domain-driven-design skill
  → Ports and Adapters            → hexagonal-architecture skill
  → Domain-first folder structure → screaming-architecture skill
  → Error handling pattern        → result-pattern skill
  → Eliminate duplication         → dry-principle skill
  → Decoupled communication       → mediator-pattern skill
  → State / workflow modeling     → state-machines-pattern skill
  → Flexible component APIs       → composition-pattern skill
  → Fault tolerance / fast fail   → circuit-breaker-pattern skill
  → Microservice sidecar          → sidecar-pattern skill

---

Example

Repository + Service Layer pattern applied to a user feature in a medium-sized backend.

Request: POST /api/v1/users
         ↓
UserController          (Presentation)
  → validates input with zod
  → calls UserService.createUser(dto)
         ↓
UserService             (Business Logic)
  → checks email uniqueness
  → hashes password
  → calls UserRepository.save(user)
         ↓
UserRepository          (Data Access)
  → IUserRepository interface defined in application layer
  → PostgresUserRepository implements it in infrastructure
  → returns saved User entity
         ↓
UserController
  → maps result to 201 Created + UserResponseDTO

Why this fits a medium project (4-10 devs, 10k–100k LOC):

• Clear layer boundaries make code navigable for new team members
• Repository interface lets tests inject in-memory fakes (no DB required)
• Service layer owns business rules (uniqueness, hashing) — not the controller

---

Edge Cases

Over-engineering: Applying Clean Architecture to a 1000-line app. Start simple, add architecture when pain emerges.

Under-engineering: No architecture in 100k LOC app with 10 devs. Technical debt compounds, velocity slows dramatically.

Premature abstraction: Creating 5 layers before knowing requirements. Apply YAGNI — add layers when needed, not speculatively.

Frontend Clean Architecture: Usually overkill for React apps. State management (Redux/Zustand) + smart component composition is sufficient for most cases.

---

Checklist

• [ ] Project complexity assessed (small/medium/large)
• [ ] Architecture approach chosen for complexity level
• [ ] Frontend vs backend context considered
• [ ] Strategic vs tactical refactoring distinguished
• [ ] Specific pattern skills consulted if needed

---

Resources

• code-refactoring — Tactical refactoring patterns
• frontend-dev — Frontend workflow and patterns
• backend-dev — Backend workflow and patterns

Pattern-specific skills:

• solid, clean-architecture, domain-driven-design
• hexagonal-architecture, screaming-architecture
• result-pattern, dry-principle
• mediator-pattern, composition-pattern
• state-machines-pattern, circuit-breaker-pattern
• sidecar-pattern

Integration examples:

• backend-integration.md — Architecture in Node.js/NestJS/Express
• frontend-integration.md — Architecture in React + Redux