jobtrackingapp/docs/planning/global-jobs-prompts/00_MASTER_ORCHESTRATOR.md

Jobjakt — INT-GLOBAL-JOBS-01 — MASTER CODEX / ASTRA PROMPT

International, multilingual, cross-industry job discovery

Mission

Build Jobjakt into a trustworthy, professional job-discovery and application-tracking experience for everyone: educators, chefs, cleaners, nurses, drivers, retail workers, construction trades, engineers, office staff, IT professionals and every other occupation. Start with Norway, Sweden and the United Kingdom, using an extensible, provider-aware foundation that can add countries without rebuilding search. Make users' preferred countries and languages persistent rather than requiring repeated filtering.

All agreed product requirements are in scope:

1. During onboarding/Settings ask country of residence and separately one or more countries to search; never equate nationality, home country, residence and desired work countries. Save preferred regions/cities, occupation interests, skills, work arrangement and ad languages; apply defaults automatically at discovery; allow temporary overrides without modifying the user's profile. Support multiple named saved search profiles.
2. Provide country-aware interface language choices: English plus the selected country's local official language(s) prominently, with all other actually-supported UI languages under More Languages. Countries with several official languages and region-specific languages must be handled properly. Store interface locale, ad language filters and each CV/cover-letter language separately; never imply all translations already exist.
3. Universal occupational title autocomplete: multilingual title aliases and related occupations across all sectors, not developer-centric heuristics; optional skills-based suggestions; exact-title vs related roles vs open keyword; preserve local terms and original advert text. Use qualified ESCO and appropriate national classifications with explicit versioning and licences; support unknown/free-text occupations.
4. Accurate hierarchical locations: country → appropriate region/county → municipality/district → town/locality. Use provider-specific geographical adapters and authoritative canonical IDs/geometries, not substring matching. For example Warwickshire selected searches whole county; then selecting Warwick refines that branch to Warwick only while parent remains visibly selected; selecting Leamington Spa too searches both towns, not the rest of county. Other selected branches combine as OR. No automatic child-checkbox selection. Add optional radius/commute filtering around a location with explicit semantics for multiple selections, remote roles and missing coordinates.
5. Responsive results with persistent filters and three-column desktop design (filter rail, job list, in-app detail panel), and mobile full-screen detail; optionally expand panel to full Job Details page. Show as much authorised source information as available: full or truncated original description, employer, location, requirements, responsibilities, qualifications, salary with period/currency and predicted/estimated distinction, shift/hour schedule, working arrangements, contract, deadlines, original source, posted/updated time, and apply link. Sanitise content; show source completeness and provenance. Link original application method directly; do not fabricate anything.
6. Source adapters with capability flags: direct search, event feed + compliant local indexing, authorised details, URL bookmark/manual import, external search link; provider rules for licensing, caching, update, removal, attribution and click-through. Norway: NAV feed and manual FINN URL workflows; Sweden: JobTech sources; UK: investigate official and licensed aggregators such as Adzuna, job boards, public sector sources. No forbidden scraping. Providers may be disabled independently without preventing other countries from working.
7. Cross-provider deduplication (conservative confidence, separate source records, source labels), saved vacancies, application-tracker integration, job-specific CV and cover letter links, job expiry handling, saved searches, new-job alerts, optional commute radius, occupation/skills/qualification matching with reasoned evidence and no invented claims.
8. Admin source health, sync/index queues, API quotas, failures and job import events integrated where practical with Jobjakt's processing monitor; admin-only redacted diagnostics. Keep external advertisements separate from user applications.
9. Commercial product standards: scalable feed processing, accessible design, English and local languages, localisation coverage, strict multi-tenant security, privacy, GDPR-conscious data handling, good empty/disabled/failure UX, comprehensive cross-sector and cross-country test suites, metrics, rollback strategy.

Architecture and boundaries

Inspect the actual React, .NET, MariaDB and sidecar code and reuse existing auth, settings, dashboard, application tracker, Career Profile, CV Builder, documents, alerts, admin processing, multilingual framework, concurrency and migration patterns. Do not create a second job tracker or duplicate profile master. Build an explicit provider capability/rights manifest and canonical data contracts; separate job-ad inventory from user-owned saved/job-application records. Do not invent an unlimited global index or require AI for basic features.

Sequence (run one stage at a time)

• GJ-00 Discovery, access and architecture → 01_GJ_00_DISCOVERY.md (planning only)
• GJ-01 Country, language and search preferences → 02_GJ_01_PREFERENCES_I18N.md
• GJ-02 Geographic hierarchy, selection semantics and radius → 03_GJ_02_GEOGRAPHY.md
• GJ-03 Cross-sector occupation suggestions and queries → 04_GJ_03_OCCUPATIONS.md
• GJ-04 Provider adapters, rights and ingestion → 05_GJ_04_PROVIDERS.md
• GJ-05 Unified search UI and in-app listing details → 06_GJ_05_SEARCH_UI.md
• GJ-06 Saved searches, alerts, matches and tracking → 07_GJ_06_ALERTS_MATCHING.md
• GJ-07 Admin operations, hardening and resilience → 08_GJ_07_ADMIN_SECURITY.md
• GJ-08 Full QA and release qualification → 09_GJ_08_ACCEPTANCE.md

For each stage, read its full prompt, respect the shared rules, begin from the accepted predecessor baseline, implement safe checkpoints, commit/push each, provide actual acceptance verdict and stop without starting the next stage automatically. Stage 00 may run before Phase 10 only as non-mutating research. Later stages require the documented Phase 10 and product-review handoff and owner-approved scope. If an API requires commercial permission, generate exact operator steps and leave its connector blocked; do not misrepresent external links or sample data as full integration.

Provider research to verify anew at execution

• NAV feed and terms: https://navikt.github.io/pam-stilling-feed/ and https://arbeidsplassen.nav.no/vilkar-api
• FINN API eligibility: https://www.finn.no/api/
• Sweden JobAd Links: https://links.api.jobtechdev.se/ and JobTech official APIs (verify current names/availability)
• Adzuna search/terms: https://developer.adzuna.com/docs/search and https://developer.adzuna.com/docs/terms_of_service
• ESCO multilingual occupations: https://esco.ec.europa.eu/en/use-esco/use-esco-services-api
• UK geographic datasets: https://geoportal.statistics.gov.uk/

Cross-industry benchmark

Every major behaviour must be tested with examples spanning teacher/teaching assistant, chef/kitchen assistant, nurse/care worker, electrician/plumber/carpenter, driver/warehouse operator, shop assistant, cleaner, accountant/administrator, farm worker, and software developer. Include English, Bokmål, Swedish and other supported source terms; qualifications, shifts and multiple employment modes; do not optimise relevance exclusively for tech roles.

Final output

Report completed stage list, exact Git ancestry/commits, live-vs-fixture provider coverage by country, current user-facing capabilities, translation completeness, geography correctness, occupation coverage, data provenance/expiry, alerts and dedupe, performance, security and accessibility, all remaining external approvals/human tests, independent GO decisions and production withholding status. Never merge main or deploy. Stop after the approved stage.

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.