Ranvier
KR

#Ranvier Samples โ€” Official Example Track

Version: 0.43.0 Updated: 2026-04-08 Applies to: ranvier (facade) Category: Patterns & Examples

Use this page as the official learning order for Ranvier examples.

The goal is not to browse everything at once. The goal is to move through a small sequence that grows from basic pipeline structure to realistic backend shape, then to public reference apps.

#Official Track

#1. Hello World

Purpose:

  • Learn what a Transition, Axon, and Outcome look like in the smallest possible service.

Run:

cargo run -p hello-world

Expected:

  • server startup log
  • simple typed pipeline returning a greeting

Next:

#2. Tutorial: TODO API

Purpose:

  • Learn CRUD, typed request/response flow, and HTTP route wiring.

Run:

cargo run -p reference-todo-api

Expected:

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

Next:

#3. Order Pipeline

Purpose:

  • Learn multi-step workflow structure and how Ranvier models business flow more explicitly than a simple CRUD app.

Run:

cargo run -p order-processing-demo

Expected:

  • validation โ†’ inventory โ†’ payment โ†’ shipping flow
  • success and failure-path logs

Next:

  • admin-crud-demo

#Bridge Example

#4. Admin CRUD Demo

Purpose:

  • See a familiar admin-style backend after the official track: JWT login, SQLite, pagination, search, and OpenAPI.

Run:

cargo run -p admin-crud-demo

Expected:

  • POST /login
  • GET /departments
  • GET/POST/PUT/DELETE /users
  • GET /openapi.json
  • GET /docs

This example is the first answer to:

"What does a practical Ranvier admin backend look like?"

#Reference Apps

After the bridge example, move to reference apps depending on your goal.

#Reference Fullstack Admin

Purpose:

  • Public-only fullstack admin app with Ranvier backend and SvelteKit frontend.

Run:

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

#Reference E-commerce Order

Purpose:

  • Saga-heavy reference app with compensation, audit, and tenant-aware workflow shape.

Run:

cargo run -p reference-ecommerce-order

#Governance Example

#Request Governance Demo

Purpose:

  • Inspect the operability surface that is intentionally separate from OpenAPI: JWT auth, policy checks, audit logging, request-level observability, and RFC 7807-style errors.

Run:

cargo run -p request-governance-demo

Expected:

  • POST /login
  • POST /requests
  • POST /requests/:id/approve
  • 403 application/problem+json on insufficient-role approval
  • audit event writes

This example answers a different question than admin-crud-demo:

"What does a policy-heavy service with explicit error and observability wiring look like?"

#When To Use Which Surface

Surface Use it when
Official Track You are learning the Ranvier mental model in order
Bridge Example You want a practical admin-style backend shape
Reference Apps You want larger, public-facing example architectures
Governance Example You want explicit policy/error/observability wiring in one service
Examples Explorer You already know what kind of pattern you want to inspect