code-architecture

Code Architecture

Architecture patterns and code organization that survive contact with reality. The goal is code you can still understand, test, and change 18 months after it was written. This covers the decisions made at the module and application level — not how to split services, not how to design schemas, but how to organize the code within a single deployable unit.

When to Use

Use for:

• Choosing an architecture pattern for a new project (clean, hexagonal, feature-based, vertical slice)
• Diagnosing architectural problems in existing code (fat controllers, circular deps, tangled business logic)
• Applying dependency inversion to untangle tightly coupled code
• Deciding on folder structure and module organization
• Applying SOLID principles at the module scale (not just class scale)
• Setting up dependency injection containers
• Defining module boundaries and barrel exports
• Designing the test pyramid relative to architecture layers

NOT for:

• Splitting a monolith into microservices (use microservices-patterns)
• Database schema design, normalization, query optimization (use database-design-patterns)
• Framework-specific routing or middleware setup
• CI/CD pipeline architecture

---

Core Decision: Which Architecture Pattern?

flowchart TD
    Start[New project or restructuring?] --> Team{Team size?}

    Team -->|Solo / 2 dev| Size{App complexity?}
    Team -->|3-8 dev| MedComplex{Domain complexity?}
    Team -->|8+ dev| Large[Feature-based / Vertical Slice]

    Size -->|Simple CRUD, low domain logic| Simple[Flat + MVC or Feature-Based]
    Size -->|Complex domain, long-lived| Hex[Hexagonal Architecture]

    MedComplex -->|Low: thin business layer| FeatureBased[Feature-Based Organization]
    MedComplex -->|High: rich business rules| Clean[Clean Architecture]
    MedComplex -->|Mixed: CRUD + some complex| Vertical[Vertical Slice Architecture]

    Simple --> SCheck{Will it grow?}
    SCheck -->|No, short-lived| MVC[Layer-based MVC is fine]
    SCheck -->|Yes| FeatureBased

    Large --> Testing{Testing rigor?}
    Testing -->|Low: mostly E2E| Vertical
    Testing -->|High: unit + integration| Clean

    Clean --> ClNote[Entities → Use Cases → Interface Adapters → Frameworks]
    Hex --> HexNote[Domain core ↔ Ports ↔ Adapters]
    FeatureBased --> FBNote[features/X contains all layers for X]
    Vertical --> VSNote[Each slice owns its full stack top to bottom]