Core concepts
Identity resolution
"Lakeside FC 2014B Blue" and "Lakeside 14B Blue" are one team. Two sources describing one game become one fixture — and every merge is reversible.
Sources name things in their own terms. Resolution maps each (source, external_id) to a canonical entity in four stages: a known external id; structured fuzzy matching on name tokens, birth year, gender and club; embedding candidates for the spellings token rules miss; then a threshold.
- Above the threshold, the external id is mapped onto the existing entity — a mapping row, never a canonical mutation.
- In the review band, the entity is created and the pair waits in the operator review queue with the evidence per signal.
- A wrong merge is one undo: approval repoints mappings and sets a pointer, so reversing it restores exactly what was.
The thresholds are set from a labelled evaluation set, not taste, and sibling teams that differ only by color ("2014B Blue" vs "2014B White") can never auto-merge no matter how alike the rest looks. For consumers this is invisible: you read one fixture with one id, whose external_ids object lists what every source calls it.