Examples

Learn by example.

Explore categorized examples covering core concepts, HTTP routing, auth, persistence, observability, and protocol adapters. Each card links to the full source in the GitHub repository.

Learning Paths

Follow a guided path from beginner to advanced.

Build your first Axon workflow in under 30 minutes.

1. hello-world2. typed-state-tree3. basic-schematic4. outcome-variants5. testing-patterns

Build production HTTP APIs with routing, auth, and real-time features.

1. typed-json-api2. reference-todo-api3. admin-crud4. reference-chat-server

Master resilience, persistence, and enterprise patterns.

1. order-processing2. bus-capability3. persistence4. retry-dlq5. reference-ecommerce-order

Apply explicit request governance and connect a maintained full-stack reference.

1. request-governance-demo2. reference-fullstack-admin

Official Example Track

This is the official learning order. Start with Hello World, then move through CRUD and workflow examples before the bridge/reference surfaces.

Minimal Flat API example — chain transitions to build and transform a greeting.

~5 min

Run

cargo run -p hello-world

Expected

server startup log
simple greeting response

#[transition]
async fn greet(input: String) -> Outcome<String, String> {
    Outcome::Next(format!("Hello, {input}!"))
}

Complete CRUD application with JWT authentication, Bus dependency injection, HTTP routing, and collection-based testing.

~30 min

Run

cargo run -p reference-todo-api

Expected

POST /login
GET/POST/PUT/DELETE /todos

// Single-transition Axon circuits per endpoint
POST /login   -> [login]       -> JWT token
GET  /todos   -> [list_todos]  -> Vec<Todo>
POST /todos   -> [create_todo] -> Todo
PUT  /todos/:id  -> [update_todo] -> Todo
DELETE /todos/:id -> [delete_todo] -> { deleted }

Domain-driven workflow: validation, payment, inventory reservation, and shipping.

~20 min

Run

cargo run -p order-processing-demo

Expected

validation -> inventory -> payment -> shipping flow
success and failure-path logs

Axon::new("order")
    .then(validate_order)
    .then(process_payment)
    .then(reserve_inventory)
    .then(arrange_shipping)

Bridge & Reference

Continue from the official track into the admin-style bridge backend and the public-only reference app.

Bridge example: JWT login, SQLite-backed admin CRUD, pagination/search, and OpenAPI in one mid-sized backend.

~35 min

Run

cargo run -p admin-crud-demo

Expected

JWT login
users CRUD
OpenAPI JSON
Swagger UI parity

Ranvier::http()
    .post_typed_json_out("/login", login)
    .get_json_out("/users", list_users)
    .post_typed_json_out("/users", create_user)
    .put_typed_json_out("/users/:id", update_user)
    .delete_json_out("/users/:id", delete_user)

Public-only fullstack reference app with a Ranvier backend, SvelteKit frontend, JWT login, dashboard, and user administration.

~40 min

Run

cargo run -p reference-fullstack-admin
cd examples/reference-fullstack-admin/frontend && npm install && npm run dev

Expected

backend login/dashboard/users surface
frontend login/dashboard/users surface

Ranvier::http()
    .guard(CorsGuard::<AppState>::permissive())
    .post_typed_json_out("/login", login)
    .get_json_out("/dashboard", dashboard)
    .get_json_out("/users", list_users)

Complete Saga pipeline with compensation, audit trail, multi-tenancy, and RFC 7807 errors.

~40 min

Run

cargo run -p reference-ecommerce-order

Expected

saga compensation flow
order reference app surface

// Saga: CreateOrder → ProcessPayment → ReserveInventory → ScheduleShipping
//          ↓ (comp)          ↓ (comp)
//      RefundPayment    ReleaseInventory

Canonical WebSocket reference: multi-room chat with JWT auth, REST + WS hybrid routing, health/readiness probes, and graceful shutdown.

~35 min

Run

cargo run -p reference-chat-server

Expected

health/ready/live probes
unauthenticated websocket auth_failed frame
authenticated join/history/message websocket flow

Governance & Operability

Separate from the OpenAPI surface, inspect a service that combines structured errors, audit logging, and guard-backed observability in one operability example.

Cross-cutting backend example combining JWT auth, policy checks, audit logging, SQLite persistence, and RFC 7807-style errors.

~30 min

Run

cargo run -p request-governance-demo

Expected

403 application/problem+json on insufficient-role approval
200 on approver approval
audit event writes

Ranvier::http()
    .post_typed_json_out("/login", login)
    .post_typed_json_out("/requests", create_request)
    .get_with_error("/requests/:id", get_request, governance_error_response)
    .post_with_error("/requests/:id/approve", approve_request, governance_error_response)

All Examples

17 examples match the current filters.

Default filter: Core examples

Minimal Flat API example — chain transitions to build and transform a greeting.

~5 min

Run

cargo run -p hello-world

Expected

server startup log
simple greeting response

#[transition]
async fn greet(input: String) -> Outcome<String, String> {
    Outcome::Next(format!("Hello, {input}!"))
}

Type-safe decision flows using Rust enums with Axon, Transition, and Outcome.

~10 min

let flow = Axon::new("flow")
    .then(validate)
    .then(process);

Axon flow visualization with schematic extraction for debugging and documentation.

~10 min

Domain-driven workflow: validation, payment, inventory reservation, and shipping.

~20 min

Run

cargo run -p order-processing-demo

Expected

validation -> inventory -> payment -> shipping flow
success and failure-path logs

