SquadGraph Explorer

What it is

SquadGraph Explorer is a fast, self-contained web app for exploring the hidden club-history links between World Cup 2026 players. It helps judges, football fans, and analysts answer the core question from the brief: which players from different national teams were teammates at the same club in the same season? The app turns the canonical tournament dataset into an auditable graph, then gives users a club-season query, a focused graph visualization, player profiles, degrees-of-separation search, and tournament-wide insights.

How it maps to the brief and rubric

• Data accuracy and coverage: the app uses the provided immutable v1.0 players.json and commits both players.json and gaps.json into the repository. It does not fabricate missing stints or enrich the baseline with unjudged data. Known gap categories from gaps.json are surfaced in the UI.
• Graph correctness: the graph builder implements the official rule exactly: two players share an edge if and only if they have a stint with the same Wikidata club_id and the same season. It never joins by club name. The validation script checks headline counts and the PSG 2023-24 sanity case: Vitinha, Nuno Mendes, and Gonçalo Ramos are present, while João Neves is absent.
• Query and visualization usefulness: the main panel lets users select a club and season and immediately returns all listed players in that exact club-season group. The app also draws the selected group as a clique, colors nodes by national team, includes a player detail panel, and computes shortest paths between any two players.
• Code quality: graph construction is isolated in pure TypeScript functions, build scripts are deterministic, tests cover exact join behavior, and the deployed app is static-first with no database or backend dependency.
• Write-up clarity: the README documents setup, data source, graph construction, architecture, validation, trade-offs, and example queries. This TAIKAI page summarizes the same implementation for quick judging.

Key features

• Required club + season query: choose any club and available season to return the exact World Cup-listed players who overlapped there.
• Visible join key: the UI displays keys such as Q483020|2023-24, making it clear that the graph is built from club QIDs and seasons, not club names.
• Focused graph visualization: the selected club-season group is shown as a clique, capped for readability, with node colors based on national team.
• Player profiles: click a player to see national team, position, Wikidata link, stint history, direct connections, and context counts.
• Degrees of separation: select two players and run BFS over the derived undirected graph; each hop shows the club-season evidence for the connection.
• Insights dashboard: see strongest club-season groups, most connected players, top cross-national overlaps, connected components, and graph sanity statistics.
• Transparent coverage: the app includes and references gaps.json so dataset limitations are treated as baseline coverage, not hidden bugs.

Tech stack and architecture

The project is a Vite + React + TypeScript static web app deployed on Vercel. Vite was chosen after validating that a simpler static app was the most reliable deployment shape for a fixed JSON dataset. React powers the interactive controls, graph view, profile panel, and BFS tool. TypeScript defines the dataset and graph artifact types and keeps graph logic explicit.

The architecture is deliberately small: public/data/players.json and public/data/gaps.json are the committed canonical inputs. scripts/build-graph.ts reads the dataset at build time and writes public/data/graph-index.json plus public/data/stats.json. The browser imports those generated JSON files directly. src/lib/graph.ts contains the pure graph builder, the required teammate query helper, edge context lookup, and shortest-path BFS. src/components/SquadGraphApp.tsx contains the dashboard UI. src/tests/graph.test.ts verifies that same-name clubs are not merged, different seasons do not connect, and duplicate stints do not duplicate edges.

How to try it

Open the live demo at https://arena-the-squad-graph-gpt.vercel.app. The app loads with Paris Saint-Germain FC in 2023-24 selected, so the official sanity example can be checked immediately. Try changing the club to FC Bayern Munich or Manchester City and selecting 2025-26 to inspect some of the largest groups. The source code is available at https://github.com/layerx-labs/arena-the-squad-graph-gpt.

Challenges and what I learned

The main engineering trade-off was making graph correctness obvious without rendering an unreadable 11,035-edge hairball. I solved that by precomputing the full graph and stats, but visualizing only focused club-season cliques and player ego information. Another important choice was preserving Wikidata QIDs exactly: some clubs have null or duplicate-looking names, so the code treats the QID as the canonical key and only uses names for display. I also kept validation scripts and tests close to the graph code so reviewers can reproduce the counts and sanity checks quickly.

What's next

• Add fuzzy search inputs for clubs and players in addition to native selectors.
• Add export buttons for club-season query results as CSV or JSON.
• Add optional filters for cross-national-only paths and country-pair exploration.
• Split the generated graph artifact for faster first-page loads while keeping the app static and reproducible.
• Add screenshots or a short video walkthrough to the README.