jobtrackingapp/docs/remaster/MIGRATION_PLAN.md

Migration / Remaster Plan — Job Tracker

Companion to: REMASTER_PROPOSAL.md · Decision: REBUILD_DECISION.md

Strategy: incremental, test-guarded, feature-branch per unit (matches .gsd D017 slice discipline and the project's no-direct-main / conventional-commit rule). The 135 backend integration tests + 23 frontend suites are the safety net that makes internal change low-risk. No big-bang.

Guardrails per slice

1. Branch off main; conventional commit; no direct main pushes; no auto-merge.
2. dotnet build -c Release + dotnet test JobTrackerApi.Tests green before commit.
3. Frontend: full Jest suite green.
4. One PR per slice → one CI run on the Pi (single-capacity runner).
5. Behaviour preserved; add a targeted test if a slice exposes a coverage gap.

Wave 1 — Performance (lowest risk, highest ROI) — this was the paused Phase 7 work

• P1. Hot-path indexes (Data/JobTrackerContext.cs + one migration): IsDeleted, (IsDeleted,Status), FollowUpAt, Correspondence.JobApplicationId, JobEvent.JobApplicationId. SQLite+MySQL safe.
• P2. Server-side aggregation for GetStats/GetAnalyticsOverview (no full-table ToListAsync).
• P3. Gmail N+1 batch fixes (:646, :701, :893) + FirstOrDefaultAsync for review decisions.
• P4. RuleSettings cache in IMemoryCache (short TTL, per user).
• AI provider router in app.py (AI_PROVIDER={ollama|gemini|groq}) + /health reports provider; default stays ollama (keyless). Prod .env sets AI_PROVIDER=gemini + rotated key → offloads the 1060.

Wave 2 — Safe refactors (behaviour-preserving)

• R1. Extract services from JobApplicationsController: AnalyticsService, JobStatsService, CvContextBuilder. Controller shrinks to a thin adapter.
• R2. Extract GmailImportService + GmailThreadRefresher from GmailController.
• R3. DTO extraction for JobApplicationsController/ProfileCvController/GmailController.
• New files under Controllers//Services/ so the JobTrackerBackend glob picks them up; no Program.cs DI churn beyond registering the new services.

Wave 3 — Data-model evolution (additive migrations + backfill)

• D1. Attachment booleans → computed. Migration + backfill verification test; then drop stored columns.
• D2. Single tailored-CV source. Migrate TailoredCvText → TailoredCvDraft; deprecate the string.
• D3. Split JobImportContent 1:1 off JobApplication.
• D4. CvVersion + CoverLetter first-class tables (enables real versioning promised by the product). Each is a reversible EF migration; run against a SQLite dev DB and a MariaDB staging copy before prod.

Wave 4 — AI hardening + UX

• A1. Prompt-injection delimiters + input normalisation; factuality diff vs StructuredCvProfile.
• A2. Match-score synonym map + relabel; matched/missing breakdown in the UI.
• U1. Import partial-parse state; dedicated application-answer field; AI-fabrication confirm UI.

Wave 5 — Frontend platform (decide first)

Resolve the .gsd "use next.js" override deliberately:

• Least churn: CRA → Vite (drops most transitive-vuln debt, keeps React/MUI, fast).
• If public/SEO product: Next.js (honours the override; SSR/routing/metadata) — larger effort. Do this as its own milestone, not coupled to backend work.

Risk assessment

Risk	Likelihood	Mitigation
Migration data loss (Wave 3)	Low	additive + backfill + staging dry-run on MariaDB copy + backups (already automated)
Behaviour regression in extraction	Low	135 integration tests lock the API contract
Single-runner CI bottleneck	Medium	one PR per slice; keep slices small
Provider-router auth leak	Low	key from env only; never logged/committed; rotate the pasted key
Frontend migration churn	Medium	isolate as its own milestone; feature-flag if needed

Preserve vs discard

• Preserve unchanged: auth (cookie+CSRF), SSRF ingestion guard, global query filters, deterministic services, AI HTTP boundary, background-service model (single-node), test suites, deploy pipeline.
• Refactor before reuse: the three god controllers, JobApplication entity, prompt construction.
• Discard: attachment boolean columns (after backfill), inline TailoredCvText/CoverLetterText strings (after migration), scraper reliance as a guarantee (keep as best-effort).
• .gsd logic: treat as historical design intent (already mostly realised); resolve the two open items (next.js override, notes-block workaround). The .gsd folder is git-ignored and stays out of the repo.