🚚 Hands On Movers - Dispatch System

A complete worker dispatch and scheduling system for Hands On Movers, designed to match jobs with available workers based on zip code zones in Aurora and Lakewood, Colorado.

Features

• ✅ Smart Zone Matching - Automatically matches jobs to workers based on Aurora/Lakewood zip codes
• ✅ SMS Notifications - Sends job offers and confirmations to workers via text message
• ✅ Real-time Dispatch - Live dashboard for managing jobs and worker assignments
• ✅ Worker Availability - Track who's available and their assigned zones
• ✅ Schedule Management - View and manage daily schedules
• ✅ API Integration - Ready for ARAYA AI integration for automated job intake

Tech Stack

• Backend: Node.js + Express
• Database: PostgreSQL
• SMS: Twilio
• Frontend: HTML5 + Vanilla JavaScript
• Hosting: Railway (backend) + Netlify (dashboard)

Service Area

Aurora Zones

• Aurora North: 80010, 80011, 80012, 80013, 80014, 80015, 80016, 80017, 80018, 80019
• Aurora South: 80044, 80045, 80046, 80047, 80247

Lakewood Zones

• Lakewood West: 80214, 80215, 80226, 80227, 80228, 80232
• Lakewood East: 80401, 80403, 80439

Quick Start

1. Clone and Install

cd /Users/tigermcbride/hands-on-dispatch
npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your credentials

3. Set Up Database

# Create PostgreSQL database
# Then run:
npm run db:setup

4. Start Development Server

npm run dev

The API will run on http://localhost:3000

5. Open Dashboard

Open admin-dashboard/index.html in your browser or serve it with:

cd admin-dashboard
npx serve .

API Endpoints

Jobs

• POST /api/jobs - Create new job
• GET /api/jobs - List all jobs
• GET /api/jobs/:id - Get single job
• PUT /api/jobs/:id - Update job

Workers

• POST /api/workers - Create worker
• GET /api/workers - List all workers
• PUT /api/workers/:id - Update worker

Dispatch

• GET /api/dispatch/match-workers/:jobId - Find best workers for job
• POST /api/dispatch/assign - Assign job to worker
• POST /api/dispatch/confirm/:assignmentId - Confirm dispatch

Schedule

• GET /api/schedule/today - Get today's schedule
• GET /api/schedule?start_date=&end_date= - Get schedule by date range

Dashboard

• GET /api/dashboard/stats - Get dashboard statistics
• GET /api/zones - Get all zones
• GET /api/zones/stats - Get zone availability stats

SMS

• POST /api/sms/webhook - Handle incoming SMS from workers
• POST /api/sms/status - SMS delivery status callback

SMS Commands (Workers)

Workers can respond to job offers via text message:

• YES or ACCEPT - Accept the job
• NO or DECLINE - Decline the job

Worker Notification Flow

1. Job Created → System finds matching workers
2. Job Assigned → SMS sent to best matching worker
3. Worker Responds → System processes YES/NO reply
4. Dispatch Confirmed → SMS sent with full job details
5. Day of Job → Reminder SMS sent 24 hours before

Database Schema

See database/schema.sql for full schema including:

• zones - Service area zones with zip codes
• workers - Worker profiles and availability
• jobs - Job details and assignments
• job_assignments - Worker-job relationship tracking
• sms_logs - SMS message history

Deployment

Deploy to Railway (Backend)

# Make sure Railway CLI is installed
railway login

# Link to your project
railway link

# Deploy
railway up

Deploy Dashboard to Netlify

# Deploy admin dashboard
cd admin-dashboard
netlify deploy --prod --dir=.

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
TWILIO_ACCOUNT_SID	Twilio account SID	Yes (for SMS)
TWILIO_AUTH_TOKEN	Twilio auth token	Yes (for SMS)
TWILIO_PHONE_NUMBER	Twilio phone number	Yes (for SMS)
DISPATCH_PHONE_NUMBER	Dispatch phone for worker questions	Yes
API_BASE_URL	Base URL for API	Yes
JWT_SECRET	Secret for authentication	Recommended

Next Steps

1. Add Twilio credentials to .env
2. Create PostgreSQL database on Railway
3. Add initial workers to the system
4. Test job creation and dispatch flow
5. Deploy to production

Support

For questions or issues, contact dispatch at the number configured in your environment variables.

---

Built for Hands On Movers 🚚💪