# 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:

```bash
pnpm install --frozen-lockfile
```

## Quality gates

```bash
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:

```bash
cp .env.example .env
pnpm infrastructure:up
```

Stop services or follow their logs with:

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