MatchMind — Technical Architecture

Overview

MatchMind combines:

1. Gemini (gemini-2.5-flash-lite) for classification and analysis
2. MongoDB Atlas as the football intelligence database
3. MCP tool interface (lib/mcp.ts) for agent data retrieval
4. Google ADK (@google/adk) when USE_ADK_AGENT=true
5. Next.js 16+ App Router for UI and API routes

Fan Agent Flow

1 — Classification

Questions map to stats, prediction, fantasy, tactical, or historical.

2 — MongoDB Query

The query_football_data tool runs read-only aggregation pipelines against matches, players, teams, headToHead, groups, and tournament collections.

3 — Analysis

ADK LlmAgent or the local Gemini pipeline reasons over records and returns structured JSON.

4 — Rendering

Analyst card with headline, analysis, key stats, confidence, data badge (◇ Preview mockup before kickoff · ● Live MongoDB after sync · ○ Demo data without MongoDB), and follow-up.

Tournament Data Phases

Official (FIFA): groups, 72 fixtures, venues, and kickoff times from the Dec 5 2025 draw and published schedule (lib/worldcup2026-official-fixtures.ts).

Before 11 June 2026, MatchMind also serves preview mockup scores, standings, and player stats — illustrative demo data with an amber banner on /agent. See docs/DATA-SOURCES.md for the full real vs mockup matrix. After kickoff, npm run sync or the admin agent updates MongoDB; badges switch to live mode automatically (lib/tournament-phase.ts).

Admin Agent

/agent/admin — protected by ADMIN_SECRET. Tools: update_match_result, update_player_stats, query_football_data.

Data Updates

• npm run seed — full dataset reload
• Admin agent — natural-language writes
• npm run sync — local private pipeline (gitignored)

Official fixture structure always; mockup scores before kickoff; live synced results after. Independent of any official broadcast data feed.

Security

• Secrets in .env only — server-side API routes
• MongoDB Atlas IP whitelist + auth
• Admin writes require X-Admin-Key
• Read-only pipeline safety in lib/query-safety.ts

UI / Backgrounds

Stadium Night × Gold Intelligence. Section images in public/images/:

• .bg-hero — landing hero
• .bg-middle — How It Works + agent pages
• .cta-section — agent CTA tunnel imagery
• .bg-footer — footer

Gradient scrims in styles/globals.css keep art visible with readable text.

Implementation Map

• lib/agent-builder.ts — fan orchestration
• lib/admin-agent-builder.ts — admin orchestration
• lib/mcp.ts — MCP tool contract
• lib/mongo-writes.ts — match/player updates
• lib/validation.ts — response normalization

Builder Notes

The database is the intelligence; the agent is the reasoning layer on top.

That's what makes MatchMind a real agent, not a chatbot wrapper.

Full markdown on GitHub: docs/ARCHITECTURE.md