Releasing and handing over an AI-built MVP: what to prepare

## Quick start

```bash
git clone <repository-url> leads-mvp
cd leads-mvp
npm install
npm run dev
```

$ npm install
  4 high severity vulnerabilities
$ npm run dev
> tsx watch --env-file=.env src/server.ts
node: .env: not found

$ cp .env.example .env && npx tsx --env-file=.env src/server.ts   # next guess
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…\src\generated\prisma\client.js' imported from …\src\db.ts

# Leads MVP

API for the website contact form: stores leads in PostgreSQL and can notify
a Telegram chat about each new lead.

## Requirements

- Node.js 24 and npm 11 (`node -v`, `npm -v`)
- Docker with Compose v2 (`docker compose version`) for the local database
- Free ports: 3080 for the API and 55439 for PostgreSQL. To use other ports,
  change `PORT`, `DB_PORT` and the port in `DATABASE_URL` in `.env`

## Quick start from zero

Commands are for bash: macOS, Linux, WSL or Git Bash on Windows.

```bash
git clone <repository-url> leads-mvp
cd leads-mvp
cp .env.example .env
docker compose up -d --wait db
npm ci
npx prisma generate
npm run db:migrate
npm run db:seed
npm run check
npm run dev
```

In another terminal: `curl http://localhost:3080/health` returns
`{"status":"ok"}`.

## Commands

| Command | What it does |
| --- | --- |
| `npm run dev` | API with reload on file changes |
| `npm run check` | Type check and tests. Must pass before every merge |
| `npm run db:migrate` | Applies pending migrations (`prisma migrate deploy`) |
| `npm run db:seed` | Adds a demo lead. Local database only |
| `docker compose down` | Stops the database; add `-v` to delete its data |

## Project structure

- `src/app.ts` — HTTP routes and input validation
- `src/env.ts` — environment variables, checked at startup
- `src/db.ts` — database access (Prisma)
- `prisma/` — schema, migrations, seed
- `tests/` — API tests without a real database
- `docs/HANDOFF.md` — external services and account owners
- `docs/RELEASE.md` — release and rollback checklist

## Configuration

Every variable is listed with a comment in `.env.example`; a test fails
if the code reads a variable that is not there. Production values are set
in the hosting provider's settings and are never committed.

## Known limitations

- `POST /api/leads` has no rate limiting or captcha: spam is possible.
- Admin access is one shared `ADMIN_TOKEN`; there are no users or roles.
- If Telegram is unreachable, the request returns 500 after the lead
  is already saved, and a retry by the user creates a duplicate.
- `GET /api/leads` returns the latest 100 leads, without pagination.
- Tests use an in-memory store; the database is checked only by the
  quick start above.
- On 12 Oct 2026 `npm audit` reports 4 high-severity advisories in the
  dependencies of the `prisma` CLI (`mysql2`, `deepmerge-ts`). The suggested
  fix downgrades Prisma to 6.x, so it is not applied. Re-check after
  Prisma updates.

## Contacts

- Product owner: `<name, email>`
- Technical contact: `<name, email>`

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: leads
      POSTGRES_PASSWORD: leads_local_only
      POSTGRES_DB: leads
    ports:
      - "${DB_PORT:-55439}:5432"
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U leads -d leads"]
      interval: 2s
      timeout: 3s
      retries: 15

volumes:
  db-data:

# Copy to .env for local development: cp .env.example .env
# Production values live in the hosting provider's settings, never in git.

# PostgreSQL. The local value matches compose.yaml.
DATABASE_URL="postgresql://leads:leads_local_only@localhost:55439/leads"

# HTTP port of the API.
PORT=3080

# Token for GET /api/leads (Authorization: Bearer ...), at least 32 characters.
# Generate one: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
ADMIN_TOKEN="replace-with-a-random-string-of-32-plus-chars"

# Optional: Telegram notifications about new leads. Leave empty to disable.
TELEGRAM_BOT_TOKEN=""
TELEGRAM_CHAT_ID=""

import { z } from "zod";

