# Smart Gmail Job Correspondence Integration

## Phase split

### Phase 1
Deterministic, high-trust Gmail job correspondence integration:
- OAuth/account connection
- token refresh lifecycle
- sync-state tracking
- manual sync/backfill
- dedup by Gmail message id
- deterministic job-linking + confidence routing
- review queue for medium-confidence items
- unmatched thread suggestions
- global inbox + per-job timeline

### Phase 2
Prepared, not deeply implemented in this slice:
- semantic Gmail-to-job disambiguation
- richer recruiter/company/role extraction
- stage/status hinting
- interview/rejection/offer extraction
- follow-up/reply suggestion generation

## Foundation decisions

- Phase 1 remains useful without AI/Ollama.
- Deterministic evidence remains the primary truth source.
- Future AI enrichment attaches reasons/confidence alongside deterministic evidence rather than replacing it.
- Gmail sync state is now durable on the Gmail connection record:
  - `LastSyncAttemptedAt`
  - `LastSyncSucceededAt`
  - `LastSyncMode`
  - `LastSyncSource`
  - `LastSyncStatus`
  - `LastSyncError`

## Current code seams

- Gmail OAuth and token lifecycle: `JobTrackerApi/Services/GmailOAuthService.cs`
- Gmail endpoints: `JobTrackerApi/Controllers/GmailController.cs`
- Gmail connection persistence: `Models/GmailConnection.cs`
- Correspondence persistence: `Models/Correspondence.cs`
- Per-job correspondence UX: `job-tracker-ui/src/components/Correspondence.tsx`
- Future Phase 2 AI seam: `JobTrackerApi/Services/GmailCorrespondenceEnrichment.cs`

## What Phase 2 should plug into later

The `IGmailCorrespondenceEnrichmentService` seam is intended to accept normalized Gmail message/thread context and return optional semantic hints:
- probable job match
- richer confidence rationale
- extracted recruiter/company/role entities
- lightweight stage hints

Phase 1 should never require this service to return anything useful. The default runtime implementation remains a no-op.