PilotEdge — Oversize Load Resource Platform (V1 POC)

What Is This?

A proof-of-concept web application for truck drivers, carriers, and escort/pilot vehicle operators in the oversize/overdimensional freight industry.

⚠️ All regulation data shown is SIMULATED for demonstration purposes and must be verified with actual state DOT regulations before any real-world use.

Prerequisites

• Node.js v18+ (LTS recommended)
• PostgreSQL 14+
• npm (comes with Node.js)

Getting Started

1. Clone the repo

git clone <repo-url>
cd pilot-poc

2. Set up PostgreSQL

Create a database called pilotedge:

psql -U postgres -c "CREATE DATABASE pilotedge;"

3. Configure environment

Copy the example env file and update if needed:

cd server
cp .env.example .env

The default .env expects:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/pilotedge?schema=public"
JWT_SECRET="change-this-to-a-long-random-string"
PORT=3000

Update the DATABASE_URL if your PostgreSQL password or port is different.

4. Install dependencies

cd server
npm install

5. Run database migrations

npm run db:migrate

This creates all 15 tables in your PostgreSQL database via Prisma.

6. Seed the database

npm run db:seed

Populates the database with demonstration data (51 states with regulations, contacts, equipment requirements, truck stops, bridges, weigh stations, alerts, and seasonal restrictions).

7. Start the server

npm run dev

Open http://localhost:3000 in your browser.

Available Scripts

Run these from the server/ directory:

Command	Description
npm run dev	Start server with auto-reload on file changes
npm start	Start server (production)
npm run db:migrate	Apply database migrations
npm run db:seed	Seed database with demo data
npm run db:reset	Drop all data and re-run migrations
npm run db:studio	Open Prisma Studio (visual database browser)

Pages

Core

Page	URL	Description
Home	/	Platform overview and all feature modules
Regulations Map	/pages/regulations.html	Interactive US map + equipment requirements by state
Request Service	/pages/order.html	Escort vehicle service request form

Road Intelligence

Page	URL	Description
Truck Stops	/pages/truckstops.html	Oversize-friendly parking with user comments
Bridge Clearances	/pages/bridges.html	Height/width/weight restrictions for bridges
Weigh Stations	/pages/weighstations.html	Crowd-sourced open/closed status
Route & Weather	/pages/alerts.html	Construction, closures, and wind/weather alerts

Services & Resources

Page	URL	Description
Load Board	/pages/loadboard.html	Oversize load listings needing escort services
Find Escorts	/pages/locator.html	Map of available escort vehicle operators
DOT Contacts	/pages/contacts.html	State permit office phone/email directory
Seasonal Calendar	/pages/calendar.html	Seasonal restrictions and closure calendar
Document Vault	/pages/documents.html	Store permits, insurance, certifications

API Endpoints

All endpoints are prefixed with /api. Public endpoints require no authentication; protected endpoints require a Bearer token in the Authorization header.

Public

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/regulations	All states with regulations
GET	/api/regulations/:stateAbbr	Single state with equipment requirements
GET	/api/contacts	All state DOT contacts
GET	/api/calendar	All seasonal restrictions
GET	/api/truckstops?lat=&lng=&radius=	Truck stops with optional geospatial filter
GET	/api/bridges?maxHeight=&maxWidth=	Bridges with optional conflict detection
GET	/api/weighstations	Weigh stations with status
GET	/api/alerts?state=&type=	Active route and weather alerts
GET	/api/loads	Load board listings
GET	/api/escorts	Escort operator profiles

Auth

Method	Endpoint	Description
POST	/api/auth/register	Create account (email, password, name, role)
POST	/api/auth/login	Login and receive JWT token
GET	/api/auth/me	Get current user profile (protected)

Protected (requires auth)

Method	Endpoint	Description
POST	/api/loads	Post a new load
PUT	/api/loads/:id	Update own load
DELETE	/api/loads/:id	Delete own load
POST	/api/escorts/profile	Create/update escort profile
POST	/api/orders	Submit escort service request
GET	/api/orders	List own orders
POST/GET/DELETE	/api/documents	Upload, list, download, delete documents
POST	/api/contributions	Submit user contributions

Tech Stack

• Frontend: HTML, CSS, JavaScript (no build step)
• CSS: Tailwind CSS via Play CDN
• Maps: Leaflet.js via CDN
• Server: Express.js (Node.js)
• Database: PostgreSQL 16
• ORM: Prisma with auto-migrations
• Auth: JWT + bcrypt

Project Structure

pilot-poc/
├── public/                     # Frontend (served by Express)
│   ├── index.html              # Landing page
│   ├── pages/
│   │   ├── regulations.html    # State regulations map
│   │   ├── order.html          # Escort service request form
│   │   ├── loadboard.html      # Oversize load board
│   │   ├── locator.html        # Escort operator locator
│   │   ├── truckstops.html     # Oversize-friendly truck stops
│   │   ├── bridges.html        # Bridge clearance database
│   │   ├── weighstations.html  # Weigh station status
│   │   ├── alerts.html         # Route & weather alerts
│   │   ├── contacts.html       # State DOT contact directory
│   │   ├── calendar.html       # Seasonal restriction calendar
│   │   └── documents.html      # Document vault
│   └── js/
│       ├── api.js              # Frontend API client
│       ├── nav.js              # Shared navigation component
│       ├── mock-data.js        # Original mock data (preserved)
│       └── mock-data-extended.js
│
├── server/
│   ├── package.json
│   ├── .env                    # Environment config (not in git)
│   ├── .env.example            # Template for .env
│   ├── prisma/
│   │   └── schema.prisma       # Database schema (15 models)
│   └── src/
│       ├── index.js            # Express app entry point
│       ├── config/db.js        # Prisma client
│       ├── middleware/
│       │   ├── auth.js         # JWT verification
│       │   └── errorHandler.js
│       ├── routes/             # 13 API route files
│       └── seeds/seed.js       # Database seeder
│
├── PLAN.md                     # Product plan and module breakdown
└── README.md

## Next Steps
- Replace demo data with real, verified state regulation data
- Integrate payment processing for subscriptions
- Add real-time weigh station status updates (WebSockets)
- File storage service (S3) for document vault
- Email notifications for regulatory change alerts
- Deploy to a Cloud VPS (DigitalOcean, Linode, etc.)