README
¶
PocketCQRS
A CQRS + functions-as-a-service backend built on PocketBase as a Go dependency.
- Write side: commands arrive at a gateway route, are handled by Go Deciders (
InitialState/Decide/Evolve), and commit as events to an append-only log — the source of truth. - Event store: separate SQLite file
events.dbalongside PocketBase'sdata.db, with per-aggregate optimistic concurrency and a global position for catch-up. - Read side: projections fold events into ordinary PocketBase collections, so the stock REST API, realtime subscriptions, auth rules and admin UI serve queries unchanged. Rebuild a projection offline with
pocketcqrs projection rebuild <name>. - Write-guard: direct record writes to guarded collections are rejected for everyone (superusers included); the only writer is the projection engine.
- Sagas: reactors are durable consumers that map committed events to follow-up commands, dispatched back through the registry with causation/correlation metadata — reactions become events like everything else.
- Functions (FaaS): user-defined JS functions from
pb_functions/— effects (//@trigger event), HTTP (//@trigger http), cron (//@trigger cron), projections (//@trigger projection+//@schema), and full deciders (//@trigger decider) — with durability, determinism tiers and read-only query-side bindings per role. Commands and HTTP functions require PocketBase auth by default (--cqrsAllowAnonymousfor dev).
Status
Early development — see milestones in the issue worktree (task_plan.md). Not affiliated with PocketBase; upstream (pocketbase/pocketbase) is an unmodified dependency pinned in go.mod.
Docs
- Getting started — run it, first command, first function, hot reload
- JS guide — directives, tiers, bindings, determinism, dry-run/dead-letter workflows
- Go guide — deciders, projections, reactors in Go
- Reference: directives · CLI · gateway
- Domain docs — convention + dogfooded task, order, note
- Domain packs — export/import domains, versioning contract, trust model
- Contributing
Development
Requires Go 1.25+.
go run . serve
Then open the PocketBase admin UI at http://127.0.0.1:8090/_/.
Install
Two binaries, two install paths (go install <module>@latest covers only the
root main package):
go install github.com/JamesTryand/pocketcqrs@latest # the backend
go install github.com/JamesTryand/pocketcqrs/pocketcqrs-dashboard@latest # the ops dashboard
@latest resolves to the newest semver tag (see the repo's tags; pin an
exact version with @vX.Y.Z or a commit hash). The dashboard prints its
version with pocketcqrs-dashboard --version.
License
MIT (see LICENSE). PocketBase itself is MIT-licensed, (c) Gani Georgiev.
Documentation
¶
There is no documentation for this package.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package aggregates holds the write-side models (deciders) of the domain.
|
Package aggregates holds the write-side models (deciders) of the domain. |
|
Package catalog introspects the running platform — aggregates, event types, consumers, collections, functions and reactor flows — into a single document (the catalog), rendered as JSON, Markdown + Mermaid, or domain-doc skeletons.
|
Package catalog introspects the running platform — aggregates, event types, consumers, collections, functions and reactor flows — into a single document (the catalog), rendered as JSON, Markdown + Mermaid, or domain-doc skeletons. |
|
Package consumers provides the shared checkpointed-consumption engine: named consumers follow the event log in position order with durable checkpoints (stored in the event store), so delivery survives restarts.
|
Package consumers provides the shared checkpointed-consumption engine: named consumers follow the event log in position order with durable checkpoints (stored in the event store), so delivery survives restarts. |
|
Package decider implements the functional event-sourcing Decider pattern (see https://thinkbeforecoding.com/post/2021/12/17/functional-event-sourcing-decider): commands are decided against a folded stream state, producing the events that get appended to the event store.
|
Package decider implements the functional event-sourcing Decider pattern (see https://thinkbeforecoding.com/post/2021/12/17/functional-event-sourcing-decider): commands are decided against a folded stream state, producing the events that get appended to the event store. |
|
Package events implements the PocketCQRS append-only event store.
|
Package events implements the PocketCQRS append-only event store. |
|
Package functions provides the PocketCQRS functions-as-a-service layer: user-defined functions triggered by domain events or HTTP (cron later).
|
Package functions provides the PocketCQRS functions-as-a-service layer: user-defined functions triggered by domain events or HTTP (cron later). |
|
Package gateway exposes the write side over HTTP: commands in, events out.
|
Package gateway exposes the write side over HTTP: commands in, events out. |
|
Package migrations holds the PocketCQRS PocketBase migrations.
|
Package migrations holds the PocketCQRS PocketBase migrations. |
|
Package packs implements domain packs: portable bundles of a domain's function files (pb_functions) plus any plain (non-projection-owned) collection schemas, with a manifest.
|
Package packs implements domain packs: portable bundles of a domain's function files (pb_functions) plus any plain (non-projection-owned) collection schemas, with a manifest. |
|
Command pocketcqrs-dashboard is the CQRS ops dashboard: a separate, self-contained binary that consumes a pocketcqrs instance over its public API only (never internals, never the event store).
|
Command pocketcqrs-dashboard is the CQRS ops dashboard: a separate, self-contained binary that consumes a pocketcqrs instance over its public API only (never internals, never the event store). |
|
Package projections folds events from the event store into ordinary PocketBase collections, so the stock PocketBase REST/realtime/auth API serves the query side unchanged.
|
Package projections folds events from the event store into ordinary PocketBase collections, so the stock PocketBase REST/realtime/auth API serves the query side unchanged. |
|
Package reactors implements cross-aggregate reactions (sagas/process managers): durable consumers that map committed events to new commands, dispatched in-process through the decider registry — so reactions become events like everything else, never out-of-band state changes.
|
Package reactors implements cross-aggregate reactions (sagas/process managers): durable consumers that map committed events to new commands, dispatched in-process through the decider registry — so reactions become events like everything else, never out-of-band state changes. |
|
Package writeguard rejects out-of-band record writes on guarded (projection-owned) collections.
|
Package writeguard rejects out-of-band record writes on guarded (projection-owned) collections. |
Click to show internal directories.
Click to hide internal directories.