Documentation
Guides, tutorials, and references.
Browse the documentation by category. Each guide is self-contained and includes code examples with syntax highlighting.
Featured
Quickstart
Install and run your first pipeline in 5 minutes.
Tutorial
Build a circuit with CLI schematic and VSCode workflow.
Getting Started
Interactive overview with code examples and learning paths.
Examples Explorer
68 published workspace examples with filters and source code.
Pattern Catalog
12 battle-tested patterns with live code.
Capability Board
Live module status, versioning, and verification.
Getting Started
Quickstart
Install Ranvier and run your first typed pipeline in under 5 minutes.
Hello World
Build your first Transition and Axon pipeline from scratch.
Tutorial: TODO API
Build a complete REST API with JWT auth, CRUD, and guards.
Getting Started Guide
Complete onboarding guide covering concepts, setup, and first project.
Getting Started Overview
Interactive overview: build your first pipeline with code examples and learning paths.
Tutorial
Step-by-step tutorial: hello-world, CLI schematic, VSCode extension workflow.
Deep Tutorial: Payment Pipeline
End-to-end payment saga with compensation, branching, schematic diff, and testing.
Philosophy & Architecture
Introduction
Ranvier is a Typed Decision Engine โ execution, structure, control flow.
Philosophy Overview
Opinionated Core, Flexible Edges โ the guiding philosophy.
PHILOSOPHY.md
Full philosophy document from the Ranvier repository.
Design Principles
Architecture Decision Records (ADR) for core design choices.
Core Paradigm
The Four Pillars: Transition, Outcome, Bus, Schematic.
Why Opinionated Core?
Identity, learning curve, and consistency through constraints.
Why Flexible Edges?
Ecosystem integration, gradual migration, user autonomy.
Boundary Map
Where core ends and edges begin.
Decision Framework
Choose between Ranvier way, ecosystem way, or hybrid approach.
Code Examples
Real-world patterns: pure Ranvier, Tower integration, hybrid, e-commerce.
Guides
Bus Access Patterns
Decision tree for read(), get(), require(), and try_require() methods.
Persistence Ops Runbook
Checkpoint recovery, PostgreSQL/Redis store setup, and compensation hooks.
OTel Ops Playbook
OpenTelemetry collector configuration, trace export, and metrics setup.
Security Hardening
SQL injection prevention, timing-safe auth, error redaction, and OWASP coverage.
Production Readiness Checklist
Pre-deployment checklist: auth, security, observability, resilience, and CI/CD.
Auth Comparison
Transition-based vs Tower-based authentication: 7-feature comparison with benchmarks.
Cookbook
Guard Patterns
Global/per-route Guard composition, guards![] macro, custom Guard implementation.
HttpIngress Patterns
post vs post_typed, path parameters, bus_injector, static assets, WebSocket.
Bus Patterns
insert/read/write, DB pool sharing, newtype collision safety, Guard Bus types.
Saga Compensation
then_compensated, LIFO ordering, compensation failure handling, persistence.
LLM Pipeline
LlmTransition, parallel tool calls, PII filtering, retry/timeout resilience.
Database Migration
sqlx/refinery integration, Docker Compose ordering, CI/CD pipeline setup.
Streaming Patterns
StreamingTransition, StreamingAxon, SSE endpoints, stream timeouts, testing.
Multi-Tenant Isolation
TenantGuard extraction, Bus propagation, DB isolation, per-tenant rate limiting.
Egress Patterns
HMAC webhook delivery, multi-channel notifications, retry/DLQ, circuit breaker.
LLM Gateway
Multi-provider routing, token counting Guard, cost budgets, SSE streaming proxy.
PII Masking
PII detection Guard, regex patterns, masking strategies, double-scan pipeline.
Billing & Metering
Redis API metering Guard, plan management, overage handling, usage reports.
Data Reconciliation
Fuzzy matching, weighted scoring, Outcome classification, reconciliation reports.
Outcome Patterns
try_outcome! macro, Outcome combinators (from_result, and_then, map_fault), Bus::get_cloned().
Outcome::from_result
Convert Result<T, E> to Outcome via from_result/from_result_ctx โ sqlx, serde, reqwest patterns.
Explicit Search Params
PageParams, Paginated<T>, custom search structs with from_bus() โ no derive magic.
JSON Outcomes
get_json_out, post_typed_json_out, BusHttpExt, json_outcome(), typed JSON at route boundary.
Saga Compensation Patterns (Deep Dive)
Advanced saga patterns with payment, insurance, and onboarding domain examples.
Cascade Screening
Sequential filter pipeline with fail-fast โ AML/KYC, content moderation, customs.
Multi-Step Pipeline
Typed state progression pipeline โ AI agent, ETL, IoT, with streaming support.
Integration
Tower Integration
Tower Service/Layer middleware with Ranvier transitions.
actix-web Integration
Use Ranvier transitions in actix-web handlers and extractors.
Axum + Ranvier Hybrid Guide
Axum serves HTTP, Ranvier processes complex logic โ saga, state bridging, decision criteria.
When to Use Ranvier vs Axum
Decision table: when to use Ranvier, Axum, or both together (hybrid pattern).
Operations
Deployment Guide
Docker multi-stage builds, Kubernetes manifests, and environment configuration.
Performance Tuning
Profiling, connection pools, async patterns, and release build optimization.
Pattern Catalog
Reusable patterns: saga, fan-out/fan-in, validation pipeline, and more.
API Stability Contract
Frozen traits, deprecation policy, and semver commitment for v1.0.
Product Manuals
Ranvier Manual
Core runtime guide: Transition, Outcome, Bus, Axon, and Schematic.
CLI Manual
Commands and artifact flows for ranvier-cli.
VSCode Manual
Setup and diagnostics workflow for ranvier-vscode.
Deep Dives
HTTP Deep Dive
HTTP Ingress, Router DSL, body handling, and middleware.
Standard Library
Built-in nodes: Logic, Flow, Data categories.
Persistence Deep Dive
Crash recovery, durable adapters, saga pattern.
Observability Deep Dive
Inspector, Prometheus metrics, OTLP tracing pipeline.
Auth Deep Dive
Guard nodes, IAM framework, session management patterns.
Operations Deep Dive
Configuration, health probes, structured logging, telemetry.
Deployment Deep Dive
Docker multi-stage builds, Kubernetes manifests, production patterns.
Patterns & Examples
Use Cases
6 real-world use cases โ saga, screening, pipeline, IoT, triage, rule chain.
Ranvier Samples
Core example reproduction: typed-state-tree, basic-schematic, hello-world.
CLI Samples
CLI artifact generation from schematic and timeline inputs.
VSCode Samples
Circuit view and issue navigation workflow reproduction.
Examples Explorer
Interactive example browser with tier/category filters and learning paths.
Pattern Catalog (Interactive)
12 battle-tested patterns with live code examples and difficulty ratings.