PitchIQ

An AI-native football intelligence platform that uses Gemini to generate structured, coach-style tactical match analysis with grounded data and cloud-native deployment.

Comment

PitchIQ — Football Intelligence, Reimagined

Inspiration

I've always enjoyed football, but understanding the tactical side of the game is harder than it looks. Professional analysts spend hours studying formations, playing styles, and matchups before a single match. Most fans never see that process — only the conclusions.

For Hack Days CUET 2026, I wanted to build something that could surface that kind of analysis on demand. Not a chatbot, not a Q&A tool — a structured tactical report generator that actually feels useful. That idea became PitchIQ.

I also wanted to challenge myself by building a complete full-stack AI application from scratch: real backend architecture, real deployment, real engineering decisions.

What It Does

PitchIQ is an AI-powered football intelligence platform. A user selects two teams, and PitchIQ generates a structured pre-match tactical report — powered by Gemini 2.5 Flash on the backend and rendered in organized sections on the frontend.

The report covers:

  • Match overview and context
  • Team formations and playing styles
  • Tactical identities and pressing structures
  • Strengths, weaknesses, and key personnel
  • Key tactical battles to watch
  • Expected game flow
  • Coach recommendations
  • Comparative tactical scores

The output is not a block of freeform AI text. Every field is validated against a typed schema before it reaches the frontend.

How I Built It

Frontend: React, TypeScript, Vite, Tailwind CSS, TanStack Query

Backend: FastAPI (Python), organized into services, prompt builders, Pydantic schemas, and API routes for modularity and maintainability.

AI Layer — Google Gemini 2.5 Flash:

This is the core of the project. When a user selects two teams, the backend runs a structured pipeline:

  1. A knowledge enrichment layer adds football-specific context about both teams before any prompt is built.
  2. A prompt builder constructs a detailed, domain-specific prompt that instructs Gemini to return a strict JSON structure.
  3. Gemini 2.5 Flash generates the response.
  4. Pydantic validates the response against a typed MatchReport schema. If any field is missing or malformed, the backend automatically requests a regenerated response from Gemini.
  5. Only a fully validated report reaches the frontend.

This retry-and-validate architecture is what makes PitchIQ reliable as a web application rather than a demo. Language models are flexible by design; web applications need predictable data structures. The pipeline bridges that gap.

Deployment — Google Cloud:

  • Google Cloud Run hosts the containerized FastAPI backend. Cloud Run was chosen for its stateless, auto-scaling model — no server management, and the backend scales to zero when idle, keeping costs reasonable for a solo project.
  • Firebase Hosting serves the React frontend with fast global CDN delivery and simple CI-friendly deployment.
  • Google Secret Manager stores the Gemini API key securely, keeping credentials out of environment files and source code.
  • Docker containerizes the backend, ensuring the local development environment and the Cloud Run deployment are identical.

Challenges I Ran Into

The hardest problem wasn't AI — it was making AI output reliable enough for a structured web application.

Gemini is capable and flexible, but flexibility is the enemy of predictable JSON. Early versions of the pipeline occasionally returned responses with missing fields, slightly restructured objects, or inconsistent formatting — any of which would break the frontend renderer.

The solution was layered: a strict prompt that specifies the exact output schema, Pydantic validation that catches any deviation, and an automatic retry that asks Gemini to regenerate whenever validation fails. Getting this retry loop to work correctly — without introducing infinite loops or returning stale data — took more engineering than I expected.

Deployment was the other major challenge. Wiring Cloud Run, Firebase Hosting, Docker, and Secret Manager together for the first time involves a lot of moving parts. Environment variable injection at build time versus runtime, container port configuration, CORS between the hosted frontend and the Cloud Run backend — each required debugging from scratch.

Working solo, I also had to manage scope carefully. Frontend, backend, AI integration, deployment, and documentation all had to fit within the hackathon window.

What I Learned

The most important thing PitchIQ taught me is the difference between making AI work and making AI reliable.

Getting Gemini to generate a reasonable tactical breakdown is straightforward. Getting it to generate a consistently structured, validated, schema-compliant breakdown — one that can be safely consumed by a typed frontend — required thinking about failure modes, not just happy paths. That shift in mindset, from "does this output look good?" to "does this output satisfy the contract?", is something I'll carry into every AI project I build next.

On the infrastructure side, deploying a containerized backend to Cloud Run and understanding how secrets, networking, and hosting connect in a real Google Cloud project was far more valuable than any tutorial.

What's Next for PitchIQ

Three things I want to build next:

  1. Live data integration — connecting to a real football data API so reports are grounded in current squad form and statistics, not just model knowledge.
  2. Tactical visualizations — formation diagrams and heatmap overlays rendered on the frontend alongside the text analysis.
  3. Historical comparisons — allowing users to compare how a matchup looked at different points in a season.

PitchIQ started as a hackathon project, but I plan to continue developing it into a more complete football intelligence platform.

Built With

Share this project:

Updates