Rust Hexagonal

Hexagonal Architecture for Rust Backends

Overview

Hexagonal Architecture (Ports & Adapters) isolates the domain from all external concerns. Nothing in domain or use cases ever imports an infrastructure crate.

Call flow (always this direction):

[ HTTP / CLI / gRPC ]  →  inbound  →  use case fns(ports...)  →  domain  →  port traits  →  outbound  →  [ DB / APIs / cache / email ]

Dependencies point inward only (enforced via Cargo.toml):

app → inbound  ─┐
                ├→ domain  (model + errors + ports + use cases)
app → outbound ─┘

Typical workspace shape is four crates + one binary:

1. domain — entities, value objects, errors, ports, use cases.
2. inbound — HTTP/gRPC/CLI adapters; depend only on domain.
3. outbound — DB/API/cache/email adapters; depend only on domain.
4. migration (or migrations) — schema migrations only.
5. app — binary; the only crate that knows all concrete types.

Is this still hexagonal? Yes. The invariant holds: domain/use cases never depend on infrastructure.

Merge use cases into domain, or keep a separate application crate?

async-trait rule: With Rust ≥ 1.75 and static dispatch, native async fn in traits is sufficient — no async-trait needed. Only add it if you explicitly need dyn Trait object safety.

Companion Skills

Load these skills when working on the corresponding layers:

These skills are authoritative for their layer. Prefer them over inline examples when detail is needed.

Workspace Structure

my-app/
├── Cargo.toml          # workspace root
├── domain/             # lib — model, errors, ports, use cases (Layout A)
├── inbound/            # lib — HTTP/gRPC/CLI adapters  (actix-web preferred; axum supported)
├── outbound/           # lib — DB/cache adapters (SeaORM v2)
├── migration/          # lib — DB migrations (some teams prefer name: migrations)
└── app/                # bin — sole composition root

Layout B adds an application/ crate between domain and app; domain then stays dep-free.

See folder structure & Cargo.toml templates.

Key Rules

Scaffold Checklist

Load only the reference for the layer you're working on:

Testing Strategy

See testing reference.

Recommended Crates

Common Pitfalls

• Domain importing infrastructure crates — domain/Cargo.toml must list no sea-orm, actix-web, axum, etc.
• Cross-adapter coupling — inbound and outbound must not import each other; enforced by their Cargo.toml.
• Handler holding a concrete service type — web::Data<OrderService<PgRepo>> leaks the concrete type. Keep handlers generic over traits and inject concrete types only in app.
• Unnecessary async-trait — only add it when you need dyn Trait. With static dispatch and Rust ≥ 1.75, remove it from port traits.
• mockall::automock on RPIT traits — #[automock] compile-errors when a trait method returns impl Trait in return position (e.g. async fn find_all() -> Result<impl Iterator<Item = T>, _>). Only annotate traits with concrete return types. For RPIT traits write a hand-written fake struct in a #[cfg(test)] block — see testing reference.
• Returning Vec<T> from collection ports — prefer impl Iterator<Item = T>; the adapter collects from DB internally but the interface stays flexible.
• Leaking SeaORM types into domain — Model, ActiveModel, column enums belong in outbound/src/db/. Map to domain structs in mappers.rs immediately.
• Bloated app/main.rs — extract fn wire_orders(db) helpers per bounded context; keep main under ~30 lines.
• Using .insert() in save() — always INSERT fails for existing records. Use an ON CONFLICT … DO UPDATE upsert (see outbound.md).
• find_all() without pagination — fetching entire tables into memory will OOM in production. Add page/limit or cursor parameters to collection port signatures before the table grows.
• Expanding AppRepository with every new trait — when adding a second bounded context (e.g. CustomerRepository), create a focused CustomerAppRepository supertrait rather than bolting it onto the existing one. Handlers that only handle orders should not receive a repo that also exposes customer operations.
• Treating DI shape as architecture law — hexagonal architecture does not require one AppState format. Prefer the shape that keeps adapter boundaries clear for your runtime and framework.

Scaling to Multiple Bounded Contexts

As the application grows beyond a single orders domain, organise by bounded context within each crate before splitting crates:

domain/src/
├── lib.rs              # pub mod orders; pub mod customers;
├── orders/
│   ├── mod.rs          # pub mod model; pub mod error; pub mod ports; pub mod use_cases;
│   └── …
└── customers/
    ├── mod.rs
    └── …

inbound/src/
├── state.rs            # separate AppRepository supertrait per context if needed
└── http/
    ├── orders/         # handlers, router, dto for orders
    └── customers/      # handlers, router, dto for customers

outbound/src/db/
├── orders/             # repository, entities, mappers
└── customers/

When to split into separate crates / microservices: