What is the onion architecture file structure?

The Onion Architecture file structure organizes a codebase into distinct, concentric layers, ensuring a clear separation of concerns where inner layers remain independent of outer ones.

Understanding the Onion Architecture File Structure

Onion Architecture is a software design pattern that organizes the codebase into multiple layers. Each layer depends only on the layers inside of it and not on the layers outside of it. This creates a separation of concerns, which allows for a more maintainable and scalable codebase. This layered approach naturally translates into a well-defined file and project structure, enhancing modularity, testability, and adherence to business rules.

The file structure of an Onion Architecture typically mirrors its layered design, often manifested as separate projects (in environments like .NET or Java) or distinct top-level directories (in Node.js or Python).

Core Layers and Their File Structure Representation

The Onion Architecture consists of several concentric layers, with the most critical business logic residing at the core. Here's a breakdown of the typical layers and how they translate into a logical file or project structure:

1. Domain Layer (The Core)

• Purpose: This is the innermost layer and the heart of the application. It contains the core business rules, entities, value objects, aggregates, and interfaces for repositories or services that represent the application's domain. It is completely independent of external concerns.
• Typical Project/Folder Name: YourApp.Domain or YourApp.Core
• Contents:
  • Entities/: Core business objects (e.g., Product.cs, Order.java).
  • ValueObjects/: Immutable objects representing descriptive aspects (e.g., Money.cs, Address.java).
  • Aggregates/: Clusters of associated entities and value objects treated as a single unit.
  • Interfaces/: Contracts for repositories (e.g., IProductRepository.cs) or domain services that will be implemented in outer layers.
  • Enums/, Exceptions/: Domain-specific enumerations and custom exceptions.
  • DomainEvents/: Events that occur within the domain.

2. Application Layer

• Purpose: This layer contains the application-specific business rules and orchestrates the domain objects to perform use cases. It defines what the application does, coordinating between the UI and the domain. It depends on the Domain layer but is independent of the Infrastructure and Presentation layers.
• Typical Project/Folder Name: YourApp.Application
• Contents:
  • UseCases/: Specific application functionalities, often structured into Commands (for actions) and Queries (for data retrieval). For example, CreateOrderCommand.cs, GetProductByIdQuery.cs.
  • DTOs/ (Data Transfer Objects): Objects used to transfer data between layers, often representing the input/output of use cases.
  • Services/: Application services that use domain objects to fulfill business requirements.
  • Interfaces/: Contracts for infrastructure services needed by the application layer (e.g., IEmailService.cs).
  • Validators/: Business rule validation logic.
  • Pipelines/: Cross-cutting concerns like logging or transaction management.

3. Infrastructure Layer

• Purpose: This layer provides the concrete implementations for interfaces defined in the Domain and Application layers. It handles external concerns like database interactions, file system access, external API integrations, logging, and email services. It depends on the Domain and Application layers but is not depended upon by them directly.
• Typical Project/Folder Name: YourApp.Infrastructure
• Contents:
  • Persistence/: Database context, ORM configurations, concrete implementations of repository interfaces (e.g., ProductRepository.cs implementing IProductRepository).
  • Services/: Implementations of external services (e.g., EmailService.cs implementing IEmailService).
  • ThirdPartyIntegrations/: Code for interacting with external APIs or libraries.
  • Migrations/: Database migration scripts.
  • Logging/: Logging configurations and implementations.

4. Presentation Layer (UI / API)

• Purpose: This is the outermost layer, responsible for user interaction. It could be a web API, a web application (MVC), a desktop application, or a mobile app. It consumes the Application layer's services and orchestrates their usage. This layer handles user input, displays data, and configures dependency injection.
• Typical Project/Folder Name: YourApp.Api, YourApp.Web, YourApp.DesktopApp
• Contents:
  • Controllers/ (for API/MVC): Handles incoming requests and orchestrates responses.
  • Views/ (for MVC/Web Apps): User interface templates.
  • ViewModels/: Models specifically for the presentation layer.
  • Startup.cs or Program.cs (for configuration): Sets up dependency injection, routing, middleware.
  • ClientApp/: For single-page applications (React, Angular, Vue).

Summary of Layer Dependencies and File Structure

The following table summarizes the typical project/folder names and their contents, illustrating how the logical layers map to a physical file structure.

Practical Insights

• Separation of Concerns: Each project/folder has a clear, singular responsibility, making it easier to understand, develop, and debug specific parts of the system.
• Testability: Because the core Domain and Application layers do not depend on external infrastructure, they can be tested independently and easily using unit tests without needing a database or external services.
• Maintainability and Scalability: Changes in one layer (e.g., switching databases in the Infrastructure layer) have minimal impact on other layers, particularly the core business logic. This modularity makes the system more adaptable and scalable over time.
• Dependency Inversion: The file structure inherently supports the Dependency Inversion Principle, where high-level modules (Domain, Application) depend on abstractions (interfaces) rather than concrete implementations (in Infrastructure).

By adopting this structured approach, development teams can build robust, flexible, and easily maintainable software systems that are well-aligned with the core principles of Onion Architecture.