Architecture Decision Records
Design decisions made while building the Palworld TCG importer and game configuration. The initial records are kept inline below.
| Date | Decision | Status |
|---|---|---|
| 2026-07-16 | EN catalogue is canonical, JP joins as translations via the E-prefix rule | Accepted |
| 2026-07-16 | Parallels are separate printings with a single Standard finish | Accepted |
| 2026-07-16 | Printing slugs include the expansion code | Accepted |
EN Catalogue Is Canonical, JP Joins as Translations via the E-Prefix Rule
| Date | 2026-07-16 |
| Status | Accepted |
Context and Problem Statement
The official API serves two independent catalogues (EN and JP hosts) with unrelated internal ids. We needed one canonical catalogue plus a reliable join for the other language.
Decision Outcome
The EN catalogue is canonical (card identity, slugs, images, attributes). The JP catalogue joins as card-level translations.ja (name + rules text) and expansion-level translations.ja (name). The join key is the E-prefix rule: EN card_number = "E" + JP card_number (verified 100% — 241/241 at launch), and EN expansion code = "E" + JP code (EBP01 ↔ BP01, PR2026 unchanged). JP ids are never used for matching.
Consequences
- âś… Single source of identity; both global release languages (
en,ja) covered per the languages rule. - ⚠️ If a future set breaks the E-prefix convention, the join logic needs a per-set mapping.
Parallels Are Separate Printings with a Single Standard Finish
| Date | 2026-07-16 |
| Status | Accepted |
Context and Problem Statement
Parallel treatments (SP, SSP, OSR, TSP, TSR, SR suffixes on the card number) could be modeled either as finishes on one printing or as distinct printings. The API models them as distinct rows with their own card numbers, rarities and images.
Decision Outcome
Each parallel is a separate printing of the same base card (grouping key = card number with the suffix stripped), and every printing carries a single CardFinish.STANDARD finish. No CardFinish enum growth, no Postgres migration.
Consequences
- ✅ Mirrors the publisher’s own model (distinct numbers, rarities, artwork); each parallel gets its own image and price history.
- âś… No exhaustive finish-map churn across web/mobile.
- ⚠️ Filtering by “parallel vs base” goes through rarity, not finish.
Printing Slugs Include the Expansion Code
| Date | 2026-07-16 |
| Status | Accepted |
Context and Problem Statement
A printing slug built from the card number alone is not unique: ESOUL-001 exists in both ETD01 and ETD02 (the same Soul card ships in both trial decks). (expansion, card_number) is the actual unique key.
Decision Outcome
Printing slugs are the lowercased full card number, prefixed with the expansion code whenever the number does not already start with it — ebp01-004sp for regular cards, etd01-esoul-001 vs etd02-esoul-001 for the shared Soul card. Image destinations derive from the printing slug, so image files are unique too (the number suffix already encodes the parallel/rarity, avoiding the TCGCSV image-collision bug class).
Consequences
- âś… The ESOUL cards dedupe cleanly; the ESOUL-001 card gets two printings, one per trial deck.
- ⚠️ Slugs are longer than strictly needed for the 99% of numbers that are already unique — accepted for uniformity.