martj42/international_results

This repository is a curated data package, not an application. Its architecture is centered on a small set of CSV assets that together describe historical men’s international football matches from 1872 through 2024.

1. Primary purpose

The repo exists to provide a “semi-definitive” machine-readable archive of international match history. There is no executable code, backend, or UI layer; the main interface is the data files themselves.

2. Core dataset: results.csv

This is the primary fact table. Each row represents one match and carries the match date, teams, scoreline, tournament, venue city/country, and a neutral flag. This file is the central hub for most analysis and is the baseline dataset other files augment.

3. Derived match detail: shootouts.csv

This file adds penalty shootout outcomes for matches that were decided that way. It is keyed by the same match identity fields as results.csv (date, home_team, away_team) and supplies post-match resolution data: shootout winner and which side shot first.

4. Derived player detail: goalscorers.csv

This file is a second match-linked extension of the main results data. It stores goal-level events: who scored, for which team, and whether it was an own goal or penalty. In architectural terms, it is a one-to-many child table of match results.

5. Normalization/supporting mapping: former_names.csv

This file exists to reconcile historical team names with current team identities. The README makes clear that home/away teams use current successor names, while country names reflect the place name at the time of the match. This mapping layer is important for longitudinal analysis and prevents historical naming drift from fragmenting team statistics.

6. Data modeling boundary

The repo separates three layers of information:

- match outcomes in results.csv

- shootout outcomes in shootouts.csv

- scoring events in goalscorers.csv

This separation keeps the base match record clean while allowing optional detail tables to enrich it.

7. Identity and join strategy

The consistent match key across files is the combination of date, home_team, and away_team. That is the main relational boundary in the dataset. Any diagram should show results.csv as the parent dataset with the other two files joined onto it by these fields.

8. Temporal and geopolitical handling

The data model explicitly distinguishes between team identity and host-country identity. Team names are normalized to present-day successors; country names are historically accurate for the match date. The neutral flag captures whether the venue should be considered neutral despite naming changes or historical boundaries.

9. Data provenance

The dataset is manually compiled from multiple external sources, including Wikipedia, RSSSF, and national association sites. These sources are upstream inputs, but the repository itself contains only the curated output, not source ingestion code.

10. Repository role and consumption

Consumers are expected to read the CSVs directly from GitHub or after download. There is no service layer, API, or transformation pipeline in the repo. In architecture terms, this is a static data distribution repository.

11. Ancillary repository contents

.github/FUNDING.yml is operational metadata for GitHub sponsorship and does not affect the data model. LICENSE governs reuse. These files are peripheral to the dataset architecture.

12. How to diagram it

A good architecture diagram would show:

- upstream external historical sources

- a curation/normalization step

- four output artifacts: results.csv, shootouts.csv, goalscorers.csv, former_names.csv

- downstream analysts or tools consuming the CSVs directly

The main conceptual boundary is between curated canonical match data and supporting normalization/detail tables.