A Java web application for tracking FIFA World Cup matches, teams, venues, and live events — with AI-powered match commentary and interactive venue maps.
World Cup Tracker is a full-stack Java capstone project that brings the World Cup to life in a single web application. Users can browse team profiles, follow match results, explore host venues on an interactive map, and read AI-generated tactical commentary that breaks down how competing teams match up — without spoiling the outcome.
- Live and scheduled match listings with scores and status
- Team profiles including squad info, group standings, and tournament history
- Match detail pages with lineups, stats, and timeline events
- Interactive maps showing all World Cup host stadiums
- Venue detail pages with capacity, location, and scheduled matches
- Visual callouts linking matches to their host city
- Pre-match tactical analysis generated by an AI model
- Highlights stylistic matchups: how one team's defensive shape sets up against another's attacking system
- Deliberately non-predictive — focuses on narratives and contrasts, not picks or scores
- Examples: "Portugal's fluid front three will test England's narrow defensive mid, but England's set-piece game may be their equalizer."
- Graphic assets for team flags, tournament branding, and venue photography
- Clean, tournament-themed UI built to feel like a sports broadcast dashboard
| Layer | Technology |
|---|---|
| Language | Java 21 |
| Web Framework | Spring Boot |
| Template Engine | Thymeleaf |
| Build Tool | Maven |
| Database | PostgreSQL |
| ORM | Spring Data JPA / Hibernate |
| External APIs | FIFA / football-data.org / API-Football |
| Maps | Google Maps JavaScript API (or Leaflet.js) |
| AI Commentary | Anthropic Claude API (or OpenAI) |
| Frontend | HTML/CSS, Bootstrap, vanilla JS |
| Testing | JUnit 5, Mockito |
┌─────────────────────────────────────────────────────────┐
│ Browser / Client │
└───────────────────────┬─────────────────────────────────┘
│ HTTP
┌───────────────────────▼─────────────────────────────────┐
│ Spring Boot Application │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ Controllers │ │ Services │ │ AI Commentary │ │
│ └──────┬──────┘ └──────┬───────┘ │ Service │ │
│ │ │ └───────┬────────┘ │
│ ┌──────▼──────┐ ┌──────▼───────┐ │ │
│ │ Thymeleaf │ │ Repositories │ ┌──────▼──────┐ │
│ │ Templates │ └──────┬───────┘ │ Claude / │ │
│ └─────────────┘ │ │ OpenAI API │ │
│ ┌─────▼──────┐ └─────────────┘ │
│ │ PostgreSQL │ │
│ └─────┬──────┘ │
│ ┌─────▼──────┐ │
│ │ External │ │
│ │ Sports API │ │
│ └────────────┘ │
└─────────────────────────────────────────────────────────┘
Team — id, name, country, flag_url, group, coach
Match — id, home_team, away_team, venue, kickoff_time, score, status
Venue — id, name, city, country, capacity, lat, lng, image_url
MatchEvent — id, match_id, type (goal/card/sub), minute, player, team
Commentary — id, match_id, content, generated_at
- football-data.org — Free tier available; teams, matches, standings
- API-Football — Richer event/lineups data; freemium
- ESPN / ESPN API (unofficial) — Scores and stats
- Google Maps JavaScript API — Venue pins, info windows, styled map
- Leaflet.js + OpenStreetMap — Open-source alternative; no API key required
- Anthropic Claude API — Generates pre-match tactical breakdowns
- Prompt is engineered to produce color commentary only — no winner predictions
- Commentary is cached in the database to avoid redundant API calls
- Java 21+
- Maven 3.9+
- PostgreSQL 15+
- API keys for: sports data provider, maps, and AI (Claude or OpenAI)
git clone https://github.com/<your-org>/world-cup-tracker.git
cd world-cup-tracker
cp src/main/resources/application.example.properties src/main/resources/application.propertiesEdit application.properties:
spring.datasource.url=jdbc:postgresql://localhost:5432/worldcup
spring.datasource.username=your_db_user
spring.datasource.password=your_db_password
api.football.key=YOUR_SPORTS_API_KEY
api.maps.key=YOUR_MAPS_API_KEY
api.anthropic.key=YOUR_CLAUDE_API_KEYmvn spring-boot:runNavigate to http://localhost:8080
mvn spring-boot:run -Dspring-boot.run.arguments="--seed"This will load teams, venues, and any available scheduled matches from the external API.
src/
├── main/
│ ├── java/com/zipcode/worldcuptracker/
│ │ ├── controller/ # Spring MVC controllers
│ │ ├── model/ # JPA entities
│ │ ├── repository/ # Spring Data repositories
│ │ ├── service/ # Business logic, API clients
│ │ │ ├── MatchService.java
│ │ │ ├── SportsApiService.java
│ │ │ └── CommentaryService.java
│ │ └── WorldCupTrackerApplication.java
│ └── resources/
│ ├── templates/ # Thymeleaf HTML templates
│ ├── static/ # CSS, JS, images
│ └── application.properties
└── test/
└── java/com/zipcode/worldcuptracker/
├── service/
└── controller/
The commentary engine is intentionally scoped to tactical and stylistic analysis only. The prompt explicitly instructs the model not to predict a winner.
Example prompt pattern:
You are a football analyst providing pre-match color commentary.
Analyze how [Team A] and [Team B] might match up tactically.
Focus on: playing styles, key matchups, historical tendencies, strengths and vulnerabilities.
Do NOT predict a winner or suggest one team is likely to beat the other.
Keep the tone engaging, like a broadcast analyst before kickoff.
Generated commentary is stored in the commentary table keyed to match_id so it is only generated once per match.
- User accounts with favorite teams and match watchlists
- Push notifications for match kickoffs (WebSocket or polling)
- Historical tournament data (past World Cups)
- Mobile-responsive redesign
- Docker Compose setup for one-command local environment
Built by ZipCode Wilmington cohort students as part of the capstone program.
MIT