jobtrackingapp/docs/decisions/ADR-002-job-application-model.md

ADR-002 — Separating Job (the opportunity) from JobApplication (the pursuit)

• Status: Accepted (partially implemented)
• Date: 2026-07-17
• Phase: 0 (foundation corrections)
• Supersedes: the 0-byte placeholder previously at docs/_archive/decisions/ADR-002-job-application-model.md

---

Context

docs/MASTER_IMPLEMENTATION_GUIDE.md names this as the product's #2 priority workflow:

Find Job → Import Job → Review Details → Prepare CV → Prepare Cover Letter
         → Add Supporting Files → Submit Application → Track Progress

docs/01-glossary.md is explicit that "A Job may exist before an application is submitted" and models the hierarchy as Company → Job Opportunity → Application.

The code could not represent any of that. The 2026-07-17 discovery audit found:

1. There was no Job entity. JobApplication was the only entity, carrying 43 members that mixed opportunity data (JobTitle, Description, JobUrl, Salary*, Deadline, Tags, Location) with application data (Status, DateApplied, ResponseReceived, FollowUpAt).
2. JobPipeline.Stages began at Applied. There was no Saved/Interested/Preparing.
3. DateApplied was non-nullable with a DateTime.UtcNow default.

Consequences:

• A job you had not applied to could not be tracked. The 6-step add-job wizard (components/AddJobModal.tsx) walks a user through preparing an application and then had nowhere to save it except Applied with a fabricated date.
• Applying twice to the same reposted role duplicated the entire job description.
• Teal — the market leader — offers Saved in its free tier. This was a table-stakes gap.

Decision

Split Job from JobApplication, additively and in stages. Phase 0 lays the foundation only.

Delivered in Phase 0

1. Job entity (JobTrackerApi/Models/Job.cs) — the opportunity: company, title, description, URL, location, salary, deadline, tags, plus SavedAt. Owner-scoped by the same deny-on-null global query filter as every other tenant entity.
2. JobApplication.JobId — a nullable FK to Job, OnDelete: SetNull.
3. Prospect stages — JobPipeline gained PipelineCategory.Prospect and the stages Saved(1), Interested(2), Preparing(3), ahead of Applied(4). No schema change: Status is a free-text column by deliberate prior design.
4. DateApplied is now nullable, and SavedAt was added to JobApplication.
5. JobPipeline.SyncAppliedDate — the single enforcement point for the invariant below.

Explicitly NOT done in Phase 0

• No dual-write. Nothing writes or reads Job yet. JobApplication remains the sole source of truth for every read and write.
• No backfill of Job rows. The table ships empty.
• No legacy columns dropped. JobApplication keeps its full copy of the opportunity fields.

This keeps Phase 0 a pure schema-and-vocabulary change with zero behavioural change to existing workflows, which is what "unblock future phases safely" requires.

Phase 1 status (2026-07-31)

Create and update paths now synchronize Job, and startup idempotently backfills a linked Job for every legacy application missing one. Reads and legacy columns remain unchanged until the production validation and observation release in docs/operations/job-opportunity-cutover.md complete.

The invariant

DateApplied is set if and only if the job has left the pre-application stages.

Enforced in exactly one place — JobPipeline.SyncAppliedDate(job, now) — called from all three status-write paths (POST /jobapplications, PUT /jobapplications/{id}, PATCH /jobapplications/{id}/status) so they cannot drift.

• Entering a real stage stamps DateApplied if unset.
• Moving back into a Prospect stage clears it.

The backward clear is deliberate. The alternative — a Saved job still carrying an applied date — would silently count it as applied in analytics and expose it to the follow-up/ghosting rules. The original date stays recoverable from the StatusChanged JobEvent history, so this is denormalised-field loss, not data loss.

Consequences

Safe by construction

• RulesEngine already whitelisted Applied/Offer/Rejected/Waiting and explicitly refused to ghost anything else, so prospects were never at risk. A JobPipeline.IsProspect guard was added anyway, ahead of any date arithmetic, plus a null-DateApplied guard on the Applied branch — a null must fail safe rather than read as "infinitely old" and auto-ghost the job. Covered by RulesEngineProspectTests.
• StageAnalytics already filtered to PipelineCategory.Active, so prospects drop out of time-in-stage automatically.

Deliberate behaviour changes

• DaysSince is now int?, null for prospects. Returning 0 would render as "Applied 0 days ago" — a lie. The API DTO and the frontend JobApplication type follow; the UI renders —.
• Applied-volume analytics and average-days-since-applied now filter DateApplied != null, so prospects cannot drag the average toward zero or inflate applied counts.
• JobFlowBar omits the "Applied" milestone entirely when there is no applied date.
• Custom (non-canonical) statuses are not treated as prospects. They predate this split and have always counted as applied; assuming otherwise would silently drop them out of existing users' analytics.

Costs accepted

• JobApplication temporarily carries both JobId and its own opportunity columns — real duplication, time-boxed to the Phase 1 cutover.
• An empty Jobs table ships. Preferred over a backfill that no code consumes and that a later, better-informed cutover might shape differently.

Migration notes (read before the next migration)

20260717071417_AddJobEntityAndProspectStages was hand-edited after scaffolding. dotnet ef migrations add additionally emitted CreateTable for TrustedDevices, TwoFactorRecoveryCodes, UserSessions and AddColumn for six AspNetUsers columns (Microsoft*, Totp*).

Those tables already exist in every real database — they were provisioned by the idempotent reconciler in StartupInitializationExtensions, not by a migration, so the prior ModelSnapshot did not know them and the scaffolder diffed them as missing. Verified directly against the live dev database: all three tables are present. Leaving the scaffolded statements in would have failed the deploy with "table already exists". They were removed; the reconciler still creates them on a fresh boot via CREATE TABLE IF NOT EXISTS.

IX_JobApplications_OwnerUserId_IsDeleted_Status was removed for the same reason: the reconciler applies it, and MySQL needs a Status(50) prefix length that the scaffolded DDL does not carry (see the comment in JobTrackerContext.OnModelCreating).

The regenerated snapshot now includes those tables, so future migrations will not re-scaffold them. This ADR's migration is the one that closes that drift.

EF emits a warning that the SavedAt backfill UPDATE runs while a rebuild of JobApplications is pending. Verified empirically against a copy of the real dev database (13 rows): the migration applies cleanly, all 36 pre-existing columns survive the rebuild, DateApplied values are preserved, SavedAt backfills correctly with no 0001-01-01 sentinels remaining, and DateApplied ends up nullable.

Phase 1 cutover plan

1. Done: dual-write Job on every persistence path (JobApplicationsController and Gmail suggestion creation; CSV import is preview-only).
2. Done: backfill one Job per existing JobApplication; link via JobId.
3. Flip reads to Job, one endpoint at a time.
4. Drop the duplicated opportunity columns from JobApplication.
5. Make JobId non-nullable.

A Job with no JobApplication row is the eventual clean representation of a saved-but-not-applied job. Until step 4, the Prospect stages on JobApplication.Status carry that meaning instead.

Alternatives considered

• Full split in Phase 0. Rejected: touches 38 endpoints, the Kanban, the table, the rules engine and the wizard at once, with no staging environment and a straight-to-prod deploy. The discovery report ranked this the highest-risk item in the plan.
• Prospect stages only, no Job entity. Would have unblocked the workflow, but leaves the duplication that makes applying twice to one role copy the whole description, and defers the schema foundation the roadmap's Phase 3/4 depend on.
• Keep DateApplied non-nullable, add SavedAt alongside. Rejected: a saved job would still carry a fabricated applied date — precisely the defect this ADR exists to remove.