jobtrackingapp/automation/prompts/global-jobs-pack/01_GJ_00_DISCOVERY.md

GJ-00 — Product and Provider Discovery / Architecture Sign-off

Suggested branch: planning/int-global-jobs-00 | Mode: planning/research ONLY

Objective

Establish an evidence-backed implementation plan for international, multilingual, cross-industry job discovery, integrating with the real Jobjakt code and accepted roadmap, without changing application behaviour. You may perform this planning stage before Phase 10 completion, but code implementation requires later confirmed development entry.

Mandatory investigations

1. Verify current Git baseline and latest Phase 10 / PRODUCT-REVIEW-01 handoff. Inspect code for existing job imports, Kanban, Career Profile, search, preferences, geolocation, translations, notifications, dashboard, admin monitor, user/tenant authorization and MariaDB entities.
2. Map user journeys for new resident, multi-country mover, returning jobseeker, jobseeker with no formal occupation, and mixed jobs/shift work. Distinguish country of residence, nationality, desired search countries, ad language(s), UI language and document language.
3. Review current official API terms and capabilities for Norway (NAV feed including tombstones and consumer token; FINN partner-restricted), Sweden (JobTech JobSearch and JobAd Links, including truncation/attribution and classification), UK (Adzuna commercial agreement and description snippets; government/public-sector APIs where legitimately available); optionally Denmark/Germany/France/Netherlands as future prospects. Cite URL/access date. No claiming API access without proof.
4. Review authoritative geography: Norway county/municipality and locality; UK country/county/unitary authority/district/built-up area/town and overlap issues; Swedish län/kommun/tätort. Include immutable IDs, dataset version, ancestry, geometry/licence, alias/local names, postal code mapping where licensed, and provider data quality. Explicitly verify Warwickshire/Warwick/Leamington Spa, Vestfold/Tønsberg, Vestland/Bergen and Oslo edge cases.
5. Research ESCO multilingual occupation taxonomy, mappings to Swedish SSYK and UK SOC where viable; distinction among occupation, keyword, industry, required credential, skill, employer title and free text. Do not limit taxonomy to IT.
6. Determine options and costs for local index vs live provider queries, data updates/deletes and cache limits, rate limiting and search technology compatible with actual stack. Avoid adding Elasticsearch/third-party SaaS automatically.
7. Model source-rights metadata and per-provider capability gating. Document what can be fully displayed in-app vs preview-only vs external-link-only. Detail redirects/apply links, licences, price, approval needs.
8. Define privacy, PII retention, alert frequency and anti-spam, admin diagnostics, multi-tenant threats, disabled-source fallback and data lineage.

Produce

docs/global-jobs/00/PRODUCT_REQUIREMENTS.md, PROVIDER_RIGHTS_MATRIX.md, CROSS_INDUSTRY_TAXONOMY.md, GEOGRAPHY_DECISIONS.md, ARCHITECTURE_ADRS.md, DEPENDENCIES_AND_GATES.md, IMPLEMENTATION_CHECKPOINTS.md, ACCEPTANCE_MATRIX.md, OWNER_ACTIONS.md.

Architecture must include canonical SearchPreference, LocationNode, LocationScope, OccupationConcept, ProviderCapability, SourceAdvertisement, SourceLifecycleEvent, SavedJob, SavedSearch, and SearchAlert concepts, reconciled against existing names—not a mandate to create all those tables. Define data contracts and safe migration strategy, not code changes.

Sign-off

Identify GO / CONDITIONAL GO / NO-GO for design completeness and each proposed provider. Separate paid/approval/deployment gates. Commit and push planning docs. Do not implement features, register consumers on behalf of the user, or start GJ-01.

Shared rules for every INT-GLOBAL-JOBS-01 stage

• Product: Jobjakt, a general-purpose, commercial job-search and career-management SaaS. It is not an IT-only product. Current architecture includes React/TypeScript, .NET backend, MariaDB, an AI sidecar, existing Career Profile/CV/document/application features, and an established EN/NO localisation approach. Verify actual repository reality before making assumptions.
• Entry gates: Do not implement new global-job-discovery features until the authoritative Phase 10 and product-review/development-entry decisions permit this initiative. Planning-only reconnaissance may precede them. If an entry gate remains NO-GO, produce safe analysis and stop before code changes.
• Baseline: Find the latest accepted, integration-complete development commit by reading Git history and the latest authoritative acceptance reports. Do not assume main is current. main deploys production: NEVER merge to main or trigger production. Never change live MariaDB, Docker, Ollama, storage, secrets or other production services.
• Branches: Use the specified independent stage branch from the latest accepted development integration history including the preceding accepted stage. Verify ancestry, remote, clean tree and existing branch collisions. Use checkpoint commits; push each validated checkpoint; verify remote HEAD equals local HEAD. Do not force-push. Do not advance to another stage without its actual entry criteria.
• Autonomy: Investigate, design, implement, add tests, document, commit and push safe work without pausing for routine decisions. Stop only for external API agreements, new paid resources, security-risk acceptance, destructive changes, privileged infrastructure actions and production operations. Continue independent work when one provider or model capability is blocked.
• Sources: Integrate only documented, authorised sources. Verify current licensing, commercial eligibility, credentials, permitted display, storage, cache lifetime, update/delete/tombstone, attribution, user-click-through and rate-limit rules. No covert scraping, private APIs, stolen cookies, bypassing anti-bot controls or fetching protected listing content without authorisation. An external-link-only source is not a direct searchable provider.
• Data trust: All provider data, job descriptions and user-provided URLs are untrusted. Guard SSRF, XSS/unsafe HTML, prompt injection, HTML injection, unsafe redirects, credential leakage, denial of service and cross-user/tenant access. Do not present missing facts, inferred salaries, regulated-profession eligibility, or AI-generated job details as verified employer facts.
• Availability: Preserve offline/disabled provider states. Use realistic fixtures in automated tests; any live contract test needs authorised test credentials and bounded rates. Never claim unavailable external API functionality passed.
• User-facing quality: Desktop/tablet/phone, keyboard and screen-reader access, light/dark, EN/Bokmål plus future qualified locales, loading/empty/error states, responsive design, sensible defaults, performance, source transparency, internationalisation and accessible non-drag alternatives.
• Data integrity: Source advertisements and user-owned saved jobs/applications are separate records and lifecycles. Preserve existing Career Profile, historical CVs, cover letters, saved applications, revisions, RD21 protections and MariaDB compatibility. Follow source rules for removing or masking withdrawn advertisements, while handling user-owned records under a separately justified retention policy.
• AI: Existing live-model inference and semantic quality must remain gated unless separately qualified. Rule-based/ESCO-backed title suggestions and auditable matching should function without a generative model. Do not invent user qualifications or automate application submissions.
• Evidence: At every checkpoint provide exact tests (pass/fail/skip/not run), security/coverage evidence, dated docs, commit hashes, branch and remote verification. Report individual stage GO / CONDITIONAL GO / NO-GO; separate production NO-GO from development readiness.