#Why Opinionated Core? โ Constraints Enable Clarity
Version: 0.33.0 Updated: 2026-03-15 Applies to: ranvier (all crates) Category: Philosophy & Architecture
Ranvier's core is deliberately opinionated for three strategic reasons. While "opinionated" might sound limiting, it's actually what makes Ranvier productive and distinct.
#1. Identity: What Makes Ranvier, Ranvier?
Problem: Rust has many web frameworks (Actix, Axum, Rocket, Warp, Tide...). Why another one?
Answer: Ranvier is not "another web framework" โ it's a schematic-first, event-driven framework. The Transition/Outcome/Bus/Schematic paradigm is our unique value proposition.
- Unique niche: Ranvier excels at complex, stateful workflows (multi-step auth, saga patterns, event sourcing)
- Visual debugging: No other Rust framework gives you VSCode-integrated circuit views
- Type-driven composition: The compiler guides you toward correct architectures
#Framework Identity
| Framework | Identity |
|---|---|
| Actix | Actor model for web apps |
| Axum | Ergonomic routing with Tower middleware |
| Ranvier | Schematic-first, visualizable data flows |
Each has a clear identity. Ranvier's opinionated core IS that identity.
#2. Learning Curve: One Right Way, Not Ten Ways
Problem: Flexible frameworks offer choice, but choice creates cognitive load. "Should I use middleware X or Y? Pattern A or B?"
Ranvier's approach:
- One blessed path: Use Transition for business logic. Always.
- Clear migration: If you need ecosystem tools, there's a documented integration path
- Reduced decision fatigue: New users don't waste time evaluating alternatives
#Learning ROI
| Week | What You Learn | Result |
|---|---|---|
| Week 1 | Transition/Outcome/Bus | Productive immediately |
| Week 2 | Schematic visualization | Debugging superpowers |
| Week 3 | Ecosystem integration (if needed) | Best of both worlds |
#3. Consistency: Codebases That Look Alike
Problem: In flexible frameworks, every team/project invents their own patterns. Onboarding new developers is slow because every codebase is a snowflake.
Ranvier's approach: All Ranvier codebases follow the same structure (transitions/, outcomes/, schematics/, main.rs).
- Faster onboarding: Developers moving between Ranvier projects recognize the patterns instantly
- Easier code review: Reviewers know what "good Ranvier code" looks like
- Tool support: Editors, linters, generators can assume a consistent structure
Analogy: Rails' "convention over configuration" made Ruby teams highly productive. Ranvier applies the same principle to Rust event-driven systems.
#Related Documents
- Why Flexible Edges? โ The other side of the coin
- Decision Framework โ How to choose your approach
- PHILOSOPHY.md โ Full arguments and code examples