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, ● Live MongoDB badge, and follow-up.

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)

Curated World Cup 2026 intelligence — not a live FIFA broadcast 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: docs/ARCHITECTURE.md in the repository.