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
66 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.
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.
Integration
Tower Integration
Tower Service/Layer middleware with Ranvier transitions.
actix-web Integration
Use Ranvier transitions in actix-web handlers and extractors.
Axum Integration
Combine Axum's ergonomic API with Ranvier's Schematic workflows.
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
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.