Skip to content
rusthacks.dev
Architecture

Clean Architecture in Rust and How Much of It You Need

Clean architecture's dependency rule fits Rust: inner layers define traits and outer layers implement them. Here is how many layers you need, with a layout and a verdict.

2 min read
Summarize in AI
Flat illustration for the post “Clean Architecture in Rust and How Much of It You Need”, composed around memory.

Clean architecture comes with a diagram of concentric circles, and it is easy to build the circles and miss the point. The point is one rule: dependencies point inward. Rust makes that enforceable in a way few languages do, because a crate that depends on another cannot be depended on back. This post maps the layers to Rust, and says which ones to skip. It follows hexagonal architecture and fits in organizing Rust projects.

Rust 1.90, edition 2024.

The layers, mapped

LayerContainsMay depend on
Domainentities, value objects, domain rulesnothing but std
Applicationuse cases, port traitsdomain
InfrastructureSQLx repositories, HTTP clients, queue workersapplication, domain
InterfaceAxum handlers, CLI, wiring in mainall of the above

A workspace gives the strongest enforcement:

Text
crates/
  domain/          no dependencies
  application/     depends on domain
  infrastructure/  depends on application
  api/             binary, depends on all

If someone writes use sqlx::PgPool in domain, Cargo refuses, because the crate does not list sqlx. That is a build error instead of a review comment.

A use case

rust
// crates/application/src/lib.rs
use domain::{Email, User};

pub trait Users {
    fn by_email(&self, e: &Email) -> Option<User>;
    fn save(&self, u: &User);
}

pub fn change_email(users: &impl Users, current: &Email, new: Email) -> Result<(), &'static str> {
    let mut user = users.by_email(current).ok_or("no such user")?;
    if users.by_email(&new).is_some() {
        return Err("email already taken");
    }
    user.email = new;
    users.save(&user);
    Ok(())
}

The use case depends on a trait it owns. infrastructure implements Users; api plugs it in. Tests use an in-memory implementation. Real signatures would be async and return Result.

What costs more than it returns

  • Mapping between layers. A UserRow, a User and a UserResponse triple the code for a CRUD table. Use the domain type directly in the response when they are the same.
  • One trait per entity. A trait is justified by a second implementation or a test double, not by symmetry.
  • Four crates for 800 lines. Modules in one crate enforce nothing, but cost nothing; start there.

A pragmatic version

Keep a domain module without framework imports, a services module with the traits, and an infra module. Check imports in review. When the codebase or team grows, move the modules to crates.

Verdict

Keep the dependency rule, test doubles through traits and thin handlers. Drop layers that only forward calls. The rules in dependency inversion with traits say how far to go with traits, and the discussion of errors across layers is in error boundaries. The original article is Robert Martin's Clean Architecture post.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.