jobtrackingapp/docs/release-checklist.md

# Release checklist

> **Historical snapshot (2026-07-19).** The current release gate and external dependencies are
> documented in `.gitea/workflows/ci-deploy.yml`, `docs/implementation-roadmap.md`, and `BLOCKERS.md`.

> 2026-07-19. State of the build before the first production deployment after the Phase 4/5
> architecture changes. Companion to `deploy/first-production-deployment.md` (how to deploy),
> `docs/production-readiness-review.md` (what was audited) and
> `docs/phase-5-completion-report.md` (what was built and why).

## Completed architecture work

| Area | State |
|---|---|
| **Career Profile** | Single source of truth. Relational children with stable item keys; `ProfileJson` is a derived projection. Nothing downstream writes to it. |
| **CV Builder** | Data-driven theme engine — themes are data, not hardcoded templates. Eight themes; adding one is appending an object. Variants are lenses over the master profile, never copies. Autosave, version history, restore. |
| **Public CV** | `/cv/{slug}`, off by default, per-variant opt-in, unguessable slug, `noindex`. SPA deep-link routing fixed so direct navigation, refresh and shared links resolve. |
| **Application Workspace** | `/applications/{id}`: Overview, Checklist, Timeline, Analysis, Match, CV, Cover Letter, Documents, Interview Prep, Communication. Owns almost no data — it composes systems that already existed. |
| **AI integrations** | Suggestion-only. Every generation appends to `AiInteraction` (that history *is* the versioning). Interview generation now receives the analysis and match context. Nothing AI-driven writes to the profile, a variant, a cover letter or prep content without the user saving it. |
| **Interview preparation** | User-owned `InterviewPrepItem`, distinct from the two AI *caches* that regenerate. Six categories in one table. |
| **Production hardening** | Explicit `[Authorize]` on every controller with a reflection test; clean MariaDB initialization; database ownership documented; pre-deploy backups; restore and rollback docs; health checks on backend and frontend. |

## Local verification

| Check | Result |
|---|---|
| Backend tests (Release) | 393 passed |
| Frontend tests | 128 passed, 36 suites |
| TypeScript | clean |
| Frontend production build | clean |
| Docker images | backend and frontend build |
| Fresh empty MariaDB 11 | 42 tables, starts healthy |
| Populated MariaDB restart | idempotent, rows preserved |
| Existing SQLite dev database | upgraded 34 → 44 tables, rows preserved |
| Backup and restore | dump verified, restored into a clean database, rows identical |

## Unresolved external blocker

### CI runner — deployment is gated on this

CI is red for a reason **proven to be outside the repository**: commit `8f73548` changed a single
markdown file — no code, no test, no dependency, no workflow — and its test job failed in the same
duration band as every other run. A change that cannot affect compilation cannot fail a test job.

Consequence: **everything above is local verification.** Nothing has been proven in CI, and the
deployment pipeline will not promote a build until this is fixed.

Blocked on, and needing you:

- Job logs — the API returns 401 unauthenticated; a read-scoped Gitea token would unblock this
- `journalctl -u act_runner --since '2 hours ago'` on the runner host
- The act_runner container/service configuration

Full evidence: `docs/infrastructure/runner-investigation.md`.

## Known risks

| Risk | Severity | Notes |
|---|---|---|
| Production is many commits behind | High | The first deploy applies the whole Phase 4/5 change at once. Reconciler builds ~12 tables against real data for the first time. |
| Reconciler path unproven on your data | Medium | Verified on containers and on a real SQLite dev database — not on production. This is what the backup is for. |
| Production journey unwalked | Medium | The CI-gated local browser suite covers login, saved-job creation, Career Workspace, and public CV/PDF. The same authenticated and OAuth checks still require production credentials. |
| Rollback loses new-table data | Medium | A code rollback keeps everything. A *database restore* discards rows created since the dump. Keep the deploy window quiet. |
| Logging is structured JSON on stdout | Low | Compose retains three 10 MB files per service; aggregation remains deployment-owned. |
| No global exception handler | Low | Unhandled errors return a bare 500 with no correlation id. No stack leaks outside Development. |
| `ClientErrorsController` is anonymous | Low | By design — browser error reports must work before sign-in. Size-limited and truncated; stores nothing. |
| Prompt quality unmeasured | Low | Interview generation gets richer context; whether the questions are *better* is a judgement no test makes. |

## First deployment warnings

1. **Take a manual backup as well, and restore it once to a scratch database.** `deploy.sh` backs up
   automatically, but the first deploy is the wrong time to discover a backup does not restore.
2. **Watch `docker compose logs -f backend` live.** `Database.Migrate()` throws on failure, so a schema
   problem exits the container. The runbook lists the exact log lines that mean stop.
3. **`DATABASE_PROVIDER` defaults to `sqlite`.** If it goes missing from `.env`, the backend does not
   quietly serve an empty database — it crashes with `no such table: INFORMATION_SCHEMA.TABLES`.
   Loud, but confusing if you have not seen it before.
4. **The connection string resolves from inside the container.** `Server=127.0.0.1` means the backend
   container, not the host.
5. **Empty new sections are expected.** Existing applications will show an empty Checklist, Timeline
   and Interview Prep until used. The checklist seeds on first open. That is correct behaviour.
6. **Verify row counts before walking away.** Applications and companies must match the pre-deploy
   numbers. This is the check that matters most.
7. **Do not restore the database for a code problem.** Roll the code back first; it is almost always
   the whole fix, and it costs no data.