jobtrackingapp/docs/architecture/ai-career-assistant.md

AI Career Assistant (Phase 5)

Phase 5 (2026-07-18). The per-application AI Workspace: modules, prompt flow, provider abstraction, history model, extension points. Companion to cv-builder.md, career-profile-model.md, and MASTER_IMPLEMENTATION_GUIDE.md (AI philosophy). Verified against code + a running container.

Principle

AI assists the application workflow — it never replaces the user. Every module is suggestion only: it returns markdown the user reviews and copies. Nothing is applied automatically to the master profile, a CV variant, or the application. Every prompt carries the guardrail "preserve every factual claim — never invent employers, titles, dates, qualifications, or metrics." Job tracking stays the core product; the assistant improves the application it hangs off.

Where it lives

Each job application gains an AI Workspace tab (AiWorkspacePanel) in the job details dialog. It is the central place for all AI on that application. Pre-existing per-tab AI (candidate-fit, focus-plan, interview-prep) is untouched — the workspace is the unified, history-backed home for the Phase 5 modules.

Modules

AiWorkspaceService.Modules, all via ISummarizerService.SummarizeSectionAsync:

Module	Produces
job-analysis	Company/role/skills/tech/experience/education/soft-skills/responsibilities/salary/benefits/work-model/visa/language + summary + likely interview topics + confidence
career-match	Match % + reasoning, strengths, weaknesses, missing skills, most-relevant experience, suggested improvements
cover-letter	A tailored letter in one of 6 tones (professional, friendly, short, detailed, modern, traditional)
interview	Company research, likely/behavioural/technical questions, STAR answer outlines, prep checklist
application-review	Overall strength (rating), missing info, weak areas, ATS issues, grammar/clarity, formatting

Tailored CV is not re-implemented here — it is the Phase 4 CV Builder (CvVariant linked to the job application). The workspace links to it rather than duplicating it.

Prompt flow

job (JobApplication + Company) ─┐
                                ├─► AiWorkspaceService builds { instruction + guardrail, source }
master profile text ────────────┘        │
                                          ▼
                        ISummarizerService.SummarizeSectionAsync  ──►  ai-service (active provider)
                                          │
                                          ▼
                        AiInteraction (append-only history)  ──►  markdown suggestion to the UI

source = the job context (BuildJobContext) plus the user's master profile text (ApplicationUser.ProfileCvText). No profile fields are written; the text is read-only input.

History model

AiInteraction (JobTrackerApi/Models/AiInteraction.cs) is append-only — one row per generation, never overwritten. This is deliberately distinct from AiWorkspaceNote (a one-row-per-type cache for candidate-fit/focus-plan). History gives the user restore/reuse (re-surface a past result), compare (view two side by side), copy, and delete. ResultJson is { text, meta? }; Provider records which provider produced it. Each row also stores input/output character counts and a conservative estimated token count (characters ÷ 4); the estimate is provider-neutral because the sidecar currently returns text rather than provider billing metadata. Tenant-scoped (owner query filter), cascades with the application.

API (AiWorkspaceController, /api/jobapplications/{id}/ai): GET modules (+ current provider), POST generate, GET history?module=, DELETE history/{id}. GET /api/ai/usage returns current-month and all-time totals; the workspace displays the monthly calls and estimated tokens.

Provider abstraction

Generation goes through ISummarizerService to the ai-service. Ollama is primary; AI_PROVIDER names only the optional external fallback candidate. Fallback is sequential and requires administrator enablement, task approval, live Pro/user consent and the prompt cost/privacy ceiling. Each AiInteraction records the provider returned by the sidecar, plus bounded model/route metadata in ResultJson.meta; configuration alone is not treated as proof that a provider executed.

Per-request user-selectable providers remain intentionally unsupported. The server-side privacy policy selects a route, not the browser, and provider credentials remain deployment-only.

Extension points

• New module: add a key to AiWorkspaceService.Modules + a prompt builder + a switch arm. No new storage, controller, or UI wiring — the panel enumerates modules from AI_MODULES.
• New cover-letter tone: add to CoverLetterModes + ModeGuidance.
• Structured (JSON) results: swap a module's prompt for JSON and parse into ResultJson.meta; the UI already renders result.text as markdown and can read meta.
• Provider policy: add task types to the explicit server-side allowlist only after their payload, accounting and production checks pass; do not add browser provider overrides.

Security

Suggestion only; never overwrites user content; everything requires the user to copy it in. The ai-service stays backend-only (ai_internal network, X-Ai-Service-Token) — see current.md §16. Markdown renders React nodes (no dangerouslySetInnerHTML), so AI output has no HTML-injection path.