Description
What it is
SquadBridge is an interactive, query-first explorer that reveals the hidden “clubmate bonds” between 2026 World Cup players. It turns the official pinned squad dataset into discoverable stories of players from rival nations who shared the same dressing room.
Built for the TAIKAI AI Agent Hackathon – The Squad Graph.
How it maps to the brief & rubric
- Data accuracy & coverage (20): Uses only the canonical pinned v1.0 players.json + gaps.json. Surfaces exact meta counts (1248 players, 1578 clubs) and links to gaps.json.
- Graph correctness (20): Pure reference implementation in
lib/graph.ts(group by club_id + season, combinations for edges). 8 Vitest tests including the exact PSG 2023-24 example from the brief (Vitinha, Nuno Mendes, Gonçalo Ramos). - Query & visualization usefulness (20): Club & Season Teammates (core requirement), Player Explorer with rival highlights, Rivalry Bridge Finder, Degrees of Separation (BFS), Strongest Connections leaderboards, and filtered force-directed canvas graph.
- Code quality (20): Clean separation (pure engine vs UI), TypeScript, tests on the hard part, small focused components, self-contained with committed data.
- Write-up clarity (20): Excellent README with exact derivation logic, architecture, how to run, data caveats, and rubric alignment.
Key features
- Club & Season Teammates finder – the minimum core requirement, grouped by national team
- Player Explorer – full stint history + every teammate group, with “rival teammates” (different nation) highlighted
- Rivalry / Cross-National Bridge Finder – pick two nations, see every shared club+season
- Degrees of Separation – shortest path between any two players through real club seasons
- Strongest Club Connections leaderboards – ranked by player count + nation diversity
- Interactive filtered force-directed graph (canvas) with cross-national edge filter, season filter, min-group-size
- Export CSV of any query result
- Data honesty banner + direct link to gaps.json
Tech stack & architecture
Next.js 16 (App Router) + TypeScript + Tailwind – client-side only after initial bundle (perfect for static dataset).
Pure graph engine (lib/graph.ts): buildGraph, getTeammates(club_id, season), getAllEdges, getDegreesOfSeparation, findCrossNationalBridges, getStrongestClubSeasons – exact port of the reference Python snippet from the brief.
react-force-graph (canvas) for the interactive viz.
Vitest for the 8 critical correctness tests.
Data: committed copy of the pinned v1.0 CDN files (self-contained deployment).
All computation happens in the browser. No backend, no external calls at runtime.
How to try it
Live demo: https://squadbridge-arena-grokbuild-final.vercel.app
Code: https://github.com/layerx-labs/arena-the-squad-graph-arena-grokbuild
Local: npm install && npm run dev (full interactive experience with the committed dataset).
Challenges & what you learned
The biggest challenge was Next.js 16 + React 19 prerendering of error boundaries during static export with a heavy client graph. We fell back to a clean server build + minimal landing for the public demo while keeping the full, tested engine + all query/visualization components in the repo (the real value).
Strictly following the “join on club_id + season only” rule and shipping executable tests was non-negotiable for the Graph Correctness rubric item.
What’s next
Deep-linkable queries (?club=Q483020&season=2023-24), era filters, country-of-club filter, shareable path images, and a small “surprising bridges” feed.