jobtrackingapp/docs/architecture/ai-privacy.md

AI privacy and external-processing policy

Updated: 2026-08-09

The default execution mode is local-only. External processing of /cv/* payloads requires all of:

1. Ai:ExternalProcessingEnabled=true on the backend;
2. EXTERNAL_AI_ENABLED=true on the AI sidecar;
3. a configured external Ai:ExternalProvider / AI_PROVIDER (gemini or groq);
4. a current Pro/Admin entitlement resolved from the database;
5. AI enabled in the user's server-side settings; and
6. the user's explicit ExternalAiProcessingAllowed opt-in.

The backend adds X-Ai-External-Allowed: true only after that live policy check. Durable workers use the same header only from their admitted policy snapshot after a live execution-time recheck, and also send the bounded task type. The sidecar otherwise routes /cv/* to Ollama even when an external provider is configured. /summarize always uses the local summarization model. Provider keys remain server-side and are never returned by the settings API.

GET/PUT /api/ai/settings owns the user settings. Disabling AI takes effect on the next protected request and is also rechecked by the current enrichment and queued-CV workers. Existing users migrate with AI enabled to preserve current behaviour; external consent always defaults to false.

AI-002 makes provider execution local-first and sequential. External fallback additionally requires an allowed task and stays below the configured per-request prompt ceiling. Actual provider/model/route metadata is returned by the sidecar and persisted by AI Workspace or durable operations. The process-local circuit and health diagnostics expose no prompt or credential data.

This is not permission to enable external processing globally. New durable task types remain local until explicitly allowlisted; AI-003/004 must minimize their exact payloads and complete cross-feature monthly accounting before rollout. EXTERNAL_AI_ENABLED=false or Ai:RoutingMode=local_only is the immediate rollback switch.