114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# 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.
|