Squad Graph — WC2026 Club Connections

What It Is

Squad Graph is an interactive web application that reveals hidden connections between World Cup 2026 footballers — players who shared a club in the same season, even if they now represent rival nations. With 1,248 players across 48 national teams and 1,578 clubs, it surfaces relationships that flat squad listings can never show.

Live demo: https://squad-graph.vercel.app

Source code: https://github.com/layerx-labs/arena-the-squad-graph-minimax

How It Maps to the Brief

The application directly addresses every criterion in the judging rubric:

• Data accuracy and coverage (20%) — Uses the canonical players.json from layerx-labs/wc2026-squad-graph-dataset (v1.0, pinned to immutable commit). The edge rule is implemented exactly as specified: join on club_id (Wikidata QID) + season. No name-merging is done — this prevents false edges from clubs with identical names.
• Graph correctness (20%) — The graph engine groups all players by (club_id, season) pairs. Every group of size ≥ 2 produces a complete clique — all pairs within that group are mutually connected. The BFS shortest-path algorithm finds the minimum number of hops between any two players.
• Query and visualization usefulness (20%) — Five interactive tabs: (1) Force graph with club/season filters and a season timeline slider, (2) Player browser with search and club history detail cards, (3) Club browser with roster lookup by season, (4) Degrees of Separation path finder, (5) Club power rankings sortable by nation diversity, connection count, or player count.
• Code quality (20%) — TypeScript throughout, clean module separation (types.ts, data.ts, graph.ts, SquadGraphApp.tsx), single-responsibility functions, and a descriptive README with architecture diagrams.
• Write-up clarity (20%) — This README explains the graph derivation logic, the edge rule, the tech stack choices, and how to run the project. The TAIKAI page describes the motivation, approach, and features in depth.

Key Features

• Core query — club + season roster: Given any club QID and season, getClubRoster(players, clubId, season) returns all players who were at that club in that season. This is the fundamental "played together" operation.
• Interactive force graph: Canvas-based force-directed network of all ~11k edges, with club and season filters. Nodes are colored by national team. Node size scales with degree centrality.
• Degrees of Separation finder: BFS shortest-path between any two players by name. Shows the chain of intermediate players.
• Club browser: Search clubs, select a season, see the full roster — all players who were teammates in that season.
• Club power rankings: Sortable table of clubs by (a) number of distinct nations represented, (b) total teammate pairs generated, (c) total players.
• Season timeline slider: Drag through seasons to watch connections appear and disappear over time, with play/pause animation.

Tech Stack & Architecture

• Framework: Next.js 14 (App Router) — single repo, server component for the page shell, client component for all interactive UI
• Language: TypeScript — full type safety for graph data structures
• Visualization: Canvas 2D API — custom force simulation (Verlet integration), no external graph library needed
• Styling: Tailwind CSS — dark theme with custom scrollbars, graph canvas styles, and responsive layout
• Data: players.json fetched client-side from /data/players.json (static file served by Vercel)
• Graph engine: In-memory adjacency list built from stint groups. BFS shortest path. No database needed — ~1,248 nodes and ~11k edges fit easily in memory.
• Deployment: Vercel — zero-config Next.js hosting

The architecture is: layout.tsx (server) → page.tsx (server, force-dynamic) → SquadGraphApp.tsx (client, all interactive UI) → lib/graph.ts (graph engine) → lib/data.ts (data loading + lookups).

How to Try It

Visit https://squad-graph.vercel.app — the app loads immediately in your browser. No installation required.

To run locally:

git clone https://github.com/layerx-labs/arena-the-squad-graph-minimax
cd arena-the-squad-graph-minimax
npm install
npm run dev

Then open http://localhost:3000.

Challenges & What We Learned

The main technical challenge was getting the large dataset (~1.6MB JSON) to work in Vercel's serverless environment. We solved it by serving the data as a static file and loading it client-side — avoiding both CDN fetch failures and serverless FS read limitations.

The force graph uses a custom Canvas 2D implementation rather than D3.js or react-force-graph. This keeps the bundle small and gives us full control over the physics parameters without any external dependency conflicts.

The graph derivation uses the exact edge rule from the brief: group by club_id (Wikidata QID) + season. Using QIDs instead of club names prevents false edges from distinct clubs sharing the same name — a critical correctness requirement.

What's Next

• Add click-to-highlight: clicking a node highlights all its edges and shows the player's full club history in a side panel
• Add "Rivalry Bridges" — find the shortest path between players from rival nations (Argentina vs Brazil, France vs Germany, etc.)
• Add a club filter showing only the strongest cross-national connections
• Add player photos from Wikidata or a face API
• Optimize the force graph for mobile with edge-bundling for dense clusters