How Sandloom works¶

Your product is a set of isolated modules. They reach the framework through one public SDK, and drivers connect the framework to your backends.

Business modulesYour application code

OrdersOrder logic & data

CatalogProduct logic & data

Standard modules, same boundariesIdentity · Tenancy · Billing

KernelProvided by Sandloom

TransactionsAccess checksOutbox & inboxLocal / RPC routing

Each application or service runs its own kernel.

DriversSelected by configuration

Each driver connects the runtime to a concrete backend.

Database · sqlalchemyPostgreSQL

CacheRedis

Events · streamsRedis Streams

Files · localDisk / volume

Tasks · celeryCelery

EmailSMTP

One modular application. The same module code in a monolith or separate services.

Design principles¶

A module stands alone. It imports only the public SDK and generated contracts, never another module. You or a coding agent can change one by reading it and the contracts it calls.
The framework owns what is easy to get wrong. It commits the transaction, authenticates each route unless the route declares public(reason=...), and delivers events through an outbox. Weakening a default takes a visible line of code. Which resources a user may touch is yours to declare with require.
Configuration decides where things run. It selects which process loads which module and which backend each capability uses. Moving a running module's existing data to its own database is a separate, explicit step.
A machine checks the rules. sandloom check and the startup checks enforce the boundaries and name the fix: sandloom explain <code>.

A module is what your product does. A driver is what it runs on.

	Module	Driver
What it is	one slice of the business, such as orders or billing	a connection to a backend, such as Redis or SMTP
Who uses it	your product's users, through routes	modules, through the SDK; they never name the driver
Imports	`sandloom.sdk`	`sandloom.driverkit`
Found through	your `modules` package or the `sandloom.modules` entry point	the `sandloom.drivers` entry point
Selected by	`SANDLOOM_MODULES`	`INFRA`
Created with	`sandloom add module <name>`	your own package

Modules talk to each other in two ways: events when something has happened, and typed contracts when one needs an answer now.

I want to	I write
add a product feature	a module
react to something another module did	an event consumer
ask another module for data now	a call to its contract
run a process across modules, with undo	a saga
show a list that spans modules	a projection
change how identity, tenancy or billing behave	a customization
send notifications through a new service	a driver
run a module as its own service	configuration, no module code