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

ContractsTyped calls & replies EventsAsynchronous reactions

CatalogProduct logic & data

Standard modules, same boundariesIdentity · Tenancy · Billing

Public SDKsandloom.sdk

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>.

Modules and drivers¶

A module is what your product does; a driver is what it runs on. Modules call the framework's capabilities through the SDK and never name a driver. SANDLOOM_MODULES selects which modules a process loads, and INFRA selects which driver backs each capability. Modules talk to each other through events, contracts, projections and sagas, never an import (Choose how modules talk).

What do I write?¶

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