# NoteLett Release Notes Template And Production Deploy Checklist

Date: May 5, 2026
Product: NoteLett (`notelett`)

## Release Notes Template

```markdown
# NoteLett Release YYYY.MM.DD

## Summary

- What changed:
- Who is affected:
- Primary operator:
- Release commit:

## User-Facing Changes

- Web:
- Mobile:
- Backend/API:
- AI/Smart Actions:

## Operational Changes

- New or changed environment variables:
- Data migrations or backfills:
- Feature flags or kill switches:
- Monitoring dashboards/alerts:

## Verification

- Backend typecheck/test/build:
- Web typecheck/test/build/E2E:
- Mobile lint/typecheck/test:
- Docker image build:
- Compose smoke:
- Platform dependency smoke:
- Secret/color/token audits:

## Known Deferrals Or Risks

- Deferral:
- Owner:
- Follow-up issue/roadmap item:

## Rollback Plan

- App/backend rollback target:
- Database rollback/backfill reversal:
- Feature flag or kill-switch action:
- Smoke checks after rollback:
```

## Required Environment Variables

Backend production must fail closed unless these are configured intentionally:

| Variable | Notes |
| --- | --- |
| `NODE_ENV=production` | Production validation is stricter than local compose smoke. |
| `PORT=4016` and `HOST=0.0.0.0` | Match service routing and container health checks. |
| `PRODUCT_ID=notelett` and `SERVICE_NAME=notelett-backend` | Product/service identity. |
| `JWT_SECRET` | Strong production secret or production auth verification equivalent. |
| `DB_PROVIDER=cosmos` | Production must not use memory datastore. |
| `COSMOS_ENDPOINT`, `COSMOS_KEY`, `COSMOS_DATABASE` | Cosmos database connection. |
| `FIELD_ENCRYPT_ENABLED=true` | Required for production. |
| `FIELD_ENCRYPT_KEY_PROVIDER` | Use AKV or managed production key provider. |
| `PLATFORM_SERVICE_URL` | platform-service base URL. |
| `EXTRACTION_SERVICE_URL` | extraction-service base URL. |
| `MCP_SERVER_URL` | common-platform MCP server base URL. |
| `TELEMETRY_ENABLED=true` | Enable when platform telemetry is available. |
| `FEATURE_FLAGS_ENABLED=true` | Enable when platform feature flags are available. |
| `LLM_PROVIDER` and provider credentials | Use mock only for non-production. |

Web production build/runtime must set:

| Variable | Notes |
| --- | --- |
| `NEXT_PUBLIC_NOTES_API_URL` | Browser-reachable NoteLett backend `/api` URL. |
| `NEXT_PUBLIC_PLATFORM_SERVICE_URL` | Browser-reachable platform-service `/api` URL. |
| `NEXT_PUBLIC_EXTRACTION_SERVICE_URL` | Browser-reachable extraction-service URL where used. |
| `NEXT_PUBLIC_MCP_SERVER_URL` | MCP server `/api` URL, default local port `4007`. |
| `NEXT_PUBLIC_TELEMETRY_TRANSPORT=fetch` | Production telemetry transport. |

Mobile production builds must set:

| Variable | Notes |
| --- | --- |
| `EXPO_PUBLIC_NOTES_API_URL` | Device-reachable NoteLett backend `/api` URL. |
| `EXPO_PUBLIC_PLATFORM_SERVICE_URL` | Device-reachable platform-service `/api` URL. |

Do not place secrets in `NEXT_PUBLIC_*` or `EXPO_PUBLIC_*` variables.

## Pre-Deploy Checklist

- Confirm release commit is pushed and CI is green.
- Confirm `pnpm run audit:release-guards` passes.
- Confirm `pnpm run dependency:health` has no typecheck failures; review the non-blocking outdated report.
- Confirm backend, web, and mobile tests from `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P10 have passed or have explicit release-owner signoff.
- Confirm Docker images build in CI.
- Confirm common-platform services are deployed and reachable: platform-service, extraction-service, mcp-server, telemetry, diagnostics, flags, kill switch, blob.
- Confirm telemetry events and diagnostic breadcrumbs follow `docs/TELEMETRY_AND_DIAGNOSTICS_TAXONOMY.md`.
- Confirm Cosmos database, containers, partition keys, backups, and retention policy are ready.
- Confirm field encryption provider and key material are ready.
- Confirm feature flags and kill switch defaults are safe for release.
- Confirm mobile build identifiers and URLs match `docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`.

## Migration And Seed Checklist

- Run `pnpm run seed:bootstrap` with production backend environment; see `docs/SEED_BOOTSTRAP_STRATEGY.md`.
- Built-in prompt templates and intake rules are seeded idempotently.
- Default workspace/bootstrap behavior is per-user and deterministic.
- Cosmos schema changes are backward compatible or have a documented backfill in `docs/DATA_MIGRATION_AND_BACKFILL_PLAN.md`.
- Encrypted-field migrations have a dry-run and rollback note.
- Long-running backfills have owner, estimated duration, progress logs, and stop criteria.
- No migration relies on client-side public environment variables for secrets.

## Deploy Steps

1. Announce deploy window and freeze unrelated production changes.
2. Deploy common-platform dependencies first if their API contracts changed.
3. Deploy NoteLett backend image.
4. Run backend readiness and dependency checks:
   - `GET /health`
   - `GET /api/bootstrap`
   - `GET /api/diagnostics/readiness`
5. Deploy web image and verify root route loads.
6. Publish or distribute mobile build after backend/web smoke passes.
7. Run release smoke checks:
   - `docs/PLATFORM_SMOKE_CHECKS.md`
   - `scripts/compose-smoke.sh` in Docker-capable environments where appropriate
   - `docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`
8. Watch logs and telemetry for at least 30 minutes after deploy.

## Rollback Checklist

- Keep previous backend and web image tags available.
- Prefer feature flag or kill-switch rollback for risky UI/AI behavior before image rollback.
- If backend rollback is required, confirm the previous image can read any newly written documents.
- If a migration/backfill ran, follow its rollback section before reverting code that depends on the new schema.
- After rollback, rerun:
  - `GET /health`
  - `GET /api/bootstrap`
  - one authenticated workspace/note flow
  - web root smoke
  - mobile auth and note list smoke if mobile users were affected

## Monitoring Links To Fill Per Environment

| Area | Link |
| --- | --- |
| Backend logs | TBD |
| Web logs | TBD |
| platform-service logs | TBD |
| extraction-service logs | TBD |
| mcp-server logs | TBD |
| Cosmos metrics | TBD |
| Telemetry dashboard | TBD |
| Diagnostics dashboard | TBD |
| Error/crash reporting | TBD |
| CI workflow run | TBD |

## Release Record

After release, append a record or link to the release notes containing:

- release commit hash
- deployed image tags/build ids
- migration/backfill ids
- smoke result summary
- incidents or rollback actions
- follow-up tasks