GJ-02 — Hierarchical Geographic Filters, Scopes and Optional Radius

Suggested branch: feature/gj02-geographic-search

Objective

Implement accurate, discoverable and accessible country/region/county/municipality/town filtering across Norway, Sweden and UK without relying on false flat hierarchies or substring matching.

User interaction contract (must not be changed silently)

Selecting Warwickshire alone: query the whole Warwickshire scope; all child checkboxes remain visually unchecked.
Expanding and selecting Warwick under selected Warwickshire: query Warwick only in that branch, not every other town in Warwickshire. Warwickshire remains shown as the selected scope being refined, with a clear summary Warwick only.
Add Royal Leamington Spa: query Warwick OR Royal Leamington Spa, excluding other Warwickshire areas.
Remove both towns while leaving Warwickshire selected: revert to the whole Warwickshire scope.
Separate selected branches (e.g. Warwick plus Bergen) combine as OR. Different filter dimensions (e.g. location + profession + languages) normally combine as AND.
Deselect a parent: remove or resolve its descendant filters visibly, with accessible announcement, never leave invisible active child selections.
A checked parent with refinements is not the conventional 'all descendants checked' tri-state checkbox. Design accessible controls as scope checkbox/selection plus separate refinement state; avoid misleading mixed-state semantics. Include explicit Whole area / Specific places options and a clear effective-filter summary if needed.

Engineering requirements

Inspect genuine geography sources and licences/versions. For Norway use authoritative county/municipality and locality datasets; Sweden län/kommun/settlements; UK ONS geography and appropriate settlement data. Handle UK county vs district vs built-up area accurately and atypical administrative cases (Oslo both county/municipality, UK unitary authority, etc.). Store canonical identifiers, types, country, parent relations, names/aliases, optional polygons/centroids/coordinates with provenance/version.
Build geographic taxonomy ingestion/update routines and mapping from provider source location codes/free text; allow unresolved/approximate classifications (never silently attach a job to the wrong town).
Support tree expansion without huge downloads, keyboard navigation, search-as-you-type town lookup, saved favourite locations and a compact filter summary/chips. Strictly preserve selected scopes when tree collapses.
Define semantic query plan translating geographic selections to filter over canonical IDs/polygons and provider-supported area fields. If provider can't do exact region filtering, use compliant local filtering or clearly disclose approximation and missing data; do not claim full provider coverage.
Optional town-centered radius (e.g. 10/25/50km), with geodesic distance, coordinates known/unknown rules, multi-origin OR semantics and units/localized display. Radius by distance is not a guaranteed travel-time commute. Keep a separate optional actual travel-time capability for later, only with a qualified routing provider.
Define remote jobs explicitly: fully remote, remote limited to country/region, hybrid/on-site and unknown. Remote must not bypass legally specified work location constraints.
Add indexes/performance checks for large country scopes, no 1,000-child checkbox DOM, data migration, stale taxonomy IDs and fallback on missing geographic data.

Test corpus

Warwickshire > Warwick and Royal Leamington Spa, deselect/reselect/expand/collapse, selected parent + descendants, sibling mixing, multiple-country OR.
Vestfold > Tønsberg/Sandefjord; Vestland > Bergen; Oslo municipality/county dual identity; Sweden Stockholm län > Stockholm municipality/town.
A posting geocoded only at county level must not be misreported as located within Warwick town.
Radius from Warwick includes known nearby locations when within requested geometric distance, and doesn't claim driving time.
Keyboard/screen-reader semantics and mobile compact filtering; frozen profile roundtrips.

Checkpoints/deliverables

GJ02-A taxonomy/source decision; GJ02-B canonical model/import; GJ02-C refinement state & UI; GJ02-D query mapping/radius; GJ02-E precision/performance/acceptance. Document under docs/global-jobs/02/. Commit/push each. Report location precision and provider coverage honestly. Stop after acceptance.

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.

8.6 KiB Raw Blame History