Skip to content
Tabletop Tracker

ADR-0010: Catalogue behind a CatalogueSource interface

ADR-0010: Catalogue behind a CatalogueSource interface

  • Status: Accepted
  • Date: 2026-07-30
  • Supersedes: —
  • Superseded by: —

Context

The BoardGameGeek XML API is the obvious catalogue source, but its terms are permissive for non-commercial use and require permission for commercial use. This project intends to earn eventually, so BGG must be asked in writing before any sync code is built (WI-H01).

That question is outside our control and gates build-order step 2 — which in turn gates collection, lists, discovery and search. Seven of nine steps stall behind an email.

Decision

Define a CatalogueSource interface in packages/catalogue with a hand-seeded fixture implementation behind it. BGG becomes one swappable implementation, added later.

Rationale

The licensing risk is real but it is a sourcing risk, not an architecture risk. Nothing downstream cares where a game record came from — only that it has designers, mechanics, weight and player count.

Putting the seam in now costs one interface and buys the ability to build everything else immediately.

Consequences

  • WI-H01 (the BGG email) blocks only WI-024 (the sync worker). It blocks nothing else.
  • The fixture implementation seeds roughly 200 games — enough for search, discovery and the twenty hand-seeded lists to be genuinely exercised and tested.
  • If BGG says no, the blast radius is one package. Alternatives (own catalogue, third-party APIs) swap in at the same seam.
  • Every consumer must depend on the interface, never on a concrete implementation. Enforced in review.

Alternatives considered

Own catalogue from the start. No licensing risk and full data ownership. Rejected: docs/architecture.md §4 calls this a multi-year slog, and it would dominate the entire build.

Wait for the BGG answer. Avoids building anything that might be thrown away. Rejected: stalls seven of nine build-order steps on an email whose timing we do not control — and the adapter means nothing would be thrown away anyway.