PilotEdge/README.md

# 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](https://nodejs.org/) v18+ (LTS recommended)
- [PostgreSQL](https://www.postgresql.org/) 14+
- npm (comes with Node.js)

## Getting Started

### 1. Clone the repo

```bash
git clone <repo-url>
cd pilot-poc
```

### 2. Set up PostgreSQL

Create a database called `pilotedge`:

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

### 3. Configure environment

Copy the example env file and update if needed:

```bash
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

```bash
cd server
npm install
```

### 5. Run database migrations

```bash
npm run db:migrate
```

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

### 6. Seed the database

```bash
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

```bash
npm run dev
```

Open [http://localhost:3000](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](https://tailwindcss.com/) via Play CDN
- **Maps:** [Leaflet.js](https://leafletjs.com/) via CDN
- **Server:** [Express.js](https://expressjs.com/) (Node.js)
- **Database:** [PostgreSQL](https://www.postgresql.org/) 16
- **ORM:** [Prisma](https://www.prisma.io/) 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.)