hermes-skills/skills/devops/python-web-service-deployment/references/shark-game-architecture.md

Shark Attack Fantasy Game — Technical Reference

Game Overview

Fantasy league where players draft coastal regions and score points from real shark activity (sightings, bites, fatalities) reported globally. AI scraper searches for incidents daily.

Architecture

• Frontend: Mobile-first PWA at /var/www/shark-game/ (index.html, draft-room.html, league.html, how-to-play.html)
• Backend: FastAPI at /root/shark-game/backend/server.py on port 8083
• Database: SQLite at /root/shark-game/backend/game.db
• AI Scraper: Firecrawl + admin-ai classification pipeline at /root/shark-game/scraper/scrape.py
• Domain: shark.iamgmb.com (Cloudflare A record → 152.53.192.33)
• Proxy: Caddy reverse_proxy /api/* → 127.0.0.1:8083, static files from /var/www/shark-game/

Scoring

Event	Points
Sighting	2
Bite	5
Fatality	10

Regions

32 coastal regions with real 10-year ISAF (International Shark Attack File) data. Data source: /root/shark-game/references/shark-incident-data-10yr.md. Database pre-populates on startup.

Draft Balancing

When draft starts with N players, the lowest-performing regions are removed so 32 % N = 0. Removed regions show as "🚫 Removed" on map and card grid.

Map View

Uses Leaflet.js (CDN) with OpenStreetMap tiles. Dark-themed controls. Region markers are color-coded: teal=available, amber=your pick, red=taken, gray=excluded.

API Endpoints

All under /api/:

• Auth: register, login, me
• Leagues: create, join, list, detail, settings
• Draft: board, pick, start
• Scores: leaderboard, daily, events
• Regions: list, events