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.

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:

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

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

4.7 KiB Raw Blame History

Ekklesia

Current status

Quick start

Architecture

4.7 KiB

Raw Blame History