# 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. A Core-owned `pnpm doctor` dashboard now combines the existing
static discovery and read-only migration-planning services into one concise readiness report.
Phase 4 identity with Better Auth is next; production approval-provider composition, 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 doctor
pnpm migrations:plan
pnpm test:migrations:integration
pnpm verify
```

`pnpm doctor` builds the workspace first, then reports the supported Node.js runtime, installed
modules and dependency order, schema and migration inventories, optional read-only PostgreSQL
planning, and the current object-storage integration state. It never applies migrations, creates a
history table, starts module servers, or performs storage operations. Schema discovery does import
compiled schema-definition entrypoints; those entrypoints are contractually side-effect-free.

With no installed modules and no `DATABASE_URL`, the current repository produces a report shaped
like this:

```text
Ekklesia Doctor

Platform
  ✓ Runtime version supported
    Active Node.js satisfies the declared supported range.

Modules
  ✓ Module discovery complete
    0 modules installed
  ✓ Dependency graph valid
    Dependency order is empty.

Data definitions
  ✓ Schemas validated
    0 modules · 0 tables
  ✓ Migrations validated
    0 migrations · checksums valid

PostgreSQL
  ○ Connection check skipped
    DATABASE_URL is not configured.
  ○ Migration plan skipped
    A validated migration inventory and configured PostgreSQL connection are required.

Object storage
  ○ Check unavailable
    Core storage integration has not been implemented yet.

Result: READY WITH WARNINGS
```

Checks have stable pass, warning, failure, or skipped states. Warnings and skipped optional checks
produce `READY WITH WARNINGS` and exit zero; any failure produces `NOT READY` and exit one. The
dashboard is human-readable local guidance, not a replacement for automated CI evidence.

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