Skip to content

ADR#0045: Aggregate-Oriented Module Layout for Event-Sourced Services ​

Context ​

Several first-party services implement an event-sourced model: typed commands decide events, an evolve function folds events into state, snapshots compact that state, and read-side processors project the stream into runtime effects. trogon-scheduler and trogon-gateway both follow this shape.

ADR#0002 governs package boundaries but deliberately stops short of prescribing intra-package module structure. rsworkspace/crates/AGENTS.md governs value objects, boundary types, and errors, but describes a flat crate-root layout that fits value-object and library crates, not an event-sourced service.

With no rule, two failure modes appeared. First, code was organized by layer at the crate root: a top-level commands/ module in a crate that hosts more than one stream reads as "the crate's commands," when the commands actually belong to one specific stream among several. Second, aggregates were named after the mechanism rather than the domain: CredentialLifecycle* names describe that the type participates in an event-sourced lifecycle, which every event-sourced aggregate does by definition, so the qualifier carries no information and compensates for the fact that the opposing concern (the secret material) was never named on the same axis.

The repository needs one rule for how event-sourced code is organized and named, and a named reference implementation.

Decision ​

Organize event-sourced code by aggregate, not by layer. Name aggregates as bare domain nouns. trogon-scheduler is the reference implementation.

Organize by stream ​

The unit of organization is the stream, not a technical layer. Stream, aggregate, and workflow name that one unit from three angles: the aggregate is the consistency boundary that decides commands, the stream is that aggregate's event log, and the workflow is what the log captures over time. One aggregate, one stream, one module; wherever this ADR says "stream" or "aggregate" it means this same unit, never two different module boundaries. There is one module per stream, named for that stream. commands (with its nested state, snapshot, and domain submodules) and the read-side processor are subdivisions inside a stream, never top-level buckets that imply the whole crate is a single command model.

A stream module contains:

  • commands/: the write side. One file per command decider, named after the command; each file holds the command struct and its Decider implementation. The decider's Event is the generated proto type. Its State uses the generated state directly or the transparent wrapper described below. Neither introduces a parallel domain schema. The write-side submodules nest inside commands/:
    • commands/state: the state's no-history Default, its Evolve<Event> implementation, and the decide-time and evolve-time validators, operating on the proto state payload. Shared replay helpers used by the read side also belong here.
    • commands/snapshot: the snapshot policy only, for example the snapshot frequency. It does not contain the snapshot codec.
    • commands/domain: the aggregate's value objects used as command inputs, one type per file. The event and state shapes are proto, so this module holds value objects, not event or state definitions.
  • processor (or a named projection): the read model that consumes the stream. A processor's own rebuildable checkpoint store nests under that processor and is its adapter boundary: the store owns the persistence SDK calls, and projection logic above it stays SDK-free.
  • The aggregate's persistence and command handler: the event store, stream and subject configuration, and the handler that executes commands against the store. These belong to the aggregate and live inside its module, next to the commands they serve. They are not hoisted to the crate root.

A crate that owns exactly one aggregate places that aggregate at the crate root, so a root-level commands/ reads correctly (trogon-scheduler: the crate is the schedules aggregate). A crate that hosts multiple aggregates or bounded contexts nests each aggregate under its own noun module (trogon-gateway: the credential aggregate lives under credential/, separate from the webhook-ingress sources and the secret backends).

Name a stream for its workflow, as a noun ​

A stream is not always a static entity. More often it captures a workflow, a process that unfolds over time. Name the stream for that workflow, expressed as a noun: a workflow made noun. The name states which workflow the stream is, never that it happens to be event-sourced.

Do not qualify a stream with mechanism words such as Lifecycle, Manager, Service, or Handler. Every event-sourced stream has a lifecycle and is handled by something, so those words name the machinery, not the workflow, and carry no information. Lifecycle is the clearest offender: it restates the pattern.

Name opposing concerns on the same axis instead of qualifying one of them. A credential has two: the workflow that provisions and maintains it over time (request, activate, rotate, revoke), and its secret material. Name them Credential (the stream, event-sourced, holds no secret bytes) and Secret (the material, held by the secret store). Do not name the first CredentialLifecycle to distinguish it from the second; naming the second Secret already does that.

Value objects ​

Domain value objects for an aggregate live under that aggregate's commands/domain module, one file per type, with the construction and error rules from rsworkspace/crates/AGENTS.md. The flat src/{type}.rs placement in the crate conventions applies to value-object and library crates that own no aggregate. The read model depending on the aggregate's commands/domain is expected, not a layering violation.

Protobuf owns the event and state schemas; their codec lives in the proto crate ​

