VIA Platform

Mexican convoy logistics platform for coordinated cross-border trucking operations

📊 Project Status

🟢 Production46 API Endpoints45+ Pages LiveJWT AuthFastAPI + React

Live URL: via.handymanny.cloudAPI Docs: via.handymanny.cloud/api/docsProject Code: VIA Status: ✅ Fully Deployed & Live

Overview

VIA (Vigilancia Inteligente Autotransporte) is a comprehensive logistics platform for managing Mexican convoy operations, terminal coordination, and regulatory compliance. The platform coordinates cross-border trucking with real-time tracking, NOM compliance monitoring, and terminal operations gamification.

Key Features

Convoy Formation - Build and manage truck convoys with real-time capacity tracking
Route Planning - Optimized routing with NOM-033 compliance and speed enforcement
Hazmat Management - Safety-critical hazmat routing with permit tracking
Terminal Operations - Gamified crane operations with scoring and leaderboards
Transit Tracking - Real-time convoy position monitoring on GDL→MZO routes
Regulatory Compliance - NOM-012, NOM-033, SCT checkpoint integration
Regulator Yard Management - Patio registry with 327 parsed locations

Technology Stack

Backend

FastAPI - High-performance Python API framework
PostgreSQL + TimescaleDB - Time-series optimized database
asyncpg - Async database driver
JWT Authentication - Secure token-based auth with /api/auth/verify endpoint
Pydantic - Data validation and serialization

Frontend

React (planned migration) - Currently HTML mockups
VIA GREEN Design System - Complete brand compliance
Responsive UI - Mobile-first design
Real-time Updates - WebSocket support planned

Infrastructure

Docker Compose - 3-container architecture
nginx - Static file serving + reverse proxy
Traefik - SSL termination and routing
Git - Version control with deployment commits

Architecture

Docker Services

yaml

services:
  nginx:        # Frontend server
  api:          # FastAPI backend (via-plan-api)
  postgres:     # TimescaleDB (via-postgres)

Networks:

internal - Backend communication
root_default - External access via Traefik

API Structure

46 Endpoints Organized By Domain:

Authentication (3 endpoints) - Login, logout, token verification
Convoy Formation (8 endpoints) - Create, manage, track convoys
Trucks (7 endpoints) - CRUD operations for truck fleet
Drivers (7 endpoints) - Driver management and assignment
Terminals (6 endpoints) - Terminal registry and operations
Patios (6 endpoints) - Regulator yard management
Companies (5 endpoints) - Company/operator registry
Users (4 endpoints) - User account management

Swagger Documentation: Live at /api/docs

Features & Pages (45 Live)

Mobile Operations (8 pages)

Dashboard - Driver dashboard with active convoy info
Convoy Queue - Real-time queue status at concentrators
Truck Status - Individual truck tracking
Documents - Digital document management
Alerts - Real-time notifications
Profile - Driver profile and credentials
History - Trip history and records
Support - Help and support tickets

Operations Center (14 pages)

Main Dashboard - Overview of all operations
Convoy Planner v2 - Advanced convoy formation tool
Cuauhtémoc Station - Convoy building concentrador
Convoy Transit Map - Linear GDL→MZO route visualization
Terminal Crane Operations - Gamified terminal ops
Terminal Stacking - Container yard management
Speed Enforcement - NOM-012 compliance monitoring
Hazmat Planner - NOM-033 hazmat route planning
Manzanillo Map - Port operations overview
Contecon Terminal - Specific terminal operations
Patio Registry - Regulator yard database
Route Monitor - Active route tracking
Analytics - Performance metrics
Reports - Operational reporting

Support & Admin (8 pages)

User Management - Account administration
Company Registry - Operator database
Truck Fleet - Fleet management
Driver Registry - Driver database
Terminal Registry - Terminal directory
System Settings - Configuration
Audit Logs - Activity tracking
API Documentation - Swagger UI

Specialized Modules (5 deployed, 10 planned)

✅ Completed Modules:

