Consumer Guide

This template is the starting point for new projects on the lenne.tech fullstack stack. The fastest path is the lt CLI — it scaffolds the repo layout, the env files, and the docker-compose stack in one go:

lt fullstack init

If you'd rather do it by hand, clone this template into a fresh repo and keep the upstream link via Template-Update-Workflow.

Setup wizard

Once the repo exists, run the setup wizard. On a fresh checkout it writes .env from .env.example (random secrets), starts Postgres + Redis via docker compose, concatenates feature schemas, applies migrations, and seeds demo operator accounts:

bun install
bun run setup

Flags: --bootstrap (DB bring-up on an existing .env), --skip-bootstrap (env file only), --skip-docker, --no-seed. Feature toggles live in src/config/features.ts (edit + bun run prepare:schema when you add feature-gated Prisma models). The env writer is idempotent — it refuses to overwrite an existing .env.

Environment contract

Two variables are mandatory regardless of feature toggles:

Var	Purpose
DATABASE_URL	Postgres connection string. Use the docker-compose alias postgres for local dev.
BETTER_AUTH_SECRET	32+ chars, rotate per project. Used to sign session cookies and JWTs.

.env.example (generated by the wizard) lists everything else conditionally. Email-provider env vars (SMTP_* or BREVO_API_KEY), field-encryption KEKs, and PowerSync tokens only appear when the relevant feature is on.

CI gates

The four gates the consumer project must keep green map 1:1 to the bun scripts the template ships:

bun run lint        # oxlint + oxfmt
bun run test:unit   # pure-function suite
bun run test:e2e    # integration + story suite
bun run test:types  # tsc --noEmit on tests/types
bun run test:coverage  # vitest --coverage; ≥80% src/core, ≥75% src/modules
bun run build       # bun build → dist/

.gitlab-ci.yml already wires lint → test → audit → build (see gitlab-ci-pipeline.story.test.ts for the contract). GitHub Actions / other CI runners can copy the same shape.

Where to put project code

Project-specific work lives in src/modules/ — never in src/core/. The Customization-Guide walks through the boundaries, the features.ts activation surface, and the model→service→controller→module pattern for adding a new resource.

If you find yourself wanting to change src/core/ for a generic improvement, read the Core-Contribution-Guide and send a PR upstream — every other consumer benefits.

Updating the template

When the template publishes a new release:

bun run sync:from-template
bun run prepare:schema
bunx prisma migrate deploy
bun run lint && bun run test:e2e && bun run build

See Template-Update-Workflow for the per- bucket details and the hard src/modules/ boundary.

Stability + breaking changes

The template promises a deprecation window before any breaking change ships and migration guides for every major bump — see API-Stability-Promise.

Outgoing webhooks

Project-issued webhooks follow the Webhook-Spec: HMAC- SHA256 signature, exponential-backoff retries, auto-disable after repeated failures. Live deliveries are inspectable through /admin/webhooks.