Ranvier
KR Browse Docs

#Boundary Map โ€” Know Where to Be Rigid, Know Where to Be Flexible

Version: 0.33.0 Updated: 2026-03-15 Applies to: ranvier (all crates) Category: Philosophy & Architecture

Understanding the boundary between "core" (opinionated) and "edges" (flexible) is crucial for effective Ranvier usage.

#Core Territory (Opinionated โ€” Must Use Ranvier Paradigm)

These must use Transition/Outcome/Bus/Schematic:

  • Business logic: Use #[transition] for visualization, composition, testability
  • Data flow: Return Outcome<T, E> for type-safe error propagation
  • State sharing: Store in Bus for explicit dependencies
  • Pipeline composition: Use Axon::pipe(), .parallel() for Schematic graph generation
  • Domain errors: Define custom error enums for clear failure modes

#Edge Territory (Flexible โ€” Use Any Rust Tool)

These can use any Rust library or pattern:

  • HTTP server: Hyper, Tower, Axum, actix-web, warp
  • Database: sqlx, diesel, sea-orm, mongodb, postgres
  • Caching: redis, memcached, moka, dashmap
  • Serialization: serde_json, bincode, msgpack, protobuf
  • Metrics: prometheus, opentelemetry, statsd
  • Tracing: tracing, log, slog, env_logger
  • Async runtime: tokio, async-std, smol (Ranvier is runtime-agnostic)

#Gray Zones (Context-Dependent)

Some domains can go either way. Choose based on your needs:

#Middleware / Guards

Approach Best For
Transition-based New projects โ€” Schematic visualization, testable, composable
Tower middleware Existing Tower apps โ€” ecosystem reuse, team knowledge

#Error Handling

  • Inside Transitions: Always Outcome (required by #[transition])
  • Outside Transitions: Result is fine, convert at boundary

#State Management

  • Request-scoped data (auth, tenant): Bus (visualized in Schematic)
  • Global shared resources (DB pool, config): Framework state or Arc

#Rule of Thumb

  • Core (business logic, data flow, composition) โ†’ Ranvier paradigm
  • Edges (infrastructure, I/O, deployment) โ†’ Any Rust tool
  • Gray zones โ†’ Choose based on: visualization needs, team knowledge, migration path