Football intelligence platform — a dark-themed analytics dashboard for match analysis, AI-powered scouting, player comparison, and open-data exploration. Built for scouts, analysts, and recruitment teams who want tactical insight and structured reports in one place.

ScoutIQ is a Next.js application that combines a modern football analytics UI with AI-assisted workflows. It surfaces live-style match cards, prediction views, player similarity rankings, and scouting reports, backed by Google Gemini where configured. A StatsBomb Open Data ingestion layer powers the Data Explorer, letting you browse real competitions, fixtures, and event-derived match analytics from the public dataset.

The app uses mock data in several areas today (dashboard KPIs, predictions list, saved reports) so the product shell is fully navigable without external services. AI routes gracefully fall back to deterministic mocks when GEMINI_API_KEY is not set.

Area Route Description Dashboard / Command center with KPI cards, upcoming matches, standings, top predictions, and latest reports Match explorer /matches Filterable match grid (live / upcoming / finished) with possession and xG bars AI tactical analysis /matches + POST /api/analyze-match Per-match “Generate AI Analysis” — summary, tactical patterns, key performers, turning points, scouting insights (Gemini or mock) Predictions /predictions AI-style match prediction cards with outcome probabilities and confidence Player similarity engine /players Euclidean distance over six attributes; top-5 similar players, radar chart, attribute comparison AI scouting reports /reports + POST /api/scouting-report Structured recruitment reports with PDF export (Gemini or mock) Data Explorer /data StatsBomb competitions → seasons → matches; event analytics (shots, passes, pressures, fouls, xG, timeline) Leaderboard /leaderboard Power rankings and top scorers (mock data)

Collapsible sidebar + top navbar (search, notifications, avatar)

Responsive layout, dark ScoutIQ theme (pitch-green accent)

shadcn/ui-style components (Card, Table, Select, Badge, Button, Skeleton)

TypeScript throughout; shared validation/coercion for AI API responses

Layer Technology Framework Next.js 16 (App Router, React Server Components) Language TypeScript Styling Tailwind CSS v4, CSS variables, dark theme UI shadcn/ui (radix-nova), Radix UI, Lucide icons Charts Recharts (player radar, analytics) AI Google Gemini API (generateContent, JSON schema mode) PDF jsPDF (scouting report export) Data StatsBomb Open Data (GitHub raw JSON), in-app mock datasets Planned persistence Supabase client installed; not wired yet

Dashboard Match explorer

Player similarity AI scouting report

Data Explorer

Node.js 20+ (LTS recommended)

npm (or pnpm / yarn)

Open http://localhost:3000.

Copy .env.example to .env.local (gitignored). Restart the dev server after changes.

Variable Required Description GEMINI_API_KEY No Google AI Studio API key for /api/analyze-match and /api/scouting-report. If missing or invalid, routes use mock generators. GEMINI_MODEL No Override Gemini model (default: gemini-2.0-flash).

Get a Gemini key: https://aistudio.google.com/app/apikey

Example .env.local:

Pages that display StatsBomb data (e.g. Data Explorer) must credit StatsBomb visibly. The constant STATSBOMB_ATTRIBUTION in src/lib/statsbomb/types.ts is rendered in the UI. See the StatsBomb Open Data user agreement.

Dashboard shell and navigation

Match explorer with mock fixtures

AI tactical analysis (Gemini + mock fallback)

Player similarity engine (Euclidean + radar)

AI scouting reports + PDF export

StatsBomb open-data ingestion & Data Explorer (competitions, matches, event analytics)

Expanded StatsBomb integration — Supabase caching, batch sync, lineups in UI, deeper event views

FastAPI prediction service — Dedicated ML backend for match outcome / xG models, consumed by /predictions

Vector search — Semantic player and report search across embeddings

Embeddings pipeline — Player profiles, reports, and match summaries for RAG-style scouting Q&A

Tournament leaderboards — Live standings and stat leaders wired to real competition data (replacing mock leaderboard)

Private project ("private": true in package.json). Add a license file if you plan to open-source ScoutIQ.

This repository is in active development. For internal or team use, open issues or PRs against your main branch with a short test plan (build + lint + manual check of affected routes).