chore: establish Ekklesia platform foundation

2026-07-12 20:28:19 -05:00
commit 192a6514cf
47 changed files with 2505 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Platform architecture
+
+Ekklesia is a long-lived platform from which churches can compose many applications and user
+experiences. It begins as a modular monolith so contracts can stabilize before distribution is
+introduced.
+
+## Dependency model
+
+The arrows below mean "depends on." Presentation and composition depend on stable lower-level
+contracts; infrastructure never learns individual feature names.
+
+```text
+Surface Builder configuration -> Surfaces -> public capability contracts
+                                      ^
+                                      |
+                         HTTP/API and client contracts
+                                      |
+Feature Modules -> Module SDK / platform contracts <- Core implementations
+```
+
+The four ownership layers are:
+
+1. **Core** orchestrates generic platform infrastructure: startup, identity, permissions,
+   configuration, database connectivity, storage, events, jobs, module discovery, and lifecycle.
+2. **Modules** own backend domain behavior, data schemas, resources, actions, routes, events,
+   permissions, and jobs.
+3. **Surfaces** own every presentation concern: components, renderers, layout, navigation,
+   accessibility, interaction, branding, and client state.
+4. **Surface Builder** stores validated declarative composition. It selects capabilities and
+   surface-owned renderers but contains neither executable code nor module business logic.
+
+Modules do not own UI. For example, Calendar data, actions, and permissions will live in
+`modules/calendar`; Calendar renderers for a dashboard or public website will live in those
+surfaces.
+
+## Stable seams
+
+- Modules use public SDK ports and injected Core services, never undocumented Core internals.
+- Modules do not import another module's schema or private code. Integrations use public service
+  contracts, capabilities, events, or APIs.
+- Surfaces consume API/client and capability contracts, never feature-module packages.
+- Core discovers feature modules generically. It contains no feature-specific imports or
+  conditional branches.
+- Deployable apps are thin composition roots and do not become domain-logic owners.
+- Generated bootstrap artifacts may connect discovered entry points at the application edge;
+  they do not become manually maintained Core registries.
+
+## Security invariants
+
+- Authorization is enforced server-side.
+- Secrets are isolated from public configuration and logs.
+- Authentication tokens, private form content, prayer requests, and pastoral information are not
+  logged.
+- Sensitive actions are designed for auditability without copying sensitive content into audit
+  records.
+- Private objects use signed access and namespaced storage paths.
+- Every network service starts from least-privilege and local-only development defaults.
+
+## Phase 1 status
+
+Implemented now: monorepo/tooling, strict TypeScript policy, repository-boundary validation,
+tests, base CI, PostgreSQL, and a development S3-compatible object store.
+
+Target architecture, not yet implemented: Core runtime, module discovery and lifecycle, Drizzle
+schema aggregation/migrations, Better Auth, permissions, storage service, Module SDK, Surface
+SDK, capability/resource/action registries, API server, dashboard, Builder, and reference modules.