Lottery-Tracker/updates.md

Lottery Tracker — Update Log

Overview

Complete codebase overhaul: cleanup, modernization, new features, and full Next.js frontend build.

---

Phase 1: Code Review & Cleanup

Files Deleted

• email_sender.py — Email sending logic (removed entire email system)
• send_email_now.py — Manual email trigger
• test_email.py — Email tests
• analyze_excel.py — Excel analysis utility
• read_excel.py — Excel reader utility
• import requests.py — Misnamed utility script
• powerball_numbers.html — Debug HTML file
• megamillions_debug.html — Debug HTML file
• Dockerfile.email — Email service Docker image
• EMAIL_SETUP.md — Email configuration docs

Issues Fixed

• Hardcoded credentials removed (Gmail password in docker docs)
• verify=False on all HTTP requests replaced with default SSL verification
• Code duplication — scraping logic was copy-pasted across 3 files, consolidated into one
• No tests — full test suite added
• No linting — ruff configured
• Flask debug=True hardcoded — replaced with env var
• Docker healthcheck used curl (not installed in slim image) — switched to Python urllib
• .dockerignore missing .venv/ — build context was 456 MB, now much smaller

---

Phase 2: Backend Rewrite

New Modules

config.py

• AppConfig dataclass with nested ScraperURLs, TaxConfig, InvestmentDefaults
• STATE_TAX_RATES — all 51 US states + DC with 2024-2025 tax rates
• LOTTERY_ODDS — odds and ticket costs for all 4 lotteries
• ANNUITY_YEARS, ANNUITY_ANNUAL_INCREASE constants
• load_config() reads from environment variables with sensible defaults

scrapers.py

• Unified scraping with TTL cache (6-hour default via cachetools)
• scrape_powerball() / scrape_mega_millions() — requests + BeautifulSoup from lotto.net
• scrape_canadian_lotteries() — Playwright sync API from olg.ca
• get_all_jackpots() — returns all 4 jackpots with cache
• clear_cache() — force refresh

app.py (Rewritten)

Flask app factory pattern (create_app()) with endpoints:

Endpoint	Method	Description
/api/jackpots	GET	Current jackpots (cached)
/api/jackpots/refresh	POST	Force-refresh jackpots
/api/calculate	POST	Full investment calculation with state tax
/api/states	GET	All US states with tax rates
/api/states/<code>	GET	Single state info
/api/compare	GET	Side-by-side all 4 lotteries
/api/calculate/breakeven	POST	Break-even jackpot analysis
/api/calculate/annuity	POST	Annuity payment schedule
/api/calculate/group	POST	Group play split
/api/odds	GET	Probability data for all lotteries
/api/health	GET	Health check

lottery_calculator.py (Rewritten)

Pure calculation functions with explicit parameters:

• _run_investment_cycles() — shared 90-day reinvestment cycle logic
• calculate_us_lottery() — lump sum + federal/state tax + CAD conversion + cycles
• calculate_canadian_lottery() — tax-free + investment cycles
• calculate_break_even() — EV formula: required jackpot for positive expected value
• calculate_annuity() — 30-year schedule with configurable annual increase
• calculate_group_split() — N-way split with custom share ratios

Configuration Files

• requirements.txt — pinned versions, removed openpyxl/pandas/schedule
• requirements-dev.txt — pytest, pytest-mock, pytest-cov, httpx, ruff
• pyproject.toml — ruff config (line-length=100, py311 target), pytest config
• .env.example — all environment variables documented

Test Suite (64 tests, all passing)

• tests/conftest.py — Flask test fixtures
• tests/test_lottery_calculator.py — ~25 tests (US calc, Canadian calc, break-even, annuity, group split)
• tests/test_api.py — ~15 endpoint integration tests with mocked scrapers
• tests/test_config.py — config loading, env override, state validation
• tests/test_scrapers.py — parser tests, mocked HTTP, cache behavior

---

Phase 3: Frontend (Next.js 15 + MUI 6)

Scaffold