Axon::new("order")
    .then(validate_order)
    .then(process_payment)
    .then(reserve_inventory)
    .then(arrange_shipping)

Declarative allow/deny access control via @transition bus attributes.

~15 min

#[transition(bus_allow = "db,cache")]
async fn fetch(input: Req) -> Outcome<Resp, String> { .. }

All 5 Outcome variants: Next (linear), Fault (error), Branch (conditional), Jump (loop), Emit (side-effect).

~15 min

// Outcome<T, E> — control flow as data
Outcome::Next(value)       // linear progression
Outcome::Fault(err)        // error path
Outcome::Branch("name", v) // conditional routing
Outcome::Jump("node", v)   // goto / loop
Outcome::Emit(event)       // side-effect event

Type-safe JSON endpoints using get_json_out, post_typed_json_out, BusHttpExt, and CorsGuard::permissive().

~20 min

Ranvier::http()
    .get_json_out("/items", list_items_axon)
    .post_typed_json_out::<CreateItem, _, _>("/items", create_item_axon)
    .delete_json_out("/items/:id", delete_item_axon)

Bridge example: JWT login, SQLite-backed admin CRUD, pagination/search, and OpenAPI in one mid-sized backend.

~35 min

Run

cargo run -p admin-crud-demo

Expected

JWT login
users CRUD
OpenAPI JSON
Swagger UI parity

Ranvier::http()
    .post_typed_json_out("/login", login)
    .get_json_out("/users", list_users)
    .post_typed_json_out("/users", create_user)
    .put_typed_json_out("/users/:id", update_user)
    .delete_json_out("/users/:id", delete_user)

Workflow crash recovery, checkpointing, and compensation hooks.

~20 min

Axon::new("resilient")
    .then(step_a)
    .then(step_b)
    .with_persistence(store)
    .with_compensation(rollback);

Automatic span generation in transitions with Traced wrapper and ConnectionBus.

~20 min

Unit and integration testing strategies for Transitions and Axon chains.

~15 min

DLQ retry with exponential backoff, timeout patterns, and circuit breaker.

~25 min

let axon = Axon::new("payment")
    .then(gateway)
    .with_dlq_policy(DlqPolicy::RetryThenDlq {
        max_attempts: 5,
        backoff_ms: 100,
    })
    .with_dlq_sink(dlq);

Cross-cutting backend example combining JWT auth, policy checks, audit logging, SQLite persistence, and RFC 7807-style errors.

~30 min

Run

cargo run -p request-governance-demo

Expected

403 application/problem+json on insufficient-role approval
200 on approver approval
audit event writes

Ranvier::http()
    .post_typed_json_out("/login", login)
    .post_typed_json_out("/requests", create_request)
    .get_with_error("/requests/:id", get_request, governance_error_response)
    .post_with_error("/requests/:id/approve", approve_request, governance_error_response)

Complete Saga pipeline with compensation, audit trail, multi-tenancy, and RFC 7807 errors.

~40 min

Run

cargo run -p reference-ecommerce-order

Expected

saga compensation flow
order reference app surface

// Saga: CreateOrder → ProcessPayment → ReserveInventory → ScheduleShipping
//          ↓ (comp)          ↓ (comp)
//      RefundPayment    ReleaseInventory

Canonical WebSocket reference: multi-room chat with JWT auth, REST + WS hybrid routing, health/readiness probes, and graceful shutdown.

~35 min

Run

cargo run -p reference-chat-server

Expected

health/ready/live probes
unauthenticated websocket auth_failed frame
authenticated join/history/message websocket flow

Public-only fullstack reference app with a Ranvier backend, SvelteKit frontend, JWT login, dashboard, and user administration.

~40 min

Run

cargo run -p reference-fullstack-admin
cd examples/reference-fullstack-admin/frontend && npm install && npm run dev

Expected

backend login/dashboard/users surface
frontend login/dashboard/users surface

Ranvier::http()
    .guard(CorsGuard::<AppState>::permissive())
    .post_typed_json_out("/login", login)
    .get_json_out("/dashboard", dashboard)
    .get_json_out("/users", list_users)

Complete CRUD application with JWT authentication, Bus dependency injection, HTTP routing, and collection-based testing.

~30 min

Run

cargo run -p reference-todo-api

Expected

POST /login
GET/POST/PUT/DELETE /todos

// Single-transition Axon circuits per endpoint
POST /login   -> [login]       -> JWT token
GET  /todos   -> [list_todos]  -> Vec<Todo>
POST /todos   -> [create_todo] -> Todo
PUT  /todos/:id  -> [update_todo] -> Todo
DELETE /todos/:id -> [delete_todo] -> { deleted }

All examples live under ranvier/examples in the GitHub repository. Clone and run with cargo run -p <package>.

Learn by example.

Learning Paths

Quick Start

HTTP Services

Advanced Patterns

Governance and Full Stack

Official Example Track

Hello World

Reference Todo API

Order Processing Workflow

Bridge & Reference

Admin CRUD Demo

Reference Fullstack Admin

Reference E-commerce Order

Reference Chat Server

Governance & Operability

Request Governance Demo

All Examples

Hello World

Typed State Tree

Basic Schematic

Order Processing Workflow

Bus Capability System

Outcome Variants

Typed JSON API

Admin CRUD Demo

Crash Recovery & Persistence

Traced Wrapper

Testing Patterns

Retry & Dead Letter Queue

Request Governance Demo

Reference E-commerce Order

Reference Chat Server

Reference Fullstack Admin

Reference Todo API