Introduce country-specific adapter and configuration system

[SaitejaKommi]

Priority

P2

Area

Architecture / Extensibility

Problem

No standardized interface exists for defining a national food profile. Country assets (synonyms, brands, dataset paths, regulatory rules) are scattered across multiple directories without a unifying abstraction. New contributors to other national Open Food Facts chapters have no documented guide on how to add a country.

Why This Matters

Without an explicit configuration contract, adding a second country risks ad-hoc branching and copy-pasted code. A clean CountryProfile model allows international Open Food Facts chapters to plug in their datasets, languages, and dietary regulations cleanly.

Current Behaviour

• No CountryProfile model or configuration abstraction exists.
• Canadian synonyms live in backend/search/, brands in backend/data/, adapters in backend/adapters/.
• No documentation exists in docs/ for adding a new national food catalog.

Expected Behaviour

• A clearly defined CountryProfile or configuration interface exists.
• Canada is cleanly represented through the new profile abstraction as the default (CA).
• Country-specific synonyms, languages, and rules are isolated within the profile.
• Adding a country profile does not require modifying core retrieval logic.
• Tests cover at least the existing Canadian configuration.

Proposed Implementation

1. CountryProfile Model: Create backend/config/country_profile.py defining:
   • country_code: ISO alpha-2 (e.g. CA, IN, FR)
   • languages: Language extraction order (e.g. ["en", "fr"])
   • synonyms_file: Path to regional synonym definitions
   • regulatory_thresholds: Tolerances for sugar, sodium, calories
   • default_dataset_path: Expected Parquet location
   • index_alias: OpenSearch alias (e.g. askoff_products_ca)
2. Profile Registry: Provide a profile registry resolving active configuration via ASKOFF_COUNTRY=CA.
3. Contributor Documentation: Add docs/ADDING_A_COUNTRY.md guiding contributors step-by-step.

Acceptance Criteria

• A clearly defined country profile/configuration interface exists.
• Canada can be represented through the new abstraction without regression.
• Country-specific synonyms and rules are isolated.
• New country configuration does not require modifying core retrieval logic.
• docs/ADDING_A_COUNTRY.md is added.
• 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/config/settings.py`, `backend/adapters/base.py`, and `backend/search/synonyms_ca.py`.
Design a clean country configuration system:
1. Create `backend/config/country_profile.py` defining the CountryProfile model (country code, language priority, synonym file path, regulatory limits, index name).
2. Create profiles for Canada (default) in a structured profiles registry.
3. Update Settings to load the active profile based on an `ASKOFF_COUNTRY` environment variable.
4. Add `docs/ADDING_A_COUNTRY.md` documenting how external contributors can define a new country.
5. Write unit tests in `backend/tests/test_settings.py` validating profile registration.

Verification Plan

Run settings and configuration tests:

pytest backend/tests/test_settings.py -v
pytest backend/tests/ -v

Dependencies

Backlog ID 18

Maintainer Decision Required

A maintainer decision is required to approve the CountryProfile schema and configuration structure.

Out of Scope

• Implementing full datasets for all 150+ Open Food Facts countries.
• Real-time translation of foreign search queries.

Relevant Files

• backend/config/settings.py
• backend/config/country_profile.py
• backend/adapters/base.py
• backend/search/synonyms_ca.py
• backend/tests/test_settings.py
• docs/ADDING_A_COUNTRY.md