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

## Current implementation status

Implemented now: the Phase 1 repository and infrastructure foundation plus public module contracts,
the Module SDK manifest API, static versioned module manifests, automatic filesystem discovery,
compatibility/dependency ordering, structured discovery failures, and a backend-only module
template. Core can validate zero or more modules without importing their server behavior.

Target architecture, not yet implemented: lifecycle execution and runtime registration, Drizzle
schema aggregation/migrations, Better Auth, permissions, physical storage-bucket provisioning,
Surface SDK, capability/resource/action registries, API server, dashboard, Builder, and reference
feature modules.