#When to Use Ranvier vs Axum

Discussion: 249 | Date: 2026-03-28 | Status: Published

#Summary

Ranvier and Axum are both Rust web frameworks, but they serve different needs. This document helps you decide which to use — or when to use both together.

#Quick Decision Table

#When Axum is the Better Choice

1. Simple, stateless APIs

If your service is mostly request → database → response with minimal business logic, Axum's lightweight handler model is simpler and has less ceremony:

// Axum: 3 lines per endpoint
async fn get_user(Path(id): Path<u64>) -> Json<User> {
    Json(db.find_user(id).await.unwrap())
}

2. High-throughput edge services

Proxies, gateways, and load balancers where per-request overhead matters. Axum's zero-cost abstractions and Tower middleware stack are purpose-built for this.

3. Ecosystem breadth

Axum has a larger community, more middleware crates, and more tutorials. If your team is new to Rust web development, the learning resources are more abundant.

#When Ranvier is the Better Choice

1. Complex, multi-step business logic

When a request triggers a pipeline of 3+ steps with conditional branching, compensation, or streaming, Ranvier's Axon model makes the logic:

• Visible: The Schematic shows exactly what happens
• Auditable: Every decision is traced and inspectable
• Testable: Each Transition is independently unit-testable

// Ranvier: Complex order pipeline, fully inspectable
let order = Axon::typed::<OrderRequest, String>("order-saga")
    .with_saga_policy(SagaPolicy::Enabled)
    .then(validate_order)
    .then_compensated(reserve_inventory, release_inventory)
    .then_compensated(charge_payment, refund_payment)
    .then(complete_order);

2. Regulatory and compliance requirements

Industries that require audit trails, decision traceability, or process documentation benefit from Ranvier's Schematic extraction — your code structure IS your process documentation.

3. Long-running workflows

Saga compensation, retry with DLQ, checkpoint/resume — these patterns are first-class in Ranvier, not bolt-on middleware.

#Using Both Together

The recommended hybrid pattern: Axum serves HTTP, Ranvier processes logic.

use axum::{Router, Json, routing::post};
use ranvier_runtime::Axon;
use ranvier_core::prelude::*;

async fn handle_order(
    Json(request): Json<OrderRequest>,
) -> Json<serde_json::Value> {
    // Axum handles HTTP concerns (routing, parsing, response)
    // Ranvier handles business logic (saga, compensation, audit)

    let pipeline = Axon::typed::<OrderRequest, String>("order-saga")
        .with_saga_policy(SagaPolicy::Enabled)
        .then(validate_order)
        .then_compensated(reserve_inventory, release_inventory)
        .then_compensated(charge_payment, refund_payment)
        .then(complete_order);

    let mut bus = Bus::new();
    match pipeline.execute(request, &(), &mut bus).await {
        Outcome::Next(result) => Json(result),
        Outcome::Fault(err) => Json(serde_json::json!({"error": err})),
        _ => Json(serde_json::json!({"error": "unexpected"})),
    }
}

let app = Router::new().route("/api/orders", post(handle_order));

#When to use the hybrid approach

• Your team already has an Axum codebase and wants to add complex logic
• You want Axum's middleware ecosystem (Tower layers) for cross-cutting concerns
• You need Ranvier's Axon model only for specific complex endpoints

#When to use Ranvier standalone

• You're starting a new project where most endpoints have complex logic
• You want the built-in HTTP server (Ranvier::http()) with Guards
• You want unified Schematic extraction across all endpoints

#Feature Comparison

#Decision Flowchart

Is your service mostly CRUD?
  → Yes → Use Axum
  → No → Does it have 3+ step pipelines?
           → Yes → Does your team use Axum already?
                     → Yes → Hybrid (Axum + Ranvier)
                     → No → Ranvier standalone
           → No → Use Axum (or either)

#See Also

• cookbook_saga_compensation_patterns.md — Saga pattern deep dive
• cookbook_cascade_screening.md — Screening pattern cookbook
• cookbook_multi_step_pipeline.md — Pipeline pattern cookbook