# martj42/international_results architecture

> Architecture diagram of the GitHub repository martj42/international_results, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martj42/international_results
- Repository: https://github.com/martj42/international_results

## Overview

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**.

Main entry points: [`results.csv`](https://github.com/martj42/international_results/blob/master/results.csv) (Results), [`shootouts.csv`](https://github.com/martj42/international_results/blob/master/shootouts.csv) (Shootouts), [`goalscorers.csv`](https://github.com/martj42/international_results/blob/master/goalscorers.csv) (Goalscorers), [`README.md`](https://github.com/martj42/international_results/blob/master/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External inputs"]
  node_sources["Historical sources<br/>upstream sources"]
  node_curation{{"Curation<br/>normalization step"}}
  node_analysts(("Analysts<br/>downstream consumers"))
  node_tools(("Data tools<br/>downstream consumers"))
end

subgraph group_core["Core data"]
  node_results[("Results<br/>match fact table<br/>[results.csv]")]
  node_shootouts[("Shootouts<br/>match extension<br/>[shootouts.csv]")]
  node_goalscorers[("Goalscorers<br/>event detail<br/>[goalscorers.csv]")]
  node_former_names[("Former names<br/>name mapping<br/>[former_names.csv]")]
  node_match_key{{"Match key<br/>join key"}}
  node_team_identity["Team identity<br/>normalization boundary"]
  node_place_identity["Place identity<br/>historical boundary"]
  node_neutral_flag(("Neutral flag<br/>venue attribute"))
end

subgraph group_meta["Repo metadata"]
  node_readme["README<br/>dataset docs<br/>[README.md]"]
  node_license["License<br/>reuse terms"]
  node_funding["Funding<br/>repo metadata<br/>[FUNDING.yml]"]
end

node_sources -->|"feed"| node_curation
node_curation -->|"produces"| node_results
node_curation -->|"produces"| node_shootouts
node_curation -->|"produces"| node_goalscorers
node_curation -->|"normalizes"| node_former_names
node_results -->|"keys"| node_match_key
node_shootouts -->|"joins on"| node_match_key
node_goalscorers -->|"joins on"| node_match_key
node_former_names -->|"maps"| node_team_identity
node_results -->|"uses"| node_team_identity
node_results -->|"records"| node_place_identity
node_results -->|"contains"| node_neutral_flag
node_shootouts -->|"extends"| node_results
node_goalscorers -->|"extends"| node_results
node_readme -->|"documents"| node_results
node_readme -->|"documents"| node_shootouts
node_readme -->|"documents"| node_goalscorers
node_readme -->|"documents"| node_former_names
node_license -->|"permits use"| node_analysts
node_results -->|"consumed by"| node_analysts
node_results -->|"consumed by"| node_tools
node_shootouts -->|"consumed by"| node_tools
node_goalscorers -->|"consumed by"| node_tools
node_former_names -->|"consumed by"| node_tools
node_funding -.->|"metadata only"| node_analysts

click node_results "https://github.com/martj42/international_results/blob/master/results.csv"
click node_shootouts "https://github.com/martj42/international_results/blob/master/shootouts.csv"
click node_goalscorers "https://github.com/martj42/international_results/blob/master/goalscorers.csv"
click node_former_names "https://github.com/martj42/international_results/blob/master/former_names.csv"
click node_readme "https://github.com/martj42/international_results/blob/master/README.md"
click node_license "https://github.com/martj42/international_results/tree/master/LICENSE"
click node_funding "https://github.com/martj42/international_results/blob/master/.github/FUNDING.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sources,node_curation,node_analysts,node_tools toneBlue
class node_results,node_shootouts,node_goalscorers,node_former_names,node_match_key,node_team_identity,node_place_identity,node_neutral_flag toneAmber
class node_readme,node_license,node_funding toneMint
```

## Components

### External inputs

Upstream historical sources and downstream consumers around the curated dataset.

- **Historical sources**: upstream sources · Manual input sources such as Wikipedia, RSSSF, and national association records.
- **Curation**: normalization step · Manual compilation and reconciliation of historical match records into a consistent archive.
- **Analysts**: downstream consumers · People and tools reading the CSVs directly for analysis or download.
- **Data tools**: downstream consumers · Scripts and notebooks that consume the CSV files directly.

### Core data

Canonical match archive and its match-linked extensions.

- [Results](https://github.com/martj42/international_results/blob/master/results.csv): match fact table · Primary match record: date, teams, scoreline, tournament, venue, country, and neutral flag. · `results.csv`
- [Shootouts](https://github.com/martj42/international_results/blob/master/shootouts.csv): match extension · Penalty shootout outcomes keyed to the match identity fields in results.csv. · `shootouts.csv`
- [Goalscorers](https://github.com/martj42/international_results/blob/master/goalscorers.csv): event detail · Goal-level events linked to matches: scorer, team, own goals, and penalties. · `goalscorers.csv`
- [Former names](https://github.com/martj42/international_results/blob/master/former_names.csv): name mapping · Normalization map for historical team names and successor identities. · `former_names.csv`
- **Match key**: join key · Shared identity across files: date + home_team + away_team.
- **Team identity**: normalization boundary · Current successor team names used for home and away teams across the archive.
- **Place identity**: historical boundary · Country names remain historically accurate for the match date, separate from team normalization.
- **Neutral flag**: venue attribute · Marks whether the venue should be considered neutral despite historical naming or boundary changes.

### Repo metadata

Documentation and repository-level support files.

- [README](https://github.com/martj42/international_results/blob/master/README.md): dataset docs · Explains scope, conventions, and intended use of the data package. · `README.md`
- [License](https://github.com/martj42/international_results/tree/master/LICENSE): reuse terms · Defines reuse and distribution rights for the dataset. · `LICENSE`
- [Funding](https://github.com/martj42/international_results/blob/master/.github/FUNDING.yml): repo metadata · GitHub sponsorship metadata; operational only. · `.github/FUNDING.yml`

## Connections

- Historical sources → Curation: feed · External historical records are manually compiled into the curated archive.
- Curation → Results: produces · Curation yields the canonical match fact table.
- Curation → Shootouts: produces · Curation extracts shootout outcomes where relevant.
- Curation → Goalscorers: produces · Curation extracts goal-level event data.
- Curation → Former names: normalizes · Curation maintains the team-name mapping used across the archive.
- Results → Match key: keys · Core match identity is the join boundary for extensions.
- Shootouts → Match key: joins on · Shootout rows attach via the shared match key.
- Goalscorers → Match key: joins on · Scorer rows attach via the shared match key.
- Former names → Team identity: maps · Historic names are reconciled to current successor team identities.
- Results → Team identity: uses · Home and away teams use normalized current identities.
- Results → Place identity: records · Country values preserve the historical place name at match time.
- Results → Neutral flag: contains · Neutral venue status is stored on the base match record.
- Shootouts → Results: extends · Shootout detail enriches the base match outcome record.
- Goalscorers → Results: extends · Scoring events are a one-to-many child of match results.
- README → Results: documents · README explains the primary dataset and its conventions.
- README → Shootouts: documents · README describes shootout linkage and meaning.
- README → Goalscorers: documents · README describes goal-event structure and joins.
- README → Former names: documents · README explains historical name normalization.
- License → Analysts: permits use · License governs downstream reuse of the dataset.
- Results → Analysts: consumed by · Analysts read the CSVs directly from the repository or after download.
- Results → Data tools: consumed by · Tools and notebooks ingest the CSVs directly.
- Shootouts → Data tools: consumed by · Downstream tools optionally use shootout detail.
- Goalscorers → Data tools: consumed by · Downstream tools optionally use scorer detail.
- Former names → Data tools: consumed by · Downstream tools use mappings to avoid historical name drift.
- Funding → Analysts: metadata only · Operational GitHub sponsorship metadata; not part of the data model.