# khuenlm/the-12th-man architecture

> Architecture diagram of the GitHub repository khuenlm/the-12th-man, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khuenlm/the-12th-man
- Repository: https://github.com/khuenlm/the-12th-man

## Overview

The Twelfth Man is a World Cup referee-bias visualization project. Its user-facing result is an interactive D3 experience presenting four views: confederation-pairing card averages, same- versus cross-confederation card distributions and a statistical test, bias trends over time, and match-level high-stakes comparisons. Python export scripts prepare visualization data from processed match and booking data; a separate analysis script tests the distribution difference. The excerpts support exporter input/output relationships, but do not show the page wiring or D3 data-loading calls, so those connections are omitted.

Main entry points: [`data/viz`](https://github.com/khuenlm/the-12th-man/tree/main/data/viz) (Visualization JSON), [`data/processed`](https://github.com/khuenlm/the-12th-man/tree/main/data/processed) (Processed match data), [`src/export_beeswarm.py`](https://github.com/khuenlm/the-12th-man/blob/main/src/export_beeswarm.py) (Distribution export), [`src/export_heatmap.py`](https://github.com/khuenlm/the-12th-man/blob/main/src/export_heatmap.py) (Heatmap export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset"]
  node_worldcup_data[("World Cup data")]
  node_processed_data[("Processed match data")]
  node_viz_data[("Visualization JSON")]
end

subgraph group_preparation["Data Preparation"]
  node_export_beeswarm["Distribution export<br/>[export_beeswarm.py]"]
  node_export_heatmap["Heatmap export<br/>[export_heatmap.py]"]
  node_export_timeline["Timeline export<br/>[export_timeline.py]"]
  node_export_strip["Match comparison export<br/>[export_strip.py]"]
  node_export_notorious["High-stakes export"]
end

subgraph group_analysis["Statistical Analysis"]
  node_mannwhitney["Distribution test<br/>[mannwhitneyu.py]"]
end

subgraph group_experience["Visualization Experience"]
  node_d3_visualizations["D3 visualization suite<br/>[d3_viz.js]"]
  node_navigation["Tab navigation<br/>[nav_function.js]"]
  node_tooltips["Link tooltips<br/>[tip_function.js]"]
end

node_export_beeswarm -->|"reads bookings"| node_processed_data
node_export_beeswarm -->|"reads teams"| node_worldcup_data
node_export_beeswarm -->|"writes distribution"| node_viz_data
node_export_heatmap -->|"reads bookings"| node_processed_data
node_export_heatmap -->|"writes heatmap"| node_viz_data
node_export_timeline -->|"reads bookings"| node_processed_data
node_export_timeline -->|"writes timeline"| node_viz_data
node_export_strip -->|"reads match data"| node_processed_data
node_export_strip -->|"writes comparisons"| node_viz_data
node_export_notorious -->|"reads match data"| node_processed_data
node_export_notorious -->|"writes spotlight"| node_viz_data
node_mannwhitney -->|"reads distribution"| node_viz_data

click node_worldcup_data "https://github.com/khuenlm/the-12th-man/tree/main/data/raw"
click node_processed_data "https://github.com/khuenlm/the-12th-man/tree/main/data/processed"
click node_viz_data "https://github.com/khuenlm/the-12th-man/tree/main/data/viz"
click node_export_beeswarm "https://github.com/khuenlm/the-12th-man/blob/main/src/export_beeswarm.py"
click node_export_heatmap "https://github.com/khuenlm/the-12th-man/blob/main/src/export_heatmap.py"
click node_export_timeline "https://github.com/khuenlm/the-12th-man/blob/main/src/export_timeline.py"
click node_export_strip "https://github.com/khuenlm/the-12th-man/blob/main/src/export_strip.py"
click node_export_notorious "https://github.com/khuenlm/the-12th-man/blob/main/src/export_notorious.py"
click node_mannwhitney "https://github.com/khuenlm/the-12th-man/blob/main/src/mannwhitneyu.py"
click node_d3_visualizations "https://github.com/khuenlm/the-12th-man/blob/main/d3_viz.js"
click node_navigation "https://github.com/khuenlm/the-12th-man/blob/main/nav_function.js"
click node_tooltips "https://github.com/khuenlm/the-12th-man/blob/main/tip_function.js"

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_worldcup_data,node_processed_data,node_viz_data toneBlue
class node_export_beeswarm,node_export_heatmap,node_export_timeline,node_export_strip,node_export_notorious toneAmber
class node_mannwhitney toneMint
class node_d3_visualizations,node_navigation,node_tooltips toneRose
```

## Components

### Dataset

- [World Cup data](https://github.com/khuenlm/the-12th-man/tree/main/data/raw): `data/raw`
- [Processed match data](https://github.com/khuenlm/the-12th-man/tree/main/data/processed): `data/processed`
- [Visualization JSON](https://github.com/khuenlm/the-12th-man/tree/main/data/viz): `data/viz`

### Data Preparation

- [Distribution export](https://github.com/khuenlm/the-12th-man/blob/main/src/export_beeswarm.py): `src/export_beeswarm.py`
- [Heatmap export](https://github.com/khuenlm/the-12th-man/blob/main/src/export_heatmap.py): `src/export_heatmap.py`
- [Timeline export](https://github.com/khuenlm/the-12th-man/blob/main/src/export_timeline.py): `src/export_timeline.py`
- [Match comparison export](https://github.com/khuenlm/the-12th-man/blob/main/src/export_strip.py): `src/export_strip.py`
- [High-stakes export](https://github.com/khuenlm/the-12th-man/blob/main/src/export_notorious.py): `src/export_notorious.py`

### Statistical Analysis

- [Distribution test](https://github.com/khuenlm/the-12th-man/blob/main/src/mannwhitneyu.py): `src/mannwhitneyu.py`

### Visualization Experience

- [D3 visualization suite](https://github.com/khuenlm/the-12th-man/blob/main/d3_viz.js): `d3_viz.js`
- [Tab navigation](https://github.com/khuenlm/the-12th-man/blob/main/nav_function.js): `nav_function.js`
- [Link tooltips](https://github.com/khuenlm/the-12th-man/blob/main/tip_function.js): `tip_function.js`

## Connections

- Distribution export → Processed match data: reads bookings (evidence: `src/export_beeswarm.py`)
- Distribution export → World Cup data: reads teams (evidence: `src/export_beeswarm.py`)
- Distribution export → Visualization JSON: writes distribution (evidence: `src/export_beeswarm.py`)
- Heatmap export → Processed match data: reads bookings (evidence: `src/export_heatmap.py`)
- Heatmap export → Visualization JSON: writes heatmap (evidence: `src/export_heatmap.py`)
- Timeline export → Processed match data: reads bookings (evidence: `src/export_timeline.py`)
- Timeline export → Visualization JSON: writes timeline (evidence: `src/export_timeline.py`)
- Match comparison export → Processed match data: reads match data (evidence: `src/export_strip.py`)
- Match comparison export → Visualization JSON: writes comparisons (evidence: `src/export_strip.py`)
- High-stakes export → Processed match data: reads match data (evidence: `src/export_notorious.py`)
- High-stakes export → Visualization JSON: writes spotlight (evidence: `src/export_notorious.py`)
- Distribution test → Visualization JSON: reads distribution (evidence: `src/mannwhitneyu.py`)