Design country-agnostic search architecture

[SaitejaKommi]

Priority

P2

Area

Core Architecture

Problem

Core search components currently contain hardcoded Canadian assumptions: synonyms_ca.py directly imported in mappings.py and pipeline.py; Sobeys' Canadian private label adapter (compliments_adapter.py) coupled in base adapters; Canadian regulatory limits (0.5g zero sugar, 0.12g low sodium) hardcoded in regex; and language priority hardcoded to EN/FR.

Why This Matters

Open Food Facts is a global open database spanning over 150 countries. If the search architecture tightly couples Canadian assumptions into core modules, supporting another national chapter requires forking or duplicating the entire repository. Decoupling ensures long-term maintainability and global reusability.

Current Behaviour

• backend/search/mappings.py and backend/query/pipeline.py directly import synonyms_ca.py.
• backend/adapters/compliments_adapter.py is coupled in backend/adapters/.
• Canadian regulatory tolerances (zero_sugar_tolerance = 0.5g, low_sodium = 0.12g) are hardcoded in backend/query/constraint_extractor.py.
• Language priority in backend/utils/off_parser.py hardcodes ('en', 'main', 'fr').
• backend/config/settings.py defaults dataset path to Canadian files.

Expected Behaviour

• Country-specific assumptions are identified and separated from core search logic.
• Architecture supports adding another country without duplicating or copying the service.
• Maintainer-facing architecture documentation is provided.
• No country-specific Canadian behaviour is broken or regressed.

Proposed Implementation

1. Decouple Synonym Loading: Refactor synonym loading so that analyzers receive a generic list of synonym pairs from configuration rather than directly importing synonyms_ca.py.
2. Configurable Regulatory Limits: Move Canadian nutrient thresholds into a configurable settings/profile structure.
3. Parameterize Languages: Allow language extraction priority to be configured via environment settings.
4. Architecture Documentation: Document the country-agnostic architecture in docs/architecture/COUNTRY_AGNOSTIC_ARCHITECTURE.md.
5. Preserve Compatibility: Keep Canada (CA) as the default configuration with zero regressions.

Acceptance Criteria

• Country-specific assumptions are identified and isolated.
• Core search logic is separated from country-specific configuration.
• Architecture supports adding another country without copying the service.
• All 148 existing backend tests pass with Canadian defaults.
• Maintainer-facing architecture documentation is provided.
• Existing behaviour is not regressed.
• Appropriate regression tests are added.
• Documentation is updated where necessary.

Implementation Prompt

First inspect the existing implementation and tests before making changes. Understand the current behaviour and identify the smallest appropriate change. Implement the requested functionality without unrelated refactoring. Add or update regression tests. Run the relevant tests, linting/type checks, and verification commands. Do not modify unrelated components.

Inspect `backend/search/mappings.py`, `backend/search/synonyms_ca.py`, `backend/query/pipeline.py`, `backend/query/constraint_extractor.py`, and `backend/config/settings.py`.
Refactor Canadian-specific logic into modular country configurations:
1. Parameterize synonym loading in `mappings.py` and `pipeline.py` so they depend on a generic synonym provider rather than hardcoded `synonyms_ca`.
2. Move hardcoded Canadian nutrient thresholds in `constraint_extractor.py` into `backend/config/settings.py` with Canadian defaults.
3. Allow language resolution order in `off_parser.py` to be set via configuration.
4. Ensure default configuration remains 'CA' and all 148 backend unit tests pass without regression.

Verification Plan

Run full test suite and verify clean Canadian operation:

pytest backend/tests/ -v
ruff check backend/

Dependencies

None

Maintainer Decision Required

A maintainer decision is required to review and approve the country configuration interface before refactoring core search logic.

Out of Scope

• Deleting the Canadian synonym dataset or Compliments adapter.
• Building multi-tenant routing proxies in this issue.

Relevant Files

• backend/search/mappings.py
• backend/search/synonyms_ca.py
• backend/query/pipeline.py
• backend/query/constraint_extractor.py
• backend/utils/off_parser.py
• backend/config/settings.py
• backend/adapters/compliments_adapter.py