Philosophy / Decision Framework

How to Choose Your Approach

When you face a choice between "Ranvier way" and "ecosystem way", use this framework to make informed decisions.

Questions to Ask (In Order)

The first "Yes" determines your approach:

1. Is this core business logic?
(validation, calculation, orchestration)
Ranvier way: Visualization, composition, testability
2. Do I need to see it in the Schematic graph?
(debug complex flows, document for team)
Ranvier way: Only Transitions appear in Circuit view
3. Is this pure infrastructure?
(CORS, TLS, rate limiting, circuit breaking)
Ecosystem way: Reuse battle-tested libraries (Tower)
4. Am I migrating from an existing codebase?
(Tower app, actix service)
Hybrid: Start with ecosystem, gradually adopt Ranvier
5. Does my team already know tool X?
(Tower, Axum, diesel)
Ecosystem way → Ranvier: Use existing knowledge, wrap in Transition later

Decision Flowchart

START
  │
  ├─ Core business logic? ───Yes──> Ranvier way (Transition)
  │
  ├─ Need visualization? ────Yes──> Ranvier way
  │
  ├─ Pure infrastructure? ───Yes──> Ecosystem way (Tower/library)
  │
  ├─ Migrating existing? ────Yes──> Hybrid (Tower + Ranvier)
  │
  └─ Default ────────────────────> Ranvier way (when in doubt)
  

Summary Table

DomainRanvier WayEcosystem WayHybrid
Business logic✅ Always❌ Never-
Complex auth✅ Recommended⚠️ Possible✅ Common
CORS❌ Overkill✅ Use Tower-
Database✅ Wrap in Transition⚠️ Direct use OK✅ Common
Metrics⚠️ Manual✅ Use Tower-
Middleware✅ For business rules✅ For infrastructure✅ Common

✅ Recommended | ⚠️ Acceptable | ❌ Anti-pattern

When Should I Use Ranvier?

New project, complex workflows → ✅ Pure Ranvier (Transition)
New project, simple CRUD → ⚠️ Maybe Ranvier (or simpler frameworks OK)
Existing Tower app → ✅ Hybrid (keep Tower, add Ranvier for new features)
Existing actix/Axum app → ✅ Embed Ranvier in handlers
Microservice orchestration → ✅ Ranvier for orchestrator
Leaf CRUD services → ❌ Use simpler frameworks
Just need CORS/basic auth → ❌ Tower/actix/Axum middleware is simpler
Multi-step state machines → ✅ Ranvier's sweet spot
Default recommendation: If in doubt and you have any multi-step logic, use Ranvier. The visualization alone justifies the investment.
For detailed scenarios, code examples, and migration paths, see PHILOSOPHY.md — Decision Framework