🎅 Santa Tracker

December 3, 2025 · View on GitHub

Track Santa's magical journey around the world on Christmas Eve! This interactive Progressive Web App provides real-time updates on Santa's location, destinations, and estimated arrival times.

✨ Features

🗺️ Interactive Map - Real-time visualization using Leaflet.js with OpenStreetMap
📍 Location Tracking - Current location, next destination, and route visualization
📏 Distance Calculator - Calculate distance from Santa to your location
⏱️ Countdown Timer - Live countdown to Christmas (UTC+14 timezone-aware)
🎄 Advent Calendar - Daily unlockable Christmas content (facts, games, stories, videos) (requires ADVENT_ENABLED=True)
🔐 Admin Dashboard - Comprehensive route and location management
📱 Progressive Web App - Installable with offline support
♿ Accessible - Full ARIA support, keyboard navigation, screen reader compatible
🎨 Responsive Design - Works seamlessly on all devices

🚀 Quick Start

Prerequisites

Python 3.10+
pip (Python package manager)
Modern web browser

Installation

# Clone the repository
git clone https://github.com/WxboySuper/Santa_Tracker.git
cd Santa_Tracker

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
npm install  # For frontend linting tools

# Run the application
python src/app.py

# Development mode with debug enabled
FLASK_DEBUG=True python src/app.py

# Enable advent calendar feature
ADVENT_ENABLED=True python src/app.py

Navigate to http://localhost:5000 to start tracking Santa!

🚩 Feature Flags

Flag	Default	Description
`ADVENT_ENABLED`	`False`	Enables the advent calendar feature. When disabled, the advent calendar UI, navigation links, and API endpoints are hidden/inaccessible.

To enable a feature flag, set the corresponding environment variable:

# Via environment variable
export ADVENT_ENABLED=True
python src/app.py

# Or in your .env file
ADVENT_ENABLED=True

📁 Project Structure

Santa_Tracker/
├── src/
│   ├── static/          # CSS, JavaScript, images
│   ├── templates/       # HTML templates
│   ├── utils/           # Core logic (tracker, locations, advent)
│   └── app.py           # Flask application
├── tools/
│   └── route-editor/    # Standalone route editor tool (React + Vite)
├── docs/                # Documentation
├── tests/               # Test suite
├── config.py            # Configuration
└── requirements.txt     # Python dependencies

Backend: Flask, Gunicorn, Geopy, Python-dotenv
Frontend: Tailwind CSS (CDN), Leaflet.js, Vanilla JavaScript, CSS3
DevOps: GitHub Actions, Dependabot, DeepSource
Testing: pytest, pytest-cov (79% coverage across 140 tests)

🧪 Testing & Route Simulation

Running Tests

# Run all tests with coverage
pytest --cov=src --cov-report=term-missing tests/

# Run specific test files
pytest tests/test_tracker.py -v
pytest tests/test_route_generation.py -v

# Quick test run
pytest tests/ -q

Route Simulation

The admin dashboard includes a Route Testing & Simulation feature that allows you to:

Test Santa's route with different timing scenarios
Preview routes before finalizing them
Simulate with custom start times
Test specific location subsets
View detailed timing calculations and summaries

Access via Admin Dashboard → Route Testing & Simulation → Simulate Route

API Endpoint: POST /api/admin/route/simulate

Accepts optional start_time (ISO 8601 format) and location_ids (array)
Returns simulated route with arrival/departure times
Does not modify stored route data

Test Coverage

tracker.py: 100% coverage
locations.py: 94% coverage
advent.py: 95% coverage
app.py: 75% coverage
Overall: 79% coverage (140 tests passing)

🛠️ Developer Tools

Santa Route Editor

A standalone visual route editor for creating and managing Santa's journey routes. This tool provides:

Interactive map interface with geocoding search
Drag-and-drop route ordering
Editable location metadata (priority, UTC offset, notes, etc.)
JSON export matching the Santa Tracker route format

Quick Start:

cd tools/route-editor
npm install
npm run dev

See tools/route-editor/README.md for detailed documentation.

📚 Documentation

Architecture Guide - Design choices, performance, accessibility
Development Guide - Testing, linting, building, static generation
Admin Dashboard - Route management and admin features
Countdown Timer - Timer implementation details
Advent Calendar API - Advent calendar system documentation
Configuration - Environment variables and settings
Deployment - Deployment to Heroku, Vercel, Netlify
API Usage - API integration guide

🤝 Contributing

We welcome contributions! Here's how:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and test thoroughly
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See our Pull Request Template for guidelines.

Santa tracking route inspired by NORAD Santa Tracker
Map tiles by OpenStreetMap contributors
Icons from open-source projects

📞 Support

📫 Create an issue
💬 Start a discussion
⭐ Star this repo if you find it helpful!

Made with ❤️ for the holiday season

May your Christmas be merry and bright! 🎅🎄