Onion Architecture

Onion Architecture

Use Onion Architecture to keep the domain model and application policy at the center of the system while infrastructure, frameworks, persistence, UI, and external services remain outside. Dependencies point inward; outer layers adapt to inner policy.

Onion Architecture is a dependency strategy, not a folder naming scheme. Apply it only where domain rules, lifespan, testability, or infrastructure volatility make the extra boundaries worth their cost.

Use When

Apply this skill when the work involves:

• A domain model with meaningful invariants, state transitions, value objects, aggregates, policies, or domain services.
• Application services or use cases that should coordinate workflows without depending on web, UI, database, queue, or SDK types.
• Persistence or integration details that should not shape domain APIs.
• Multiple delivery mechanisms invoking the same domain behavior.
• Tests that should exercise domain/application behavior without real infrastructure.
• A user or codebase explicitly uses Onion Architecture terminology.

Do not force it for:

• Simple CRUD with little domain behavior.
• Prototypes, scripts, migrations, one-off automations, or short-lived tools.
• Codebases where framework conventions are intentionally the architecture.
• Features that do not yet have enough policy, infrastructure volatility, or test pressure to justify concentric layers.
• Pass-through repositories, services, or interfaces that only rename one framework call.

Dependency Rule

• Inner layers must not depend on outer layers.
• Domain types must not mention frameworks, ORMs, request/response objects, database rows, UI components, queue payloads, SDK models, or transport errors.
• Application services may depend on domain types and inner abstractions for needed capabilities.
• Infrastructure implements inner abstractions at the edge.
• Data crossing inward should be shaped for domain/application needs, not copied directly from HTTP bodies, database rows, form state, or vendor payloads.

Typical Rings

Names vary by language and repository. Preserve local vocabulary when the dependency direction is healthy.

• Domain model: entities, value objects, aggregates, domain services, policies, invariants, calculations, state transitions, and domain events.
• Application layer: use cases, application services, command/query handlers, transaction orchestration, authorization handoff, and ports or repository abstractions needed by the workflow.
• Interface adapters: controllers, presenters, serializers, persistence mappers, queue adapters, API clients, and DTO translation.
• Infrastructure/frameworks: web frameworks, ORMs, databases, queues, cloud SDKs, filesystems, UI frameworks, dependency injection, process startup, and configuration wiring.

Workflow

1. Confirm the architecture earns its cost. Identify domain rules, expected lifetime, delivery mechanisms, infrastructure dependencies, and testing pain. Recommend a simpler design when those pressures are weak.
2. Inspect the current shape. Read modules, dependency direction, tests, framework conventions, and where domain decisions live. Do not rename a healthy architecture for terminology alone.
3. Choose a small boundary. Apply Onion Architecture to one bounded context, feature area, service, package, or workflow before proposing broad reorganization.
4. Move domain decisions inward. Put invariants and state changes in domain types or domain services, not controllers, ORM models, serializers, jobs, UI components, or SQL snippets by default.
5. Keep application orchestration separate. Let application services call domain behavior, coordinate transactions, invoke ports, and produce results. Do not let them absorb rules that belong in the domain model.
6. Define abstractions from inner needs. Create repositories, gateways, clocks, ID generators, clients, or messaging ports only when application or domain policy needs a boundary.
7. Map at the edge. Translate request DTOs, database rows, SDK objects, framework errors, and transport responses at adapter boundaries.
8. Wire outside-in. Construct concrete infrastructure in composition roots, dependency-injection wiring, factories, framework setup, or process startup.

When implementation begins, load the matching language engineering skill and any data skill needed for persistence, schema, query, or transaction work.

Verification And Reporting

Before reporting completion, check the changed behavior, ring boundaries, and inward dependencies; then run broader repository checks when the change warrants them. Report failures, skipped checks, and residual risk from unverified edge adapters, mappings, or composition wiring.

Testing Guidance

• Test domain entities, value objects, aggregates, and domain services directly.
• Test application services with fake or in-memory repositories, gateways, clocks, ID generators, and external-service ports.
• Test adapters against real framework, database, serialization, queue, or SDK contracts.
• Add dependency-direction checks when the language or build system can enforce them cheaply.
• Use end-to-end tests for critical wiring only where narrower tests cannot prove the behavior.

Relationship To Other Skills

• DDD: Onion Architecture is often a good fit when domain-driven-design has identified a domain model worth protecting. DDD supplies the language and invariants; Onion supplies dependency direction around them.
• Clean Architecture: Clean and Onion overlap heavily. Load clean-architecture when use cases, interactors, presenters, and interface-adapter responsibilities are the clearer framing. Prefer Onion when the domain model and concentric domain/application rings are the main concern.
• Hexagonal Architecture: Load hexagonal-architecture when external actors, inbound/outbound ports, adapters, swappable infrastructure, or headless core execution dominate the design.
• BDD: Use behavior-driven-development to describe observable behavior at the public API, use-case, or application boundary without exposing private layers.
• TDD: Use test-driven-development to drive domain rules and application workflows before real infrastructure exists.

Language Notes

• Rust: use crate/module boundaries, visibility, traits, enums, and newtypes to make inward dependencies explicit. Keep Tokio, SQLx, Axum, Leptos, and SDK types outside the domain model.
• Python: use modules, dataclasses, protocols, explicit constructors, and thin adapters. Keep Pydantic, ORM, FastAPI, Django, Click, or SDK types at boundaries unless the project intentionally treats them as its product shell.
• JavaScript/TypeScript: use module boundaries, discriminated unions, runtime validation at trust boundaries, and adapter modules. Keep framework, generated client, request, response, and UI component types out of core domain APIs.

Anti-Patterns

• Treating Onion Architecture as folders named domain, application, and infrastructure while dependencies still point outward.
• Creating repository or service interfaces for every class without a real domain, infrastructure, or testing need.
• Letting ORM entities, active records, DTOs, API payloads, or generated SDK types become the domain model by default.
• Placing all behavior in application services while domain entities only store data.
• Hiding business policy in mappers, repositories, SQL, controllers, UI components, or framework hooks.
• Applying the same layer count to every feature regardless of complexity.

Successful Use

The final design names the protected domain model, application services, inner abstractions, adapters, mapping points, dependency direction, tests per boundary, and any deliberate decision to keep part of the codebase simpler.