Football Prediction AssistantSports data and AI explanations

The problem & workflow

User asks about standings or a match → teams/league are resolved → provider data is assembled → features and heuristic score are calculated → AI explains the supplied evidence → response reports provider usage.

Key features

• Team extraction and supported-league lookup
• Standings with season fallback
• Provider retry and in-memory caching
• Feature building, weighted score and data completeness
• Structured prompts and AI output parsing
• Express validation/rate limiting and Next.js interface

Architecture & decisions

• Environment loading belongs in the configuration module before validation, not after importing it.
• Rate limiting must cover the mounted `/chat` and `/leagues` paths; the previous `/api/` prefix did not protect them.
• Data completeness and season fallback are part of the response story. A response timestamp is not the age of its provider data.
• AI prose explains structured evidence; it does not establish calibrated betting or prediction accuracy.

Inside the source

• backend/src/config/env.ts
• backend/src/server.ts
• backend/src/routes/chat.ts
• backend/src/prediction/featureBuilder.ts
• backend/src/providers/apiFootball/client.ts

Turning structured football data into an explainable estimate

I built this application to turn football data into structured analysis and AI explanations.

The TypeScript backend extracts teams, requests standings, handles season fallback and builds features before producing a weighted estimate and optional AI explanation. Separating the score from the explanation makes an important boundary visible: fluent language does not validate the estimate. A historical evaluation is still required before claiming prediction accuracy.

Provider caching, retries and response parsing influence how complete and fresh the inputs are. The release records fixture/provider use accurately and offers deterministic generated teams, so an evaluator can reproduce a standings or match-analysis response without paid API calls or current live fixtures.

Configuration and middleware must match the real execution paths

Environment loading now runs before validation. Rate limiting covers the actual /chat, /leagues and /health routes rather than an unused /api prefix. These are small changes with practical effects: correct credentials should be read at startup, and the intended middleware should protect the routes the application mounts.

All 21 backend tests, type checking and the frontend production build passed locally. A focused Next.js update addresses confirmed advisories; remaining build-tool dependency findings are documented rather than erased through an unreviewed major styling migration. Provider outages, ambiguous inputs and malformed explanations remain explicit verification concerns.

Project status

Football data and AI analysis application. A heuristic estimate is not a validated predictive model.

Use Node 20+. Copy backend/.env.example to backend/.env and enable FIXTURE_MODE=1, PORT=3333. Put NEXT_PUBLIC_API_URL=http://localhost:3333 in frontend/.env.local before startup/build. Fixture analysis uses Demo United and Sample City and a fixed timestamp. Live mode requires the sports and AI keys from the backend example; paid calls are unnecessary for evaluation.