Admin Dashboard

November 12, 2025 · View on GitHub

The Santa Tracker includes a comprehensive admin dashboard for managing locations, routes, and content.

🔑 Accessing the Dashboard

Setup

Set the admin password as an environment variable:

export ADMIN_PASSWORD="your-secure-password"

Or add to .env file:

ADMIN_PASSWORD=your-secure-password

Start the application:
```
python src/app.py
```
Navigate to http://localhost:5000/admin
Enter your admin password to log in

Session Management

Sessions are secure with Bearer token authentication
Sessions expire after inactivity
Multiple admin sessions supported
Logout available via interface

📍 Location Management

Add Location

Create new stops on Santa's route with complete details:

Required Fields:

Location Name: City, town, or landmark name
Latitude: Geographic latitude (-90 to 90)
Longitude: Geographic longitude (-180 to 180)
UTC Offset: Timezone offset from UTC (e.g., -5, +1)

Optional Fields:

Country: Country name
Population: City population
Priority: 1 (highest) to 3 (lowest)
Arrival Time: Scheduled arrival (ISO 8601 format)
Departure Time: Scheduled departure (ISO 8601 format)
Notes: Additional information

Example:

{
  "name": "New York City",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "utc_offset": -5,
  "country": "United States",
  "population": 8336817,
  "priority": 1,
  "notes": "Times Square celebration"
}

Edit Location

Modify existing locations:

Select location from list
Update any fields
Save changes
Re-run route precomputation if timing changed

Delete Location

Remove locations from the route:

Select location to delete
Confirm deletion
Location removed permanently
Re-precompute route to update timing

Import Locations

Bulk import from JSON files:

Supported Formats:

// Format 1: Array in "route" key
{
  "route": [
    {"name": "City1", "latitude": 40.0, "longitude": -74.0, ...},
    {"name": "City2", "latitude": 51.5, "longitude": -0.1, ...}
  ]
}

// Format 2: Array in "locations" key
{
  "locations": [...]
}

// Format 3: Direct array
[
  {"name": "City1", ...},
  {"name": "City2", ...}
]

// Format 4: Single object
{
  "name": "City1",
  "latitude": 40.0,
  ...
}

Import Modes:

Append: Add to existing locations
Replace: Clear existing, then import

Validate Locations

Check route data for errors:

Missing required fields
Invalid coordinates
Duplicate locations
Timezone inconsistencies
Invalid date formats

Results show:

✅ Validation passed
❌ Errors found with details
Suggestions for fixes

🗺️ Route Management

Precompute Route

Automatically calculate optimal route timing:

Process:

Sorts locations by UTC offset (follows time zones)
Assigns arrival/departure times
Calculates stop durations based on priority:
- Priority 1: Longer stops (major cities)
- Priority 2: Medium stops
- Priority 3: Touch and go stops
Ensures logical progression through time zones

Configuration:

Start time: December 24, 00:00 UTC+14
Travel time calculated by distance
Stop duration based on priority and population

Usage:

Click "Precompute Route" button
Review confirmation dialog
Wait for processing
Check route status for results

View Route Status

Display comprehensive route statistics:

Metrics:

Total Locations: Number of stops on route
Locations with Times: Complete timing data
Priority Breakdown: Distribution of priorities
Last Modified: Most recent update timestamp
Completion Status: Overall route readiness

Status Indicators:

🟢 Complete: All locations have timing
🟡 Incomplete: Some locations missing data
🔴 Empty: No locations in route

💾 Data Management

Export Backup

Download complete route data:

Features:

Full location details included
Timing information preserved
Timestamped filename: santa_route_backup_YYYYMMDD_HHMMSS.json
Can be reimported later

Usage:

Click "Export Backup"
File downloads automatically
Store safely for disaster recovery

File Structure:

{
  "exported_at": "2024-12-01T10:30:00Z",
  "version": "1.0",
  "total_locations": 150,
  "route": [
    {
      "name": "Wellington",
      "latitude": -41.2865,
      "longitude": 174.7762,
      "utc_offset": 13,
      "priority": 1,
      "arrival_time": "2024-12-24T11:00:00Z",
      "departure_time": "2024-12-24T11:15:00Z"
    }
  ]
}

Import from Backup

Restore from previously exported backup:

Click "Import Locations"
Select backup JSON file
Choose mode (append/replace)
Confirm import
Validate imported data

🔄 Admin Workflow

Initial Setup

Access Dashboard
- Set ADMIN_PASSWORD
- Log in to admin interface
Import Initial Data
- Use bulk import for starter data
- Or manually add locations
Set Priorities
- Assign priorities (1-3)
- Priority 1 for major cities
- Priority 3 for small towns
Validate Data
- Run validation check
- Fix any reported errors

Route Preparation

Precompute Timing
- Click "Precompute Route"
- Wait for completion
- Review route status
Review Results
- Check all locations have times
- Verify logical progression
- Adjust if needed
Export Backup
- Download backup before going live
- Store in safe location

Ongoing Maintenance

Add New Locations
- Add as requested
- Re-run precomputation
Update Timing
- Edit locations as needed
- Precompute to recalculate
Regular Backups
- Export weekly during setup
- Export daily during live tracking
Data Quality
- Run validation regularly
- Address issues promptly