Architecture Decision Checklist

Walk this checklist when bootstrapping or restructuring a Rust codebase so crate boundaries, errors, and tooling are deliberate before inertia sets in.

How to Use This Checklist

Complete foundation tier before writing feature code.
Record each choice in README or ADR with owner.
Revisit after first production traffic.

Foundation

Toolchain: Pin Rust 1.97.0, edition 2024, rust-toolchain.toml committed.
Layout: Workspace with domain, api, infra crates vs single crate (justify in ADR).
Package manager policy: Cargo.lock committed for applications.
MSRV: rust-version = "1.97" in manifests; CI matrix matches.
Lint policy: fmt --check, clippy -D warnings, documented in CONTRIBUTING.

Boundaries

Domain purity: No axum/sqlx imports in domain crate.
HTTP layer: Axum 0.8 handlers thin; call domain services.
Persistence: Repository traits in domain; sqlx 0.8 impl in infra.
Errors: thiserror domain errors; map to HTTP in api crate.
Config: Typed settings from env; secrets from platform store.

Quality and Ops

Testing: Unit domain, integration HTTP, sqlx migrations in CI.
Observability: tracing JSON logs, health/readiness routes.
Graceful shutdown: SIGTERM handling with drain timeout.
Migrations: sqlx migrate or flyway-style job; not only at startup.
Deploy artifact: Release binary in minimal container or static where fit.

FAQs

Skip workspace for MVP?

Acceptable short-term; plan extraction ADR before second team joins.

When Polars?

Separate worker crate if analytics path; not inside request hot path by default.

Feature flags?

Cargo features for compile-time; runtime flags via config service.

docs structure?

ARCHITECTURE.md links to this checklist completion date.

open source?

LICENSE, SECURITY.md, CODE_OF_CONDUCT in foundation tier.

multi-binary?

Workspace members per binary sharing domain crate.

proto API?

Add tonic crate member; REST and gRPC share domain.

auth tier?

Add JWT middleware decision before public launch.

rate limits?

tower Governor/Redis limiter at edge decision.

completion sign-off?

Staff engineer tick + date in ARCHITECTURE.md.

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Foundation

Toolchain: Pin Rust 1.97.0, edition 2024, rust-toolchain.toml committed.

Layout: Workspace with domain, api, infra crates vs single crate (justify in ADR).

Package manager policy: Cargo.lock committed for applications.

MSRV: rust-version = "1.97" in manifests; CI matrix matches.

Lint policy: fmt --check, clippy -D warnings, documented in CONTRIBUTING.

Quality and Ops

Testing: Unit domain, integration HTTP, sqlx migrations in CI.

Observability: tracing JSON logs, health/readiness routes.

Graceful shutdown: SIGTERM handling with drain timeout.

Migrations: sqlx migrate or flyway-style job; not only at startup.

Deploy artifact: Release binary in minimal container or static where fit.

FAQs

Skip workspace for MVP?

Acceptable short-term; plan extraction ADR before second team joins.

When Polars?

Separate worker crate if analytics path; not inside request hot path by default.

Feature flags?

Cargo features for compile-time; runtime flags via config service.

docs structure?

ARCHITECTURE.md links to this checklist completion date.

open source?

LICENSE, SECURITY.md, CODE_OF_CONDUCT in foundation tier.

multi-binary?

Workspace members per binary sharing domain crate.

proto API?

Add tonic crate member; REST and gRPC share domain.

auth tier?

Add JWT middleware decision before public launch.

rate limits?

tower Governor/Redis limiter at edge decision.

completion sign-off?

Staff engineer tick + date in ARCHITECTURE.md.

Architecture Decision Checklist

Buscar en la documentación

Architecture Decision Checklist