What is Riverbase

Riverbase is a Rust framework for building domain-driven HTTP backends. You describe a bounded context as a domain: commands that change state, queries that read it, and an aggregate that holds the rules. Riverbase turns that into an axum service with generated routes, OpenAPI, authentication, Casbin authorization, tenant-aware row policy, and an audit log of every command.

domain/src/domain.rs

riverbase_core::domain! {
    domain TodoDomain {
        meta {
            namespace: "riverbase.todo",
            title: "Todo List",
            description: "Reference vertical slice.",
        }
        command: TodoCommandEngine,
        query: TodoQueryEngine,
        spawn(runtime: &DomainRuntime) { /* start engines against one store */ }
    }
}

Mounting that domain on a RiverbaseApp serves:

POST/api/riverbase.todo/create-todo:post/todocollection command

POST/api/riverbase.todo/update-todo:exec/todo/{id}object command

GET/api/riverbase.todo/todo.listlist query with filters, sort, paging

GET/api/riverbase.todo/todo.item/{id}item query

GET/api/riverbase.todo/todo.metafield and sort metadata for UIs

Design in one paragraph

Riverbase is state-based CQRS. Persisted aggregate state is the source of truth. Commands go through a command engine that opens one database transaction per command. That transaction holds the state change, the audit trail (command, event, activity, response), and outbox messages, and it commits them atomically. Queries go through a separate query engine that only reads. Events are audit and integration facts, not a replay stream. See DDD and state-based CQRS.

Why Rust

You get	Because
Typed command payloads and query fields	command_engine! and query_resource! generate Rust types, JSON Schema and OpenAPI from one declaration
SQL errors at compile time	Persistence uses Diesel with diesel-async on Postgres
Predictable concurrency	Command engines schedule work on ractor actor pools; queries are bounded by a semaphore
One binary per service	Run command and query together (coupled), or as separate processes (split)
Fail-closed defaults	An empty Casbin policy denies everything; query resources must declare a row policy

The crates

Riverbase ships as a Cargo workspace. Most services need two crates. Add the others when a domain needs that capability.

Crate	What it is
riverbase_core	Engines, domains, Postgres datastore, audit log, message bus, config
riverbase_proc	#[domain_action] and other proc macros
riverbase_http	RiverbaseApp, routes, OpenAPI, auth, Casbin, realtime
Extensions	riverbase_task workers, riverbase_file media storage, riverbase_form forms

Where to go next

• Run something now: the Quick start builds a todo service from an empty directory.
• Learn the model: the Tutorial builds a domain chapter by chapter.
• Look something up: Crates and Reference.