docs: document module database access
CI / verify (pull_request) Successful in 27s
CI / infrastructure-smoke (pull_request) Successful in 20s
CI / migration-smoke (pull_request) Successful in 29s

Add ADR 0016 recording the accepted module database access design (ModuleDatabase, the frozen
ModuleRuntimeServices boundary, one pool/one facade/one services-object identity, explicit
migrations, and the trust model), with narrow cross-reference corrections to ADR 0006 and ADR 0015
where their original text is now inaccurate. Sweep docs/development/api.md,
docs/development/authorization.md, docs/module-development/README.md, docs/development/testing.md,
and docs/development/identity.md for the new database boundary and remaining Phase 4C staleness;
correct the stale "Phase 4C is next" roadmap paragraph in platform-architecture.md and the matching
gap in README's current-status narrative. Extend the module template with a permissioned
GET /records route reading through context.services.database, using the canonical
createModuleTable helper, with matching template tests.
This commit is contained in:
ekklesia
2026-07-25 21:50:03 -05:00
parent d1b9efd4d2
commit c38b572778
15 changed files with 584 additions and 91 deletions
+12 -4
View File
@@ -2,8 +2,11 @@
This is the smallest supported backend-only Ekklesia module. It proves the static manifest,
compiled runtime and schema entrypoints, capability registration, a module-owned Drizzle table, a
generated module-owned migration, and logical storage-bucket declarations. Migration execution,
API routing, and storage provisioning are intentionally not included.
generated module-owned migration, logical storage-bucket declarations, and one permissioned HTTP
route (`GET /records`, declared in `register`) that reads that table through
`context.services.database` — the platform-provided `ModuleDatabase` facade, never a
module-constructed Drizzle instance or a raw `pg` client. Migration execution and storage
provisioning are intentionally not included.
To create a module inside this repository:
@@ -14,7 +17,10 @@ To create a module inside this repository:
4. Keep the manifest capability versions and dependency ranges aligned with the contracts the
module actually implements and consumes.
5. Replace `src/server/index.ts` with backend behavior only. Its `defineModuleRuntime` ID and version
must match the manifest; do not duplicate the rest of the manifest in TypeScript.
must match the manifest; do not duplicate the rest of the manifest in TypeScript. Declare HTTP
routes only in `register`, against a permission the manifest already declares; `start`, `stop`,
and every route handler — never `register` — receive `context.services.database`, a typed
`ModuleDatabase` view over the platform's one PostgreSQL pool.
6. Replace the pure Drizzle declarations in `src/schema/tables.ts` and keep its table prefix aligned
with the module ID. Keep the `defineModuleSchema` ownership wrapper in `src/schema/index.ts`
aligned too, and never import another module's schema.
@@ -29,7 +35,9 @@ To create a module inside this repository:
Do not add UI components, styles, renderers, navigation, or layouts. Those belong to surfaces.
Keep imports side-effect-free, register capabilities in `register`, acquire resources in `start`,
and release them in `stop`.
and release them in `stop`. Never construct a Drizzle instance, read `DATABASE_URL`, or reach for a
raw `pg` client — `context.services.database` is the only supported way to query this module's own
tables, and it is never available during `register`.
The migration directory uses the pinned stable Drizzle Kit `0.31.10` PostgreSQL journal and
snapshot format. Migrations are forward-only and may modify only this module's objects. Offline