# Route Tracker v3 A PHP-based system that collects Google Maps Directions API data for recurring family trips, stores statistics over time in SQLite, identifies the best routes per day/time/season, and sends alerts via multiple channels when traffic is unusually heavy or a better alternative exists. All configuration is stored in SQLite — no YAML files required. --- ## Features - **Departure Advisor** — tells you what time to leave to arrive by a target time, accounting for live traffic and historical variance - **Quick Trips** — create one-time advisor routes directly from the dashboard for ad-hoc journeys; auto-deactivate once the trip window passes - **Multi-channel alerts** — Telegram, Email, Signal, Viber - **Statistics dashboard** — overview, best routes by day, trends, history - **Scheduled collection** — single cron job handles both data collection and advisor logic --- ## Directory Structure ``` tracker/ ├── web/ # Apache DocumentRoot (browser-accessed files only) │ ├── .htaccess # Security rules │ ├── api.php # JSON REST API │ ├── dashboard.php # Main dashboard │ ├── settings.php # Admin settings UI │ ├── login.php # Login page │ ├── monitor.php # Public monitoring page │ ├── css/ │ │ ├── dashboard.css │ │ └── settings.css │ └── js/ │ ├── dashboard.js │ └── settings.js ├── src/ # PHP source (classes + CLI scripts) │ ├── Config.php # SQLite-backed config singleton │ ├── AlertManager.php # Multi-channel alert dispatch │ ├── DepartureAdvisor.php # Advisor logic │ ├── auth.php # Session authentication │ ├── collector.php # CLI data collection │ ├── advisor.php # CLI cron entry point │ └── schema.php # CLI DB initialization ├── config/ # Configuration templates │ ├── settings.php # Deployment-level constants (optional, has defaults) │ └── apache.config # Apache vhost example ├── scripts/ # Utility scripts │ └── install.sh # Automated installer ├── data/ # Runtime data (gitignored) │ ├── routes.sqlite │ ├── collector.log │ ├── alerts.log │ ├── advisor.log │ └── alert_counts.json ├── CLAUDE.md └── README.md ``` --- ## Quick Start ```bash # 1. Install + check dependencies sudo ./scripts/install.sh --check-only # check only sudo ./scripts/install.sh # full install to /var/www/route-tracker # 2. Initialize database php src/schema.php --init # 3. Test API connection php src/collector.php --test # 4. Start dev web server php -S 0.0.0.0:8080 -t web # 5. Open http://your-server:8080/login.php # Default password: changeme # 6. Configure via Settings UI: # - General: add Google Maps API key, set timezone # - Routes: add routes with schedules # - Alerts: configure Telegram/Email/Signal/Viber ``` --- ## Requirements | | | |--|--| | OS | Linux (Ubuntu 20.04+ / Debian 11+) | | PHP | 7.4+ (8.x recommended) | | PHP extensions | `curl`, `sqlite3` (no PECL yaml needed) | | Web server | Apache or Nginx (or PHP built-in) | | Cron | For scheduled collection | --- ## Dashboard The dashboard has six tabs, with the layout (top → bottom): **header** → **tab bar** → **route/time filter chips** → **content** | Tab | Description | |-----|-------------| | **Advisor** | Live departure recommendations per route. Shows recommended leave-by time, countdown, and alert stages fired. | | **Overview** | Average, best, and worst travel times per route. | | **Best Routes** | Best road/alternative per route per day of week. | | **By Day** | Average durations broken down by day of week. | | **Trends** | Timeline and monthly charts. | | **History** | Last 100 collections with route and status detail. | ### Quick Trips The `⚡ Quick Trip` split button in the header lets you create a one-time advisor route for an ad-hoc journey: 1. Click `⚡ Quick Trip` → fill in destination, origin (optional), and arrive-by time (HH:MM, 24-hour) 2. The trip appears on the **Advisor** tab immediately with a yellow `⚡ one-time` badge 3. It auto-deactivates after the arrival window passes (handled by the next cron run) 4. Delete it manually with the `✕` button on its card, or bulk-remove all expired ones via `▾ → 🗑 Clean up expired` --- ## Web Server Setup Point your DocumentRoot at the `web/` directory. This keeps PHP classes, CLI scripts, and the `data/` directory outside the web root. **Apache:** ```apache ServerName routes.yourdomain.com DocumentRoot /path/to/tracker/web DirectoryIndex dashboard.php AllowOverride All Require all granted Require all denied ``` **Nginx:** ```nginx server { listen 80; server_name routes.yourdomain.com; root /path/to/tracker/web; index dashboard.php; location ~ \.php$ { fastcgi_pass unix:/var/run/php/php-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location /data/ { deny all; } location ~ \.sqlite$ { deny all; } location ~ \.log$ { deny all; } } ``` --- ## CLI Reference | Command | Effect | |---------|--------| | `php src/schema.php --init` | Create tables + seed defaults (safe to re-run) | | `php src/schema.php --reset` | Drop all tables, recreate, re-seed (DELETES ALL DATA) | | `php src/collector.php` | Collect routes within scheduled window | | `php src/collector.php --force` | Collect ALL routes now | | `php src/collector.php --force --route=dad_work` | Force one specific route | | `php src/collector.php --test` | API call + show results, don't save | | `php src/collector.php --schedule` | Print schedule + cron lines | | `php src/advisor.php` | Manual advisor run (also deactivates expired Quick Trips) | --- ## Cron Setup Single cron job handles advisor checks, data collection, and Quick Trip cleanup: ``` */5 * * * * php /path/to/tracker/src/advisor.php >> /path/to/tracker/data/advisor.log 2>&1 ``` --- ## Default Credentials - Password: `changeme` (set by `schema.php --init`) - Change via Settings → General → Change Password --- ## Cost Estimate Google Maps Directions API: ~$5 per 1000 requests. With 3 routes × 4 collections/hour × active windows ≈ 200–300 requests/month ≈ **~$1–1.50/month**. Enable billing on Google Cloud Console and restrict the API key to: - **APIs**: Directions API only - **IP restrictions**: your server's IP address