Architecture - Generic (Web?) Codebase Layout

This article builds upon the principles outlined in Architecture - Applied Separation of Concerns. For a deeper understanding, we recommend reviewing that piece first. As teams manage multiple codebases in mono or mutli repositories, codebase structure becomes critical. To reduce maintenance costs, lower codebase entry barriers, and navigate ever-growing product complexity, a systematized, carefully designed, and policed organization is essential. In this article, we propose a streamlined approach for front-end and back-end web services, advocating for a layered architecture divided into three to four distinct tiers.

/**Infrastructure** - Tooling where codebases aren't managed by the team, ie. applicative dumb pluggins
/**Presentation** - (API or UI) humain interfacing logic (applicative IO logic)
/**Domain** - Core applicative logic 
/**Data** - Data Logic

UI-Interfaces

Infrastructure/ 
    Players: Frameworks Components & Libraries (eg. ANGULAR, REACT, VUE, SVELTE..)
    Handles: USO (UI State Objects)

Presentation/ 
    Players: Presenters Services, the logic of UI presentation
    Handles: DPO (Data Presentation Objects)

Domain/ 
    Players: Interactor and Usecases
    Handles: DBO (Data Business Objects)

Data/ 
    Players: Repositories
    Handles: DSO (Data Storage Objects)

Infrastructure/ 
    Players: Gateways & Pluggings
    Handles: Data Sources (eg. CACHE STORE, HTTPS, WEBSOCKETS, LOCAL & SESSION STORAGE, COOKIES)..

API-Interfaces

Infrastructure/ 
    Players: Frameworks Components & Libraries, eg. Middleware, Controller, etc.
    Handles: DTO (Data Transfer Objects)

Presentation/ 
    Players: System IO, Command & Query segregation
    Handles: DPO (Data Presentation Objects) (Command, Query, Projections)

Domain/ 
    Players: Interactor and Usecases
    Handles: DBO (Data Business Objects)

Data/ 
    Players: Repositories
    Handles: DSO (Data Storage Objects)

Infrastructure/ 
    Players: Gateways & Pluggings
    Handles: Data Sources (eg. CACHE STORES, SQL, NOSQL, REST-SERVICES)..

Codebase Layout Example

  eg. Applying segregation of Concerns ✦ CQRS ✦ Anti‑Corruption Layer (ACL)
  ===========================================================================
      directory layout (three macro‑layers, integrated presentation)

    src/
    ├─ infrastructure/ ◂── outer ring: frameworks + adapters
    │ ├─ tooling/ ◂── logger, env, health checks, etc.
    │ ├─ api/
    │ │ ├─ http/
    │ │ │ ├─ controllers/
    │ │ │ ├─ dto/
    │ │ │ └─ mapper/ ◂── DTO ↔︎ Query/Command
    │ │ └─ middleware/ ◂── auth, rate‑limit, logging
    │ └─ gateways/
    │ │ ├─ sql/
    │ │ | ├─ gateway*impl/ ◂── Data Pluggings normalisation
    │ │ | └─ orm/
    │ │ | ├─ models/ ◂── @Entity classes
    │ │ | └─ config/ ◂── DataSource & migrations
    │ │ ├─ nosql
    │ │ └─ ..
    │
    ├─ domain/ ◂── core business rules
    │ ├─ entities/
    │ ├─ queries/
    │ ├─ commands/
    │ ├─ read-models/
    │ ├─ mappers/ ◂── DBO → DSPO
    │ ├─ usecase/ ◂── implements UseCase<I,O>
    │ └─ repositories/ ◂── \_ports* (interfaces)
    │
    └─ data/ ◂── inner adapters toward persistence
    | ├─ repository*impl/
    | ├─ gateways/ ◂── \_ports* (interfaces) that infra impls implement
    | ├─ mappers/ ◂── DBO ↔︎ DSO (ACL)
    | └─ commands/ ◂── hand‑optimised queries (eg. sql)

    

Dependency (only inward):

infrastructure/controller ➜ (CQRS) ➜ domain ➜ (ports) ◀︎ data ◀︎ infrastructure/gateways

Done!

Thanks for reading! We hope this provide an initial clear and modular structure for your codebases, with an intent to enhance maintainability and scalability.