Generated proto messages define the event and state data shapes (ADR#0009). The decider's Event uses the generated message directly. Its State may also use the generated message directly when its Default represents no history and Rust's trait ownership rules permit the replay implementation.

A consuming crate may instead define a local, single-field #[repr(transparent)] state wrapper in commands/state, such as CredentialState(state_v1::CredentialStateSnapshot), to own the domain's Default and Evolve<Event> implementations, which automatically satisfy DeciderState<Event>. Default means the state before any events. A generated protobuf default can be an empty message with state: None or an unspecified enum value, while the aggregate starts in an explicit Missing state. Its derived Default cannot be replaced by another implementation. The orphan rule also prevents the consuming crate from implementing a foreign Evolve trait for a foreign generated state and event; the wrapper supplies a local state type while replay stays with the commands.

The wrapper contains only the generated message, without additional state fields or a parallel hand-written enum. Its From implementations only wrap and unwrap the message, and AsRef borrows it, without allocation, cloning, or serialization. StateSnapshot::Payload names that generated message, and SnapshotRead and SnapshotWrite keep using the generated payload type. The wrapper does not change the snapshot type name or persisted bytes. Manual proto-to-domain schema conversion remains prohibited.

The event and snapshot codecs, the EventEncode, EventDecode, EventType, SnapshotType, and SnapshotPayload* implementations, live in trogonai-proto on the generated types. This is forced by the orphan rule: both the trait (trogon-decider or trogon-decider-runtime) and the type (generated proto) are foreign to the consuming crate, so the impl must live in the crate that owns the proto type.

Register a per-domain cargo feature in trogonai-proto for each event-sourced domain (schedules, gateway), pulling in trogon-decider-runtime and any codec dependencies, and gating that domain's hand-written support module (codec, payload error types, oneof re-exports). The consuming crate enables that feature and uses the generated event and state payload, with any state wrapper limited to the behavior described above. trogon-scheduler with the schedules feature is the reference; its commands/snapshot.rs is only the policy const because the codec lives in trogonai-proto.

Domain stays free of infrastructure ​

Decision and projection logic in commands and processor is free of transport and persistence SDKs. What converts at the boundary per ADR#0009 is the transport and persistence envelope: adapters turn message frames, KV entries, and wire bytes into the proto event and state messages and the aggregate's value objects, and back. The event and persisted state payload stay the generated proto types; wrapping state for domain initialization and replay does not remap its fields or move its codec into the domain. Infrastructure adapters (NATS/JetStream stores, stream and subject configuration, KV stores) are thin and live inside the module that owns them, not scattered at the crate root: the event store and command handler next to the commands they serve, a processor's checkpoint store nested under that processor.

Design Rules ​

  • One command decider per file.
  • The decider's Event and persisted state payload are generated proto types. State may use the transparent wrapper described above to own Default and Evolve<Event>. Do not add parallel domain enums or hand-written schema conversion (ADR#0009).
  • The event and snapshot codec implementations live in trogonai-proto on the proto types, behind a registered per-domain feature that pulls in trogon-decider-runtime. The consuming crate's commands/snapshot module holds only the snapshot policy.
  • Keep the fold (evolve) separate from the snapshot policy.
  • Name a stream for the workflow it represents, expressed as a noun (a workflow made noun), not for the event-sourcing mechanism. Reject Lifecycle, Manager, Service, Info, and similar mechanism or filler qualifiers in stream, event, state, and command type names.
  • Persisted identifiers follow the aggregate noun: proto message names, stream names, subjects, and KV keys. Because a persisted message's package path or fully-qualified name is embedded in storage keys (ADR#0009), renaming an aggregate is a migration. Do it before the contract ships; treat it as storage-breaking afterward.
  • Value objects follow rsworkspace/crates/AGENTS.md, located under the aggregate's commands/domain.

Consequences ​

  • Event-sourced code is grouped by the thing it models, so a reader sees one aggregate's full write and read model in one place, and a multi-aggregate crate does not imply that one aggregate speaks for the whole crate.
  • Aggregate names carry domain meaning instead of restating the pattern. The credential aggregate is Credential; the secret material is Secret.
  • The value-object placement contradiction between rsworkspace/crates/AGENTS.md and real aggregate crates is resolved.
  • rsworkspace/crates/AGENTS.md gains a pointer to this ADR and to trogon-scheduler as the reference.
  • trogon-gateway migrates: the credential aggregate consolidates under credential/ with lifecycle dropped, and its event and snapshot codec moves out of credential/commands/ into trogonai-proto behind the gateway feature (which gains trogon-decider-runtime), so the deciders use the proto CredentialEvent and CredentialStateSnapshot payloads and the hand-written domain-enum conversion is removed. Domain-owned state initialization and replay can use the transparent wrapper defined above. Done before the contract ships.

References ​

Released under the Apache License 2.0.