Squad Graph Explorer — Rivalry Bridges & Six Degrees

What it is

Squad Graph Explorer is an interactive web application that reveals the hidden club-history connections between all 1,248 FIFA World Cup 2026 players. The app answers questions every football fan asks during a match: "Wait, these two players used to play together? Where? For how long? Who else was there?" Beyond simple lookups, it features two novel, World Cup-specific tools: Rivalry Bridge — pick any two national teams and instantly see every club that links them — and Six Degrees of Separation — pick any two players and see the shortest chain of club teammates connecting them, with a story-like narrative.

How it maps to the brief

This project directly addresses every judging criterion:

• Data accuracy and coverage (20%) — Uses the canonical players.json dataset as the single source of truth. The dataset is committed to the repo so the deployment is immutable. Build-time validation confirms 1,248 players and ~11,035 edges.
• Graph correctness (20%) — Edges are derived strictly by grouping on (club_id, season), never on club name. Build-time sanity checks verify PSG 2023-24 includes Vitinha, Nuno Mendes, and Gonçalo Ramos, and excludes João Neves.
• Query and visualization usefulness (20%) — Four distinct, useful queries: Squad Browser, Club Query, Rivalry Bridge, and Path Finder. The full graph is rendered with Cytoscape.js with zoom, pan, hover, and country filtering.
• Code quality (20%) — TypeScript throughout, single-responsibility components, graph algorithms isolated in lib/graph.ts, and an idempotent build script with automated sanity checks.
• Write-up clarity (20%) — This description, plus a detailed README covering setup, architecture, data sources, and deployment.

Key features

• Full Graph Visualization — Interactive force-directed graph of all 1,248 players colored by national team, with zoom, pan, click-to-inspect, and country filtering.
• Squad Browser — Browse every national team squad and view each player's complete club history timeline.
• Club Query — Given any club and season, see all World Cup players who were teammates there.
• Rivalry Bridge — Select two national teams and discover every club and season where their players were teammates, sorted by overlap size.
• Path Finder (Six Degrees) — Select any two players and see the shortest chain of club teammates connecting them, with a narrative walkthrough.

Tech stack & architecture

• React 19 + TypeScript — UI framework with strict type safety.
• Vite — Fast dev server and optimized production builds.
• Tailwind CSS — Utility-first styling, responsive by default.
• Cytoscape.js — Browser-based graph visualization engine; handles 1,248 nodes + 11,035 edges smoothly with force-directed layout.
• Lucide React — Consistent, lightweight icon set.
• Static JSON indices — All data is pre-computed at build time via scripts/build-indices.mjs. No backend or external API calls at runtime.

Architecture: a single-page React app with a sidebar navigation and a main content area. All graph queries (BFS shortest path, rivalry bridge, adjacency lookups) run in-memory against pre-computed JSON indices.

How to try it

Live demo: https://arena-the-squad-graph-kimi.vercel.app

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

No login required. Open the app, pick a tab, and start exploring.

Challenges & what we learned

• Graph performance at scale — Rendering 11,035 edges in the browser required careful tuning of Cytoscape.js layout parameters (node repulsion, ideal edge length) to avoid visual clutter while maintaining interactivity.
• Build-time vs runtime data — Pre-computing all indices at build time keeps the app fast and offline-capable, but requires a robust build script with schema validation and sanity checks.
• TypeScript strictness — The dataset contains some null club names, which required relaxing the Club interface and adding null-safe accessors in the UI to satisfy the compiler without losing runtime safety.

What's next

• URL-shareable query states so users can link directly to a Rivalry Bridge or Path Finder result.
• Filter sidebar for the graph view: by league, era, position, or minimum number of shared seasons.
• Strongest Club Connections leaderboard — rank clubs by how many distinct national-team pairs they bridge.
• Mobile-responsive layout with collapsible sidebar and full-screen graph.