An open-source ride-sharing reference architecture built on the Critter Stack, showcasing Wolverine's gRPC feature set alongside event-driven messaging, event sourcing, and more.
CritterCab is an open-source reference architecture for a ride-sharing platform, built on the Critter Stack, a family of .NET libraries maintained by JasperFx. Its distinguishing focus is Wolverine's gRPC feature set, which shipped in Wolverine 5.32. Ride-sharing was chosen because its natural shape (GPS streaming, dispatch matching, trip lifecycle) exercises gRPC in all four modes while leaving room for event sourcing, high-volume telemetry, and multi-transport messaging.
| Concern | Package | Version |
|---|---|---|
| Messaging, HTTP, gRPC, handlers | Wolverine | 5.32+ floor; currently on 5.39+ |
| Event sourcing (PostgreSQL) | Marten | 8.35+ |
| Document store (SQL Server) | Polecat | 3.1+ |
| Local-dev orchestration | Aspire | 13.3 |
| Database | PostgreSQL | 18 |
| Integration test host | Alba | 8.5+ |
- gRPC as a design concern. All four modes (unary, server-streaming, client-streaming, bidirectional) exercised against natural domain use cases.
- Multi-transport messaging. gRPC, Kafka (for high-volume telemetry), and likely Azure Service Bus (for business events) in one system, chosen per flow rather than defaulted.
- Distributed services. Each bounded context deploys as a separate service, communicating exclusively through messages or gRPC calls.
- Polyglot participation. At least one non-.NET service (Go, most likely) participates over gRPC, keeping the contract honest at the wire level.
Early development. The Dispatch service has its first two vertical slices implemented end-to-end with Marten event sourcing, Wolverine.HTTP, and Alba integration tests:
- Slice 5.1 —
SubmitRideRequest→RideRequested(HTTP entry point, aggregate, projections). - Slice 5.2 —
RideRequested→FareQuoteAutomation→FareQuoted/FareQuoteFailed(Wolverine-driven automation against a stubIPricingClient; the Pricing BC itself is pending its own workshop).
All other bounded contexts remain pre-workshop. See docs/vision/README.md for the full scope and docs/decisions/ for committed decisions.
To clone, build, and run CritterCab locally you will need:
- .NET 10 SDK — the project targets
net10.0and uses C# 14. - Docker (Docker Desktop or an equivalent OCI runtime) — Aspire spins up PostgreSQL 18 as a container for local dev, and the integration tests use Testcontainers for ephemeral PostgreSQL, SQL Server, Kafka, and Azure Service Bus instances.
- An IDE with C# tooling (optional but recommended) — JetBrains Rider, Visual Studio, or VS Code with the C# Dev Kit.
No global tool installs are required; the AppHost is a file-based .NET 10 program (apphost.cs) that pulls its Aspire dependencies via #:package directives.
Clone the repository and start the Aspire AppHost. This boots the PostgreSQL container and the Dispatch service together, and opens the Aspire dashboard at https://localhost:17068 (default).
git clone https://github.com/erikshafer/CritterCab.git
cd CritterCab
# Boot Postgres + Dispatch via the Aspire AppHost
dotnet run apphost.csRun the full test suite (unit + Alba integration tests, the latter backed by Testcontainers):
dotnet test CritterCab.slnxThe Dispatch service exposes POST /ride-requests for slice 5.1 and a health endpoint at GET /health. Probe shape and behavior are pinned by the Alba tests under tests/CritterCab.Dispatch.Tests/.
.
├── apphost.cs # File-based Aspire AppHost (.NET 10 file-based program)
├── CritterCab.slnx # Solution
├── Directory.Build.props # Shared MSBuild props (TFM, lang version, nullable)
├── Directory.Packages.props # Central package versions
├── protos/ # Protobuf contracts (buf-managed)
├── src/
│ └── CritterCab.Dispatch/ # First bounded-context service
├── tests/
│ └── CritterCab.Dispatch.Tests/
└── docs/ # Layered design artifacts (see below)
The docs/ directory is the heart of the project — design happens there before code does. See the Documentation section below.
For the comprehensive project overview (goals, tentative bounded contexts, technology stack, design principles, parked decisions, open questions), see docs/vision/.
The rest of the documentation is organized as layered artifacts:
- Workshops: Event Modeling and Domain Storytelling session output.
- Narratives: journey-scoped domain specs (NDD-informed).
- Skills: component-scoped implementation patterns and conventions.
- Rules: AI-optimized encodings of structural constraints for implementation sessions.
- Prompts and Retrospectives: the session-driven implementation workflow.
- Context Map: DDD strategic-design cross-BC relationships.
- ADRs: significant architectural decisions with rationale.
- Research: exploratory work and spikes.
The Critter Stack is a family of open-source .NET libraries maintained by JasperFx: Wolverine (messaging, handlers, and now gRPC), Marten (PostgreSQL document store and event sourcing), Polecat (SQL Server document store), Weasel (database schema management), and Alba (integration testing).
CritterCab is a reference architecture, so the way it grows matters as much as what it grows into. Before opening a PR:
- Read the project vision and the relevant ADR(s) so changes stay aligned with committed decisions.
- For implementation work, follow the session-driven workflow described in
docs/prompts/README.md— one prompt, one session, one PR, paired with a retrospective. - All contributors are expected to follow the Code of Conduct.
Bug reports and discussion are welcome via GitHub Issues.
MIT — see ADR-008 for the rationale.
Erik "Faelor" Shafer