
ScoutIQ
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.
Project overview
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.Features implemented
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)Shell & UX
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
Tech stack
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 yetScreenshots
Dashboard Match explorer
Player similarity AI scouting report
Data Explorer
Note: Add PNG captures topublic/screenshots/and update filenames above, or remove image tags until assets exist.
Local setup
Prerequisites
Node.js 20+ (LTS recommended)
npm (or pnpm / yarn)
Install and run
Open http://localhost:3000.
Other scripts
Environment variables
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:Project structure (high level)
StatsBomb attribution
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.Roadmap
Shipped (initial)
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)
Upcoming
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
/predictionsVector 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)
License
Private project (
"private": true in package.json). Add a license file if you plan to open-source ScoutIQ.Contributing
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).
0 likes · 1 view · Aug 17, 2026
Built ScoutIQ, an AI-driven football analytics platform with match analysis and scouting tools.