# Ekklesia

Ekklesia is an open, modular church technology platform for composing backend capabilities
into independently developed dashboards, websites, mobile apps, kiosks, displays, and other
surfaces.

## Current status

Phase 3 is underway. The repository now includes public module contracts, independently versioned
capabilities, static module manifests, deterministic automatic discovery, compiled server loading,
a staged capability registry, dependency-ordered lifecycle with rollback, module-owned Drizzle table
contracts, deterministic schema aggregation, and a cloneable backend-only module template. Migration
artifacts now have module-owned Drizzle contracts, deterministic offline discovery, explicit
destructive-change declarations, and exact checksums. Core now provides read-only applied-history
planning and a locked, whole-batch transactional PostgreSQL runner with exact external destructive
approval matching. A hermetic live PostgreSQL suite now proves history, rollback, statement
breakpoints, advisory-lock concurrency and release, exact destructive approvals, and sanitization
against the production adapter. Production approval-provider composition, identity, HTTP routing,
jobs, physical storage provisioning, surfaces, and feature modules remain later vertical slices.

## Quick start

Prerequisites: Node.js 24 LTS, pnpm 11.12, and Docker with Compose.

```bash
pnpm install --frozen-lockfile
cp .env.example .env
pnpm infrastructure:up
pnpm modules:validate
pnpm migrations:validate
pnpm migrations:plan
pnpm test:migrations:integration
pnpm verify
```

`pnpm migrations:plan` uses `DATABASE_URL` from the uncommitted `.env` and is read-only.
`pnpm migrations:apply` uses the same validated inventory but mutates PostgreSQL under Core's
advisory lock and one transaction. Review the plan before applying. Destructive migrations are
blocked by default and require an exact externally supplied approval; there is no force flag.

The runner has both deterministic unit coverage through a narrow database port and a separate live
PostgreSQL integration suite. The live command creates and destroys disposable Docker
infrastructure; it remains separate from the Docker-free `pnpm verify` gate.

Run `pnpm infrastructure:smoke` for an isolated end-to-end PostgreSQL and authenticated S3 check.

The development services bind only to loopback:

- PostgreSQL: `127.0.0.1:5432`
- S3-compatible object storage: `127.0.0.1:8333`

The values in `.env.example` are development-only and must never be reused in a deployed
environment.

## Architecture

- [Platform architecture](docs/architecture/platform-architecture.md)
- [Repository boundaries](docs/architecture/repository-boundaries.md)
- [Repository workflow](docs/development/repository-workflow.md)
- [Testing](docs/development/testing.md)
- [Module development](docs/module-development/README.md)
- [Architecture decisions](docs/architecture/decisions/README.md)

No open-source license has been selected yet. A license should be added only after the project
owner makes that decision.