MatchtwinAI

An explainable World Cup tactical simulator powered by GPT-5.6, Poisson modeling, and Monte Carlo simulations.

Comment

Inspiration

Football predictions often show only a final percentage or score prediction without explaining what caused the result. I wanted to build a tool that answers a more useful question:

How would the match outlook change if one team used a different tactical approach?

MatchTwin AI was inspired by football analysis, tactical scenario planning, and the need for more transparent AI-assisted tools. Instead of asking generative AI to invent a prediction, the project uses a deterministic statistical model as the source of truth and uses AI only to help explain the calculated differences.

For this hackathon MVP, I used an illustrative France vs. Morocco match and compared a normal baseline with a scenario where Morocco plays a deeper low block.

What it does

MatchTwin AI compares two versions of the same football match:

  1. A baseline prediction
  2. A tactical scenario prediction

The application displays changes in:

  • Expected goals
  • Home win, draw, and away win probabilities
  • Over and under 2.5 goals
  • Both teams to score
  • Clean-sheet probabilities
  • Most likely scorelines

The tactical scenario applies controlled backend multipliers to the expected-goal inputs and recalculates the complete probability distribution.

The probability of a team scoring exactly (k) goals is calculated with the Poisson distribution:

$$ P(X=k)=\frac{e^{-\lambda}\lambda^k}{k!} $$

Here, (\lambda) represents the team’s expected goals. MatchTwin calculates possible score combinations and derives the match-level probabilities from them.

The statistical engine always remains the source of truth. Generative AI is not allowed to create, replace, or modify the probabilities.

How I built it

The frontend was built with React, TypeScript, and Vite. It presents the baseline and tactical scenario side by side so users can immediately see how the probabilities change.

The backend was built with Python and FastAPI. It contains:

  • A deterministic Poisson prediction engine
  • Strict Pydantic request and response contracts
  • Prepared and validated demonstration data
  • A fixed tactical-scenario transformation
  • A structured OpenAI explanation adapter
  • Separate rate limits for health, prediction, and explanation endpoints
  • Sanitized error handling
  • Automated backend tests

The OpenAI integration is backend-only. The explanation adapter receives only the already-calculated statistical results and is instructed to return a structured explanation without changing any numbers.

The project is containerized with Docker Compose so the frontend and backend can be started consistently.

I used Codex throughout development to help inspect the repository, implement focused phases, review changes, add tests, enforce security boundaries, and validate the application. I used GPT-5.6 as a development partner for architecture planning, statistical reasoning, threat modeling, feature design, and explanation design.

Challenges

One of the biggest challenges was separating statistical prediction from generative AI. It would have been easier to ask an AI model for a match prediction, but that could produce inconsistent or unsupported numbers. I designed the system so that the Poisson engine calculates every probability and AI can only explain those results.

Another challenge was controlling scope. A full football platform could include live fixtures, player injuries, lineups, databases, user accounts, and external data providers. For the MVP, I intentionally used prepared illustrative data so the predictions remain reproducible and the core scenario-comparison idea could be completed securely.

Security was also a major focus. I added strict schemas, rejected unexpected inputs, kept API credentials on the backend, added request and rate-limit protections, sanitized failures, and prevented users from supplying arbitrary prompts or URLs.

Testing the application across Windows, Python environments, Docker, the frontend build, and Codex’s sandbox also created development challenges. The final backend test suite contains 242 passing tests, and the frontend production build and Docker Compose setup were validated.

What I learned

I learned how to:

  • Build a deterministic football prediction engine with a Poisson model
  • Convert scoreline probabilities into useful match-level metrics
  • Compare a statistical baseline with a tactical scenario
  • Keep generative AI grounded in calculated data
  • Design strict API contracts with FastAPI and Pydantic
  • Build a React and TypeScript comparison interface
  • Add process-local rate limiting and secure error handling
  • Containerize a full-stack application with Docker Compose
  • Use Codex effectively through small, reviewed implementation phases
  • Balance product ambition with a realistic and secure hackathon MVP

The most important lesson was that explainable AI applications need a clear source of truth. In MatchTwin AI, the statistical model provides the numbers, while AI supports development and explanation.

What's next

The current MVP uses a fixed France vs. Morocco demonstration. Future versions could add:

  • A catalog of validated matches
  • Team and fixture selection
  • Secure integration with a football-data provider
  • Additional tactical scenarios
  • Historical form and lineup inputs
  • Monte Carlo simulation
  • Frontend display of the structured AI explanation
  • More detailed visual comparisons

MatchTwin AI demonstrates how football predictions can become more transparent by showing not only what the model predicts, but also how tactical assumptions change the result.

Built With

Share this project:

Updates

Submission history