Itinera Platform Summary
Last updated: February 24, 2026
Overview
Itinera is a route optimization and fleet management platform built for mid-size to enterprise trucking carriers. It combines permit-compliant routing, fuel stop optimization, fleet tracking via Samsara, and driver compliance monitoring.
Repository: GitHub ioncernenchii/itinera (private) · Local folder: /Itinera
Live at: https://app.getitinera.com · Droplet IP: 45.55.214.61
Core value proposition:
- Fuel savings of ~$10 per optimized fuel stop
- Avoid permit violations ($2,000+ each, plus FMCSA safety record damage)
- Automated route generation with Google Maps (HERE Technologies migration planned)
- Real-time fleet tracking and deviation monitoring
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 14.2.35, React 18, TypeScript, Tailwind CSS |
| Backend | Next.js API Routes |
| Database | PostgreSQL 16 with Prisma ORM |
| Authentication | NextAuth.js (credentials provider + invite system + TOTP 2FA) |
| Maps | Google Maps JavaScript API, Directions API, Geocoding API |
| Fleet Integration | Samsara API (vehicles, drivers, GPS locations) |
| Notifications | Telegram Bot API (route deviation + fuel alerts) |
| Charts | Recharts |
| UI Components | Radix UI primitives, Lucide icons |
| File Processing | xlsx → exceljs (migration pending, see ROADMAP Phase 0) |
| 2FA | Custom TOTP (Node.js crypto, RFC 6238/4226), qrcode (QR generation) |
| Hosting | DigitalOcean droplet (2GB/1CPU, Ubuntu 24.04), Nginx, PM2, Let's Encrypt SSL |
Core Features
1. Authentication & Security
- Email/password login via NextAuth.js with JWT sessions (24-hour expiry)
- Invite-based registration with optional email lock and configurable expiry
- Two-factor authentication (TOTP) via authenticator apps
- Role-based access control (ADMIN / DISPATCHER — expanding to 6 roles, see ROLES_PERMISSIONS.md)
- Account deactivation, admin password reset with forced change flow
- Rate limiting on login (per-email + per-IP), registration, and all 2FA endpoints
- CSRF protection middleware, password blocklist, cross-entity ownership checks
2. Route Management
- Full CRUD with status lifecycle: DRAFT → ACTIVE → COMPLETED / CANCELLED
- Waypoint types: ORIGIN, STOP, DESTINATION, FUEL_STOP
- Interactive Google Maps with draggable route polyline
- Drag-to-reorder waypoints, duplicate origin/destination protection
- Route lifecycle protection (delete/edit restrictions by role)
- Google Maps URL generation for driver dispatch
3. Fleet Management (Samsara)
- Vehicle and driver list from Samsara API
- Live GPS map filtered to driver-assigned vehicles only
- Connection status indicator
4. Fuel Management
- Daily fuel price uploads via Excel (Love's network, multi-network planned)
- Nearby fuel stops displayed on route maps with pricing
- Low fuel alerts via Telegram + in-app notifications
- Fuel analytics dashboard (fleet-wide + per-truck — currently mock data, real data in Phase 5)
5. Route Deviation Monitoring
- Cron-based checking every 30 seconds
- Tracks deviation start/end, max distance, location
- Telegram alerts + in-app notifications, auto-resolves on return
6. Notification System
- Types: FUEL_LOW, ROUTE_DEVIATION, ROUTE_COMPLETED
- Per-user read tracking (NotificationRead join table)
- System-level resolution (resolvedAt) separate from per-user read state
7. Reports
- 5 types: Route Summary, Route Detail, Activity Log, Deviations, Fuel Stops
- Export formats: JSON, CSV, XLSX
- Date range, status, truck, user filters
- Phase 3 (Financial Reports) pending fuel card integration
8. Settings
- Company name, Samsara API key, Telegram chat ID management
- Team management: invite, deactivate, role change, password reset
- Invite link management with status tracking
Infrastructure & Costs
| Component | Current | After Phase 1 |
|---|---|---|
| DigitalOcean droplet | $14/mo (2GB/1CPU) | ~$48/mo (8GB/4CPU) |
| Google Maps APIs | $0–50/mo | → HERE (~$5–40/mo) |
| PostgreSQL | $0 (on droplet) | $0 (on droplet) |
| Domain | ~$1/mo | ~$1/mo |
| Total | $15–65/mo | ~$55–90/mo |
Documentation Index
| Document | Purpose |
|---|---|
| Architecture | File structure, API endpoints, env vars, domain setup, deployment |
| Database Schema | ER diagram, all models, planned schema additions |
| Roles & Permissions | 6-role system, permissions matrix, fuel markup, driver portal |
| Roadmap | 10-phase infrastructure and feature roadmap with task checklists |
| Cron Setup | Production cron configuration for deviation and fuel alert monitoring |
| Deployment | GitHub Actions → ghcr.io → Coolify deployment pipeline |