Ekklesia/docs/development/repository-workflow.md

Repository workflow

Prerequisites

• Node.js 24 LTS (.node-version and .nvmrc pin the reviewed patch)
• pnpm 11.12.0
• Docker with the Compose plugin for local infrastructure

Install dependencies from the committed lockfile:

pnpm install --frozen-lockfile

Quality gates

pnpm format:check  # formatting without mutation
pnpm lint          # Biome recommended rules
pnpm boundaries    # architectural directions, UI ownership, and cycles
pnpm typecheck     # strict TypeScript
pnpm test          # Vitest
pnpm build         # Turborepo package build graph
pnpm verify        # every code gate above

CI runs pnpm ci, which adds Compose configuration validation to pnpm verify.

Development infrastructure

Create an untracked local environment file before using Compose:

cp .env.example .env
pnpm infrastructure:up

Stop services or follow their logs with:

pnpm infrastructure:down
pnpm infrastructure:logs

PostgreSQL and the S3 endpoint bind to 127.0.0.1 only. Compose uses persistent named volumes; infrastructure:down preserves data. The S3 service creates the configured development bucket idempotently at startup.

The checked-in credentials are safe only for local development. Deployed secrets must come from an environment-appropriate secret provider and must not be committed.

Docker is not installed in every contributor environment. pnpm infrastructure:config and live service health therefore run separately from the code-only pnpm verify gate.