Rust Architect

Philosophy

We try to follow a Domain Driven Design (DDD) approach with hexagonal architecture (aka ports and adapters) with some opinionated decisions. We try to follow clean architecture and we give a lot of importance to tests.

Layers

We structure our code in three layers: application, domain, and infrastructure.

Application Layer

This is the entry point to the application, the most common case will be http controllers but it can also be a CLI application, subscribers (message consuming from a queue system), etc. The main responsibility of this layer is to VALIDATE entry data and TRANSFORM it into Value Objects (VO). In the case of http this layer is the one responsible of parsing HTTP requests, validating the data and returning HTTP errors if not valid, transforming into VO and calling the domain layer, in the case that this the method needs to return a response it will transform the domain response into a response DTO and return it to the caller with the correct HTTP status code.

Domain Layer

This is where the core BUSINESS LOGIC of the application lives. It is composed of entities, value objects, domain services, and domain events. The main responsibility of this layer is to implement the business rules and logic of the application and ORCHESTRATE calls to the ports in the infrastructure layer. We need to try to not depend on any external libraries or frameworks but some concessions could be done.

Infrastructure Layer

This layer is responsible for implementing ports and COMMUNICATING WITH EXTERNAL SYSTEMS. Most of the time we will be coding repositories to access the database, but external clients to external APIs should be implemented here too. As a convention, even if this is not entirely correct bc this should go in the domain layer, we will place the trait of the repository here, near the implementation bc it's convenient when adding new methods to the repository. repositories/ holds one aggregate's dedicated port implementation (a port injected into a single aggregate's domain service); shared/ holds infra usable across aggregates, regardless of whether it's a port (e.g. the clock, domain events) — see the file structure below. We must not hide behaviour in this layer, repositories should be as simple as possible and should behave like collections with methods like find, find_by_id, save, delete, etc. The domain layer should be the one that implements the business logic, rules and entity transformations, not the infrastructure layer. The infrastructure layer should be as simple as possible and should not contain any business logic like domain event publishing, it should only contain the operations on entities and optional monitoring. Write operations such as save, insert, update should have the entity as a parameter, not the properties. Delete could operate on the entity identifier instead of the entity itself and read methods such as find(id), find_all, etc should always return entities or collections of entities.

File Structure and Naming and other opinions

We try to organize our domain code into modules with the aggregate name as module name. This is an example of how we would structure the code:

src/
  domain/
    <aggregate>/
      <value_object>.rs   # one file per value object, named after the type
      <entity>.rs         # named after the type, even if it repeats the folder name
      errors.rs           # every error type for this aggregate, together
    services/              # every aggregate's use-case services, together, flat
      <use_case>.rs         # one domain service per use case, e.g. widget_creator.rs
  application/              # every external entry point (adapters), one subfolder per interface
    http/  (or grpc/, etc.)
      mod.rs                 # ApiServices + router wiring only
      error.rs               # ApiError + From<ValidationError>
      blocking.rs            # run_blocking
      validation.rs          # required() + shared missing-field messages
      <resource>/
        mod.rs                # handlers only
        dto.rs                # request/response wire types + From<Domain> conversions
    cli/                      # only if the project has a CLI
      mod.rs                  # Cli/Commands definitions (this is the CLI's "routing")
      <command>.rs             # one file per command's orchestration
    subscribers/              # event subscribers, one file per subscriber
      <subscriber>.rs
    tasks/                    # scheduled/background task handlers, one file per task
      <task>.rs
  infrastructure/
    repositories/            # one aggregate's dedicated port implementation
      <implementation>_<port>.rs   # trait + its implementation, together
    client/                  # port-shaped adapters nothing in domain/ injects
      <port>.rs
    shared/                  # infra usable across aggregates (ports or not)
      <thing>.rs

• We prefer not generic names: not entity.rs, not value_objects.rs, not ports.rs. A file is named after the single type/concept it holds (user.rs holds User, user_id.rs holds UserId).

• errors.rs is the one deliberately generic name: every error type for an aggregate (use-case error enums) lives together in one file, not scattered across the files that raise them.

• Every value object constructor fails with the single shared ValidationError(String) (domain/shared/errors.rs), never a per-VO error type. The application layer maps it once (e.g. impl From<ValidationError> for ApiError → 400), so handlers build VOs with a plain ?.

• Every value object gets its own file. Don't bundle multiple value objects into one "value objects" file.

• A port is named after the concept it fronts, not the one method it happens to expose (WidgetRepository, not WidgetLookup, even if today it only has an exists method). "Repository" is used loosely for "adapter implementing a domain port," not strictly persistence.

• infrastructure/repositories/ files are named <implementation>_<port>.rs (sqlite_playlist_repository.rs implements PlaylistRepository with SQLite, youtube_video_downloader_repository.rs implements VideoDownloaderRepository against YouTube/yt-dlp). The prefix signals which technology backs the port. infrastructure/shared/ and infrastructure/client/ files are named after the port/thing itself, not this convention, since they aren't per-aggregate repositories.

• A repository/port method either reads (returns anyhow::Result<Entity> / anyhow::Result<Vec<Entity>> / anyhow::Result<Option<Entity>>, an entity or collection, never a wrapper/outcome enum) or writes (returns anyhow::Result<()>, void on success). No custom infra error types (RepositoryError/LookupError and friends), infra failures are untyped anyhow::Error. A Repository always returns the entities that its name implies (UserRepository returns User).

• Business-meaningful outcomes that look like they belong in the repository (e.g. "was this newly created, or did it already exist?") are decided in the domain service, not returned by infra: call find, branch on Some/None, then call insert/save. This trades DB-level atomicity for keeping business logic out of infra, a known, accepted race window, not an oversight.

• State transitions live on the entity, never as behavior-named repository methods or as anemic domain models operated from domain service. We prefer immutable state transitions: a transition method takes self by value and returns a new Self (via struct-update syntax, Self { field: new_value, ..self }) rather than mutating &mut self. Name such a method with_<field> when it simply sets one field (e.g. with_thumbnail); reserve a verb-based name (mark_downloaded, start_download, reset_for_redownload) for a transition that carries additional domain meaning beyond "set this field".

• Fn ordering: within any impl block, and among free functions in a file, order is: new (if it exists), then every pub method or trait-impl method (trait-impl methods are the type's public surface even without the pub keyword), then private/helper methods. This applies uniformly, no exceptions — including repositories' row_to_* mapping helpers, which go after the trait-impl methods they support, not before.

• Domain service layout: every domain service file is laid out in four blocks, top to bottom, so a reader meets the contract before the implementation:

  1. The struct holding its dependencies, followed by an inherent impl with only new.
  2. The service's interface: a pub trait <Service>Api: Send + Sync declaring every public operation (doc comments describing the contract go here, on the trait method, not on the impl).
  3. impl <Service>Api for <Service> with the implementation of those operations.
  4. A second inherent impl <Service> holding every private helper, never pub.

  Guideline (not a hard rule): every public operation (block 3) should read at a glance — aim for 10–15 lines of body after rustfmt. It reads as a sequence of named steps (let channel = self.find_channel(&id)?; self.delete_channel_videos(&id)?; ...), each step a private helper in block 4 named for what it does. Lookup-or-fail matches, multi-arm outcome handling, event building and repeated map_err chains are the usual candidates to extract. When two arms or two operations share logic (e.g. marking a failed download as errored), extract it once rather than shrinking each copy. Exceptions are fine for genuinely complex flows (e.g. reconciliation) where splitting further would scatter one coherent algorithm across helpers that only make sense together — prefer readability over the line count.

  Callers keep depending on the concrete service type (State<PlaylistCreator>, video_downloader: VideoDownloader) and just use the …Api trait to call it; the trait exists to make the contract readable, not to add dynamic dispatch. Supporting types the service returns (e.g. an outcome enum) and constants go above the struct.

  pub struct WidgetCreator {
      repository: Arc<dyn WidgetRepository>,
  }
  
  impl WidgetCreator {
      pub fn new(repository: Arc<dyn WidgetRepository>) -> Self {
          Self { repository }
      }
  }
  
  pub trait WidgetCreatorApi: Send + Sync {
      fn create(&self, id: WidgetId) -> Result<Widget, CreateWidgetError>;
  }
  
  impl WidgetCreatorApi for WidgetCreator {
      fn create(&self, id: WidgetId) -> Result<Widget, CreateWidgetError> {
          self.ensure_absent(&id)?;
          // ...
      }
  }
  
  impl WidgetCreator {
      fn ensure_absent(&self, id: &WidgetId) -> Result<(), CreateWidgetError> {
          // ...
      }
  }

• Read models (*View, e.g. TaskView, ChannelView) hold the flat fields they expose, not the entity they're derived from.

• Domain services are call-agnostic: they know nothing about HTTP, CLI, subscribers, or tasks. Adapting any external trigger into a domain call — parsing/validating input, invoking the domain service, mapping its result back — is the application layer's sole responsibility.

HTTP Handlers

• A handler extracts only the service(s) it uses (State<PlaylistCreator>), never the whole ApiServices. ApiServices derives FromRef so axum resolves the sub-state.
• Handlers return typed results, never an opaque Response: Result<(StatusCode, Json<T>), ApiError> when the status varies, Result<Json<T>, ApiError> for a plain 200, Result<StatusCode, ApiError> for bodiless responses.
• Every failure is an ApiError (status + message, rendered as {"error": ...}). Input is validated with ? only: VOs via From<ValidationError>, missing fields via required(request.field, MISSING_X)? (http/validation.rs).
• Domain errors are mapped explicitly per variant (Err(e @ CreateChannelError::Lookup(_)) => Err(ApiError::new(StatusCode::BAD_GATEWAY, e))), no catch-all arm. A mapping repeated across handlers gets one small function.
• Every service call goes through run_blocking (http/blocking.rs), since services are synchronous (SQLite, blocking HTTP). Don't judge per call whether it's needed.
• Response DTOs are flat and carry only the fields their consumers use. Never compose one resource's response by wrapping or #[serde(flatten)]-ing another response DTO. A genuinely nested JSON object (e.g. a video's source) gets its own DTO.

Testing

Tests are classified by where they enter the code, not by what they fake. Our goal is to couple our tests as much as possible to behaviour instead of implementation, so we can refactor the code without breaking the tests.

• Acceptance tests: enter through an application adapter (HTTP handler, event subscriber, task). The default and by far the most numerous kind.
• Behaviour tests: enter through a domain service directly. The exception, reserved for domain logic too complex to cover through an adapter.
• Value object tests: exhaustive validation rules, one file per value object.
• Infrastructure tests: a single adapter (repository, client) against its real dependency.

Acceptance and behaviour tests follow the same rules for persistence and test doubles (see below): persistence is real, only external dependencies are faked. The Playwright suite in smoke-tests/ is the true end-to-end layer (real binary, real browser) and lives outside these conventions.