• frontend/package.json — Next.js 15.1.4, MUI 6.3.1, Recharts 2.15, Axios
• frontend/tsconfig.json — standard Next.js TypeScript config with @/* paths
• frontend/next.config.js — standalone output, /api/* rewrite to backend
• frontend/.env.local — NEXT_PUBLIC_API_URL=http://localhost:5000

Shared Libraries

• frontend/lib/types.ts — Full TypeScript interfaces (JackpotData, Calculation, StateInfo, BreakEvenResult, AnnuityResult, GroupResult, OddsInfo, etc.)
• frontend/lib/api.ts — Typed Axios client with all API endpoint functions
• frontend/lib/format.ts — formatCurrency, formatCurrencyFull, formatPercent, formatNumber
• frontend/lib/theme.ts — Dark MUI theme (primary: #4fc3f7, background: #0a1929)

Components

• frontend/components/ThemeRegistry.tsx — MUI ThemeProvider wrapper with CssBaseline
• frontend/components/NavBar.tsx — Sticky app bar with navigation links

Pages (7 routes)

Route	File	Description
/	app/page.tsx	Home — jackpot cards grid (4 lotteries) + tool cards grid (6 tools)
/calculator	app/calculator/page.tsx	Investment calculator — jackpot input, lottery type, state selector with tax rates, invest % slider, annual return slider, cycles, results summary, 90-day cycle table
/compare	app/compare/page.tsx	Side-by-side comparison — state selector, 4 lottery cards with jackpot, odds, after-tax take-home, daily/annual income
/breakeven	app/breakeven/page.tsx	Break-even analysis — lottery/state selectors, required jackpot, odds, probability, take-home fraction, expected value
/annuity	app/annuity/page.tsx	Annuity calculator — jackpot, type, years, annual increase slider, summary cards, year-by-year payment schedule table
/group	app/group/page.tsx	Group play — member count, custom share weights, per-member breakdown table (share %, jackpot share, after-tax, daily/annual income)
/odds	app/odds/page.tsx	Probability display — odds, percentage, ticket cost, log-scale relative bar, "50% chance" ticket count

---

Phase 4: Docker & Infrastructure

Docker Images Built

Image	Size	Description
lottery-tracker-backend	2.28 GB	Python 3.13-slim + Playwright Chromium + Gunicorn
lottery-tracker-frontend	285 MB	Node.js 20-alpine + Next.js standalone

Docker Fixes Applied

1. Removed playwright install-deps chromium from Dockerfile.backend — system deps already installed manually; the auto-installer fails on newer Debian due to renamed font packages (ttf-unifont → fonts-unifont)
2. Generated package-lock.json — required by npm ci in frontend Dockerfile
3. Created frontend/public/ directory with manifest.json — Dockerfile COPY step requires it
4. Added .venv/ to .dockerignore — was inflating build context
5. Removed version: '3.8' warning — obsolete in modern Docker Compose
6. Removed email-scheduler service from docker-compose.yml
7. Switched healthcheck from curl to python -c "import urllib.request; ..."
8. Backend CMD changed to gunicorn (2 workers, 120s timeout)

MUI Grid Fix

All 7 frontend pages used <Grid size={{ xs: 12, sm: 6 }}> syntax (Grid2 API), but imported Grid from @mui/material (legacy Grid v1). Fixed by changing imports to Grid2 as Grid in all pages.

Running Containers

Container	Status	Port Mapping
lottery-backend	Up (healthy)	0.0.0.0:5000 → 5000
lottery-frontend	Up	0.0.0.0:3003 → 3000

Access URLs

• Frontend: http://localhost:3003
• Backend API: http://localhost:5000/api/health

---

Phase 5: Documentation & Config

Updated Files

• .gitignore — added .next/, *.xlsx, *.html, ssl/ certs, coverage outputs
• AGENTS.md — filled in repo facts (Python 3.13/Flask + Next.js 15/MUI 6, pytest, ruff, docker compose)
• DOCKER_README.md — rewritten: removed email references, removed hardcoded password, added .env.example workflow, config table, production deployment guide
• DOCKER_QUICKSTART.md — rewritten: removed email service, updated container descriptions, simplified quick start

---

Verification

• 64/64 tests passing (pytest -q)
• ruff lint clean (ruff check . — all checks passed)
• Docker build successful — both images built
• Containers running — backend healthy, frontend serving

---

Architecture Summary

┌─────────────────────────────────────────────────┐
│                   nginx (prod)                   │
│              Rate limiting + SSL                 │
├─────────────────┬───────────────────────────────┤
│   Frontend      │       Backend                  │
│   Next.js 15    │       Flask 3.1                │
│   MUI 6         │       Gunicorn                 │
│   TypeScript    │       Python 3.13              │
│   Port 3000     │       Port 5000                │
│                 │                                │
│   7 pages       │   11 API endpoints             │
│   Dark theme    │   4 lottery scrapers           │
│   Axios client  │   TTL cache (6h)               │
│                 │   51 state tax rates            │
│                 │   Playwright (Canadian)         │
└─────────────────┴───────────────────────────────┘

Tech Stack

• Backend: Python 3.13, Flask 3.1, Gunicorn, BeautifulSoup, Playwright
• Frontend: Next.js 15, TypeScript, Material-UI 6, Recharts, Axios
• Testing: pytest (64 tests), ruff (lint)
• Docker: Multi-container (backend + frontend + nginx for prod)
• Config: Environment variables via .env + python-dotenv