Regulator Yards - Patio registry with bulk import (327 locations)
Convoy Planner v2 - Enhanced convoy formation
Speed Enforcement - NOM-012 compliance tracking
NOM Compliance - Multi-regulation monitoring
Hazmat Route Planner - Safety-critical routing with 8 restriction zones

🚧 Remaining Modules: 6. Scoring System - Performance gamification 7. Yard Mandate - Government patio requirements 8. Govt Admin - Government oversight portal 9. 14-Step Integration - Complete logistics workflow 10. Dual Highway - Multi-route optimization

Authentication

Login Credentials:

Email: chavez684@gmail.com
Password: Password789!

Auth Flow:

POST /api/auth/login - Returns JWT access token
Include token in Authorization: Bearer {token} header
nginx validates token via /api/auth/verify endpoint
Protected routes require valid JWT

Token Expiration: 24 hours Refresh: Manual re-authentication required

Database Schema

Core Tables

trucks

id (PK), license_plate, model, year, capacity_kg, company_id
status (available, in_transit, maintenance, unavailable)

drivers

id (PK), name, license_number, phone, company_id
status (available, assigned, off_duty)

convoys

id (PK), name, status, origin, destination, departure_time
lead_truck_id, formation_type, total_trucks

terminals

id (PK), name, code, location, capacity, operational_hours

patios (327 records)

id (PK), name, address, lat, lng, capacity, company_name

companies

id (PK), name, rfc, address, contact_info

users

id (PK), email, hashed_password, role, company_id

Design System: VIA GREEN

Brand Colors

Primary Green: #10b981 (emerald-500)
Dark Green: #059669 (emerald-600)
Light Green: #d1fae5 (emerald-100)
Accent: #fbbf24 (amber-400)
Text: #1f2937 (gray-800)
Background: #f9fafb (gray-50)

Typography

Headings: Inter, system-ui
Body: Inter, system-ui
Monospace: Menlo, Monaco, Courier New

Design Principles

Safety-critical information uses high contrast
Status indicators with color + icon redundancy
Mobile-first responsive design
Accessibility: WCAG 2.1 AA compliance

Deployment

Local Development

bash

cd ~/Downloads/via-plan-deploy
docker compose up -d

Access:

Frontend: http://localhost:8080
API: http://localhost:8000
API Docs: http://localhost:8000/api/docs

Production Deployment

Command:

bash

bash ~/Downloads/via-plan-deploy/deploy-windows.sh app

Deploy Script Features:

✅ Builds Docker images
✅ Syncs files to VPS via SCP
✅ Restarts containers with zero downtime
✅ Verifies health checks
✅ Creates git commit

VPS Location: /root/via-plan on srv1139900

Container Health

bash

# Check status
ssh root@srv1139900.hstgr.cloud "docker ps | grep via"

# View logs
ssh root@srv1139900.hstgr.cloud "docker logs via-plan-api"

Development History

Recent Milestones

2026-02-28 - ✅ FULLY DEPLOYED & LIVE

Full-stack deployment completed
46 FastAPI endpoints operational
JWT authentication with nginx verification
PostgreSQL + asyncpg async database
30 organized frontend pages deployed
All Docker containers healthy

2026-02-27 - Convoy Lifecycle Tracking

Created convoy transit map with real-time positions
Deployed terminal crane operations (gamified)
Built Cuauhtémoc station concentrador page
3 new pages, 41 total live

2026-02-27 - Hazmat Route Planner (Module 5/10)

NOM-033 compliance for hazmat routing
8 restriction zones mapped
Permit tracking system
Real-time active routes monitoring
5 tabs: Planificador, Restricciones, Permisos, Rutas Activas, Checkpoints SCT

2026-02-26 - Patio Registry v2.1

Bulk import with JSON paste/upload
Parsed 327 patios from KMZ
Duplicate detection
Merge preview

Deployment Commits:

7a2e028 - Deployment fixes + auth verify endpoint
93bc6c9 - Windows deploy script
1d41576 - Database migration

Testing

API Testing (Swagger)

