Architecture Decisions

Every structural decision in this project is documented here with the reason behind it. Architecture is not decided by instinct — it is decided consciously and recorded.

When we make a new structural decision — where a file goes, why a module is split, why a pattern was chosen — it gets recorded here before or immediately after the commit. The full, evolving record lives in ARCHITECTURE.md at the project root, built out across Sessions 36 and 40, and finalized in Session 44.

Entry Format

Decision: What we decided.

Session: When we decided it.

Why: The reasoning.

Alternatives considered: What else we could have done.

Consequence: What this decision requires or prevents in the future.

ADR-001 — Repository Pattern for Data Access Session 24

Decision: Wrap all data access behind a CountryRepository class with a stable get_all()/find_by_region()/search() interface.

Why: Application logic should not need to know or care whether data comes from an in-memory mock list, a JSON file, or a real API. Proven across three genuinely different data sources by Session 38 with zero changes to the repository's own methods.

Alternatives considered: Letting every part of the app import mock data directly. Rejected — this would tightly couple application logic to one specific data source.

Consequence: Any future data source must be adapted to return data in the same raw shape the repository expects.

ADR-002 — Package Structure by Responsibility Session 32

Decision: Split the growing single file into a country_explorer package with models.py, repository.py, validators.py, formatting.py, and search.py.

Why: Grouping by responsibility keeps each module focused and easier to navigate as the project grows.

Alternatives considered: Splitting by curriculum layer instead. Rejected — responsibility-based grouping stays meaningful independent of how the curriculum itself is structured.

Consequence: Every new piece of cross-cutting logic must be evaluated for which existing module — or a new one — it belongs in.

ADR-003 — Prop Drilling in Composed UI-Layer Classes (Unresolved) Session 35

Decision: None yet — documents a known problem, not a fix.

Why this is a problem: A layered App → NavigationPanel → MenuSection → CountryExplorer structure requires every intermediate layer to forward a reference it does not otherwise use.

Status: Deliberately left unresolved. A future iteration might explore a shared context object or dependency injection.