World Cup 2026 Companion App

A lightweight web app to pick a country and view its FIFA World Cup 2026 status: group standings, progression, results, and upcoming fixtures. Data is refreshed daily from a free football API. An optional Solana betting layer and a warehouse-ready analytics pipeline are built on top.

• Backend: FastAPI + SQLite, ingests from Football-Data.org (competition code WC), with a daily scheduled refresh.
• Frontend: React + Vite + TypeScript, TailwindCSS, React Query, Recharts.
• Betting (add-on): parimutuel match-winner betting in USDC on Solana devnet, with tiered subscriptions — an Anchor program plus a backend mirror/oracle layer and a betting UI.
• Analytics (add-on): an append-only event log with a DuckDB ELT proof-of-concept, designed to port to Snowflake.

backend/          FastAPI service (ingestion, progression, REST API, betting layer)
  app/            application code (routers, models, betting.py, analytics.py, ...)
  elt/            DuckDB ELT proof-of-concept for betting analytics
  tests/          pytest suite
frontend/         React + Vite single-page app (incl. the Betting page)
anchor/           wc_betting Anchor program (Rust) — Solana smart contract
betting-program-spec.md   full on-chain program specification
analytics-schema.md       analytics star schema + Snowflake DDL / ELT design
architecture.md           system architecture + diagrams (incl. section 11 betting)

• Python 3.11+
• Node 18+
• A free Football-Data.org API key — sign up at https://www.football-data.org/client/register. The free tier covers the World Cup.
• (Betting on-chain only) the Solana/Anchor toolchain — see anchor/README.md.

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then paste your API key into FOOTBALL_DATA_API_KEY
uvicorn app.main:app --reload

The API serves on http://localhost:8000. Interactive docs at http://localhost:8000/docs.

On first startup (with an empty DB) the app ingests live data. If the API is unreachable it falls back to the last-good snapshot in backend/data/snapshot.json.

Run tests:

cd backend && pytest        # 28 tests: app + betting + analytics + ELT

cd frontend
npm install
cp .env.example .env          # VITE_API_URL defaults to http://localhost:8000
npm run dev

The app serves on http://localhost:5173. The Betting page is at /betting.

Parimutuel betting on the match winner (HOME/AWAY only; a DRAW voids the market and refunds everyone), settled in USDC. Subscriptions gate betting and come in two tiers (Standard, Premium — Premium pays a reduced house fee). Full design in betting-program-spec.md.

• On-chain custody + payouts live in the wc_betting Anchor program (anchor/).
• The backend is the oracle (maps Match.winner/FINISHED → settle/void) and read-model indexer; it never custodies funds.

⚠️ On-chain betting is not live. The Anchor program is committed as source only and has not been compiled/deployed (it needs the Solana toolchain). The UI shows live odds and payout previews but disables real bet/claim actions. See architecture.md section 11.1.

Every betting state change is written to an append-only analytics_events log (in the same transaction as the mirror update). A DuckDB ELT proof-of-concept (backend/elt/) consumes the extraction feed and builds a star schema (facts + dims), validating the model locally before any Snowflake spend. Design and Snowflake DDL in analytics-schema.md; how to run the PoC in backend/elt/README.md.

The MVP targets a single host: the frontend builds to static assets (vite build → dist/) and the backend runs Uvicorn with a local SQLite file. See architecture.md section 9.

• Piwe (twala.simphiwe@gmail.com) — author & maintainer
• Claude (Anthropic — Claude Code, Opus 4.8) — co-developer

The betting framework, analytics pipeline, and supporting docs were built in collaboration with Claude Code; see the Co-Authored-By trailers in the commit history.