Documentation
Guides, tutorials, and references.
Follow the stable path in order, then expand the catalog for deeper or experimental material.
Featured
1. Install once
Install the ranvier facade and run the compiled native HTTP quickstart.
2. Compile three workflows
Continue with typed state, typed JSON HTTP, and Bus capability.
3. Choose the HTTP edge
Keep native ingress or integrate Ranvier into an existing Axum service.
Current status
Check module capabilities, versioning, and verification commands.
Catalog
Getting Started 7 docs
Quickstart Install Ranvier and run your first typed pipeline in under 5 minutes.Getting Started Guide Follow the maintained workflows, then choose the native or hybrid HTTP edge.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 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 10 docs
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 7 docs
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.Production Readiness Evidence Current candidate evidence, support matrix, and 1.0-entry go/no-go criteria.Auth Comparison Transition-based vs Tower-based authentication: 7-feature comparison with benchmarks.
Cookbook 20 docs
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 4 docs
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 4 docs
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 3 docs
Deep Dives 7 docs
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 6 docs
Use Cases 6 real-world use cases — saga, screening, pipeline, IoT, triage, rule chain.Ranvier Samples Official example track and follow-up bridge/reference examples.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.