Every module has the same shape

One shape, two languages

Account, shown here, is typical. The Nest twin has the same folders with kebab-case file names, and a few extra transport folders because Nest registers jobs, startup hooks and operator commands through its own container.

backend/go/internal/account/
├── build.go        Schema const, Build(rt) → module.Unit
├── module.go       wiring: handlers, routes, capabilities
├── admin.go        operator command facades
├── domain/         account, membership, invitation, events
├── app/
│   ├── command/    accept_invitation.go, create_account.go…
│   ├── query/      list_members.go, personal_data.go…
│   ├── ports.go    interfaces the module owns
│   └── errors.go
├── infra/
│   ├── postgres/   store.go: state + outbox
│   ├── events/     producer.go, identity_consumer.go
│   └── capabilities/ clients.go
└── transport/
    ├── http/v1/
    └── capability/v1/

backend/nest/src/modules/account/
├── schema.ts       SCHEMA const
├── account.module.ts
├── domain/
├── app/
│   ├── command/    accept-invitation.ts…
│   ├── query/
│   ├── ports.ts
│   └── errors.ts
├── infra/
│   ├── postgres/   account.store.ts
│   ├── events/     producer.ts, identity-event.consumer.ts
│   ├── capabilities/ clients.ts
│   └── security/
└── transport/
    ├── http/v1/    account.controller.ts
    ├── capability/v1/
    ├── jobs/       account.jobs.ts
    ├── startup/    declare-roles.hook.ts
    └── admin/v1/

Layers

Dependencies point inward. The domain knows nothing about storage or transport, the application layer defines the ports it needs, and only the outer adapters touch HTTP, events, other modules or the database.

The module unit

In Go, a module's Build(rt module.Runtime) returns a module.Unit, which tells the process everything it needs to run the module. The runtime hands each module a database scoped to its own schema, a capability invoker, a principal resolver, the broadcast bus, a cache in its own namespace, IDs, a clock and provenance. Nest expresses the same pieces as a module with providers wired throughmoduleDatabase(SCHEMA).

Schema, role and migrations

The runner, scripts/migrate-postgres.sh (make db-migrate), records a SHA-256 of each applied file and refuses edited ones. Databases created before the per-schema split keep a frozen shared history, migrations/0001 to 0018, and adopt the baselines; new databases run the baselines only. Each connection can move to its own database with<SCHEMA>_DATABASE_URL.

Events: outbox, delivery, inbox

1. ProducerWrites its state change and an event_outbox row in one transaction.
2. DispatcherOne per producing schema. Leases rows, publishes them, retries failures and quarantines rows it cannot decode.
3. TransportIn memory in a monolith, NATS JetStream in a split. Delivery is at least once.
4. ConsumerTracks progress in its own event_delivery table and records the event in its event_inbox in the same transaction as its state change, so a redelivery is ignored.

Eight modules produce events: Identity, Account, Authorization, Audit, Billing, Files, Privacy and AI. Event payloads are versioned JSON Schemas in contracts/events; a changed payload gets a new.vN and the old version stays listed until it is retired. Every module also gets an automatic<schema>.prune_event_tables job.

HTTP conventions

Caching

Each module gets a cache in its own namespace, in memory or on Redis (CACHE_PROVIDER), with a short local tier in front of Redis. A cache failure counts as a miss and never grants anything. Only three reads are cached today:

Enforcement

The rules above are checked, not just written down. Both checks run in make check and in CI.

Adding a module

1. Create the folders and a schema name, then add its baseline migration and runtime role to both migration folders.
2. Register it: the modules list in cmd/server/main.go and ModuleSchemas in Go; MODULES, OUTBOXES and MODULE_SCHEMAS in Nest.
3. Add its events and capabilities to contracts/, its routes to the OpenAPI spec, and its personal data to contracts/privacy/inventory.yaml with a <module>.personal_data.v1 provider.
4. Run make check in both backends and the end-to-end suites.

The full checklist is backend/ADDING-A-MODULE.md.

Shared packages

Modules share mechanics, never vocabulary. backend/go/pkg and backend/nest/src/sharedhold the same set of packages:

In the repository