const Env = z.object({
  DATABASE_URL: z.url(),
  PORT: z.coerce.number().int().positive().default(3080),
  ADMIN_TOKEN: z.string().min(32, "must be at least 32 characters"),
  TELEGRAM_BOT_TOKEN: z.string().optional(),
  TELEGRAM_CHAT_ID: z.string().optional(),
});

export type Env = z.infer<typeof Env>;
export const ENV_KEYS = Object.keys(Env.shape);

// Fails fast at startup with a list of what is missing, instead of a crash later.
export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
  const parsed = Env.safeParse(source);
  if (!parsed.success) {
    const problems = parsed.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`);
    console.error(`Invalid environment. Compare .env with .env.example:\n${problems.join("\n")}`);
    process.exit(1);
  }
  return parsed.data;
}

$ npx tsx src/server.ts   # started without --env-file, .env not loaded
Invalid environment. Compare .env with .env.example:
  - DATABASE_URL: Invalid input: expected string, received undefined
  - ADMIN_TOKEN: Invalid input: expected string, received undefined

import { readFileSync } from "node:fs";
import { expect, it } from "vitest";
import { ENV_KEYS } from "../src/env.js";

// .env.example is part of the handoff: it must list every variable the code reads.
it(".env.example documents every environment variable", () => {
  const documented = readFileSync(".env.example", "utf8")
    .split("\n")
    .map((line) => line.match(/^([A-Z0-9_]+)=/)?.[1])
    .filter(Boolean);
  expect(documented.sort()).toEqual([...ENV_KEYS].sort());
});

$ npx vitest run tests/env-example.test.ts   # SENTRY_DSN added to src/env.ts only
 FAIL  tests/env-example.test.ts > .env.example documents every environment variable
- Expected
+ Received
  [
    "ADMIN_TOKEN",
    "DATABASE_URL",
    "PORT",
-   "SENTRY_DSN",
    "TELEGRAM_BOT_TOKEN",
    "TELEGRAM_CHAT_ID",
  ]

{
  "scripts": {
    "dev": "tsx watch --env-file=.env src/server.ts",
    "start": "tsx --env-file=.env src/server.ts",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "check": "npm run typecheck && npm test",
    "db:migrate": "prisma migrate deploy",
    "db:seed": "tsx --env-file=.env prisma/seed.ts"
  },
  "engines": {
    "node": ">=24 <25"
  }
}

engine-strict=true

$ node -v
v24.18.0
$ npm ci   # test copy: engines.node ">=26", .npmrc engine-strict=true
npm error code EBADENGINE
npm error notsup Not compatible with your version of node/npm: leads-mvp@1.0.0
npm error notsup Required: {"node":">=26"}
npm error notsup Actual:   {"node":"v24.18.0","npm":"11.16.0"}

$ npm audit
deepmerge-ts  <8.0.0
Severity: high
mysql2  <=3.23.0
Severity: high
fix available via `npm audit fix --force`
Will install prisma@6.19.3, which is a breaking change
4 high severity vulnerabilities

# Handoff

## External services and account owners

| Service | Used for | Variables | Account owner | Others with access |
| --- | --- | --- | --- | --- |
| Git hosting | Code, CI | — | `<company account>` | `<names, roles>` |
| App hosting | Runs the API | `DATABASE_URL`, `ADMIN_TOKEN`, `TELEGRAM_*` | `<company account>` | `<names, roles>` |
| Managed PostgreSQL | Production data, backups | `DATABASE_URL` | `<company account>` | `<names, roles>` |
| Domain and DNS | `<api domain>` | — | `<company account>` | `<names, roles>` |
| Telegram bot | Lead notifications | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | `<company account>` | `<names, roles>` |
| AI assistant accounts and API keys | Development only | — | `<who pays>` | `<names>` |

## Access transfer

- [ ] Every account above is registered to a company email, not a personal one.
- [ ] The receiving team has admin access to each service.
- [ ] Access of people who leave the project is revoked or reduced.
- [ ] Secrets are rotated after the transfer: `ADMIN_TOKEN`, the bot token,
  the database password.
- [ ] Two-factor recovery codes are in the company password manager.
- [ ] Personal API keys used by AI assistants during development are revoked.

## Context

- Commands and rules for people and AI assistants: `AGENTS.md`.
- Limitations that are known and accepted: README, section Known limitations.

# Release and rollback

## Before the release

- [ ] `npm run check` is green in CI on the release commit.
- [ ] New migrations are reviewed. A release only adds columns and tables;
  removing or renaming happens in a later release, when no running version
  uses the old structure.
- [ ] A database backup is made and its file name is written in the release notes:

  ```bash
  pg_dump --format=custom --file="leads-$(date +%Y%m%d-%H%M).dump" "$DATABASE_URL"
  ```

- [ ] The release commit is tagged: `git tag v1.4.0 && git push origin v1.4.0`.

## Release

1. CI/CD deploys the tag and runs `npm run db:migrate` once.
2. `GET /health` returns `{"status":"ok"}`.
3. A test lead from the staging form reaches the database and Telegram.

## Rollback

1. Deploy the previous tag. This is safe when the release only added
   columns and tables: the old version ignores them.
2. If a migration must be undone, write a new migration that reverses it
   and release it as usual. Applied migrations are never edited.
3. Restore the backup only as a last resort: data written after the backup
   is lost.

   ```bash
   pg_restore --clean --if-exists --no-owner --dbname="$DATABASE_URL" leads-YYYYMMDD-HHMM.dump
   ```

$ pg_dump --format=custom --file="leads-$(date +%Y%m%d-%H%M).dump" "$DATABASE_URL"
leads-20261012-1410.dump
leads after an extra insert: 2
$ pg_restore --clean --if-exists --no-owner --dbname="$DATABASE_URL" leads-20261012-1410.dump
exit code: 0
leads after restore: 1

  // Documents a known limitation from README: the lead is saved, the response is 500.
  it("known limitation: a failed notification returns 500 after saving", async () => {
    const { app, notify, saved } = setup();
    notify.mockRejectedValueOnce(new Error("telegram unreachable"));
    const res = await request(app).post("/api/leads").send({ name: "Aigerim", phone: "+7 701 123 45 67" });
    expect(res.status).toBe(500);
    expect(saved).toHaveLength(1);
  });

$ git clone …/project leads-mvp
$ cd leads-mvp
$ cp .env.example .env
$ docker compose up -d --wait db
$ npm ci
  4 high severity vulnerabilities
$ npx prisma generate
  ✔ Generated Prisma Client (7.10.0) to .\src\generated\prisma in 25ms
$ npm run db:migrate
  Applying migration `20261012140759_init`
  All migrations have been successfully applied.
$ npm run db:seed
  seed: 1 lead(s) in the database
$ npm run check
   Test Files  2 passed (2)
        Tests  6 passed (6)
$ npm run dev
  [dev] leads-mvp listening on http://localhost:3080
$ curl http://localhost:3080/health
{"status":"ok"}
POST /api/leads → 201 {"id":2}
rehearsal finished in 27 s

import { createApp } from "./app.js";
import { createDb, createLeadStore } from "./db.js";
import { loadEnv } from "./env.js";
import { createNotify } from "./notify.js";

const env = loadEnv();
const db = createDb(env.DATABASE_URL);
const app = createApp({ leads: createLeadStore(db), notify: createNotify(env), adminToken: env.ADMIN_TOKEN });

// Express 5 passes a listen error (for example, a busy port) to this callback.
app.listen(env.PORT, (error) => {
  if (error) throw error;
  console.info(`leads-mvp listening on http://localhost:${env.PORT}`);
});

$ PORT=3000 npx tsx --env-file=.env server.before.ts   # first version, port 3000 is busy
leads-mvp listening on http://localhost:3000
exit code: 0

$ PORT=3000 npx tsx --env-file=.env src/server.ts      # fixed version
Error: listen EADDRINUSE: address already in use :::3000
exit code: 1