Visit via.handymanny.cloud/api/docs

Test Checklist:

✅ Login endpoint (POST /api/auth/login)
✅ Get convoy list (GET /api/convoys)
✅ Create convoy (POST /api/convoys)
✅ Truck CRUD operations
✅ Driver assignment
✅ Terminal operations
✅ Patio registry

Frontend Testing

Navigate to via.handymanny.cloud
Login with test credentials
Test convoy formation workflow
Verify real-time updates
Check mobile responsiveness

Future Enhancements

Planned Features

Q1 2026:

[ ] Complete remaining 5 business modules
[ ] React migration for all pages
[ ] WebSocket real-time updates
[ ] Mobile app (Flutter)

Q2 2026:

[ ] GPS integration for real-time tracking
[ ] AI-powered route optimization
[ ] Predictive maintenance alerts
[ ] Multi-language support (EN/ES)

Q3 2026:

[ ] Government integration APIs
[ ] Blockchain for document verification
[ ] Advanced analytics dashboard
[ ] Customer portal

Documentation

API Reference - 46 endpoints with schemas
Database Schema - Complete database documentation
Deployment Guide - Step-by-step deployment
Changelog - Recent changes

Support & Resources

Authentication Issues:

Clear browser cookies
Verify JWT token not expired
Check nginx logs for auth verification

Deployment Issues:

Verify Docker containers running: docker ps | grep via
Check logs: docker logs via-plan-api
Restart services: docker compose restart

Development:

Local API: http://localhost:8000/api/docs
Database: PostgreSQL on port 5432
Hot reload: enabled in development mode

Quick Reference

Resource	URL
Live Site	https://via.handymanny.cloud
API Docs	https://via.handymanny.cloud/api/docs
Login	chavez684@gmail.com / Password789!
VPS	srv1139900.hstgr.cloud
Deploy Path	/root/via-plan
Local Path	~/Downloads/via-plan-deploy

Project Status: ✅ Production Ready Last Deployment: 2026-02-28 Next Milestone: Complete Module 6 (Scoring System) Maintained By: HandyManny Development Team

Codebase Statistics

Python: 29 files (FastAPI backend)
HTML: 83 files (Frontend pages + mockups)
CSS: 1 file (Global styles)
SQL: 2 files (Migrations)
Markdown: 57 files (Documentation)

Total Lines of Code: ~25,000+ API Endpoints: 46 Database Tables: 12 Live Pages: 45+

VIA Platform ​

📊 Project Status ​

Overview ​

Key Features ​

Technology Stack ​

Backend ​

Frontend ​

Infrastructure ​

Architecture ​

Docker Services ​

API Structure ​

Features & Pages (45 Live) ​

Mobile Operations (8 pages) ​

Operations Center (14 pages) ​

Support & Admin (8 pages) ​

Specialized Modules (5 deployed, 10 planned) ​

Authentication ​

Database Schema ​

Core Tables ​

Design System: VIA GREEN ​

Brand Colors ​

Typography ​

Design Principles ​

Deployment ​

Local Development ​

Production Deployment ​

Container Health ​

Development History ​

Recent Milestones ​

Testing ​

API Testing (Swagger) ​

Frontend Testing ​

Future Enhancements ​

Planned Features ​

Documentation ​

Support & Resources ​

Quick Reference ​

Codebase Statistics ​

VIA Platform

📊 Project Status

Overview

Key Features

Technology Stack

Backend

Frontend

Infrastructure

Architecture

Docker Services

API Structure

Features & Pages (45 Live)

Mobile Operations (8 pages)

Operations Center (14 pages)

Support & Admin (8 pages)

Specialized Modules (5 deployed, 10 planned)

Authentication

Database Schema

Core Tables

Design System: VIA GREEN

Brand Colors

Typography

Design Principles

Deployment

Local Development

Production Deployment

Container Health

Development History

Recent Milestones

Testing

API Testing (Swagger)

Frontend Testing

Future Enhancements

Planned Features

Documentation

Support & Resources

Quick Reference

Codebase Statistics