Project Structure Guide

Introduction

This page outlines common approaches to organizing software projects, especially when applying Domain-Driven Design (DDD) principles. It explains the purpose of each type of component and where it belongs in the folder hierarchy.

High-Level Organization

Domain: Core business logic and rules.

Application: Orchestration, DTOs, and use cases.

Infrastructure: Technical details like persistence, middleware, and external services.

Presentation: API endpoints, UI, or CLI.

Domain Layer

Entities: Objects defined by identity (e.g., Order, Customer).

Value Objects: Immutable types defined by attributes (e.g., Money, EmailAddress).

Aggregates: Clusters of entities and value objects with a root entity.

Domain Services: Stateless operations that don't fit into entities or value objects.

Application Layer

DTOs (Data Transfer Objects): Simple carriers of data between layers.

Use Cases / Application Services: Coordinate domain logic for specific scenarios.

Infrastructure Layer

Repositories: Abstract persistence and mimic collections of aggregates.

Factories: Encapsulate complex creation logic for aggregates/entities.

Middleware: Handle cross-cutting concerns like caching, logging, or authentication.

External Integrations: Clients for APIs, messaging systems, or databases.

Presentation Layer

Minimal APIs / Controllers: Define endpoints and map requests to application services.

UI Components: Web pages, views, or CLI commands.

Suggested Folder Layout

ProjectRoot/

Domain/ ** Entities/ ** ValueObjects/ ** Aggregates/ ** Services/

Application/ ** DTOs/ ** Services/

Infrastructure/ ** Repositories/ ** Factories/ ** Middleware/ ** Integrations/

Presentation/ ** Api/ ** Ui/

Key Principles

Organize by concept, not by technical detail.

Keep domain logic pure and free from infrastructure concerns.

Use consistent naming (plural for collections, singular for value objects).

Avoid catch-all folders like Utils or Common.

This structure helps ensure clarity, maintainability, and discoverability for collaborators and future maintainers.