dispatchCore

The Problem

Last-mile delivery — the final leg from a local hub to the customer's door — is the most expensive and disorganized part of any logistics chain. It accounts for over half of total shipping costs, yet most small and mid-sized courier companies still coordinate their entire operation through phone calls, WhatsApp groups, and guesswork.

The consequences are real:

• Drivers sit idle while unassigned orders pile up nearby.
• Orders get double-assigned, sending two drivers to the same pickup.
• Customers have no visibility into where their package actually is.
• Dispatchers operate blind, making decisions without real-time data.
• No performance tracking means inefficiencies go unnoticed and unresolved.

Large enterprises build internal control towers to solve this. Small businesses can't afford to. They're left with chaos.

What dispatchCore Does

dispatchCore replaces the manual, fragmented dispatch process with a single, synchronized platform where dispatchers, drivers, and customers all operate from the same real-time source of truth.

For Dispatchers

A live control dashboard where they can see every driver, every order, and every delivery status — all updating in real time. Dispatchers can assign deliveries directly to their employed drivers or list orders on a public marketplace for independent drivers to pick up. In-app messaging keeps communication centralized per-order.

For Employed Drivers

A clean, focused interface showing their assigned delivery queue, navigation, and simple status controls. Auto-refreshing dashboard keeps data in sync with dispatcher changes. They stay connected to their company's dispatch system at all times.

For Independent Drivers

A gig-economy marketplace where freelance drivers can browse available deliveries, bid on the ones that match their route, and even pre-register their upcoming travel plans so dispatchers can proactively match them with packages heading the same direction. Earnings are tracked per-delivery with daily and weekly summaries.

For Customers

A live tracking page — no login required — showing exactly where their package is and when it will arrive.

For Platform Administrators

Full oversight of the entire system, managing companies, resolving disputes, and monitoring platform-wide health.

Built for Multiple Companies

dispatchCore is a multi-tenant platform. Each delivery company that signs up gets their own isolated workspace. Company A cannot see Company B's warehouses, drivers, orders, or analytics — and vice versa.

However, independent drivers are shared across the entire platform. When any company lists a delivery on the marketplace, freelance drivers from across dispatchCore can see it and bid. Once an independent driver picks up a delivery, only that specific company's dispatchers and the end customer can track them.

A platform-level SuperAdmin has full visibility across all companies to manage the system, onboard new businesses, and resolve disputes.

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript 5.9, Vite 7, Tailwind CSS v4
Animations	Framer Motion
Maps	MapLibre GL JS + react-map-gl
Icons	Lucide React
Testing (Frontend)	Vitest, React Testing Library, Vitest UI
Backend	Node.js, Express 4
Database	MySQL (Sequelize ORM)
Real-Time	Firebase Realtime Database
Email	Resend (Transactional Email Service)
Testing (Backend)	Jest, Supertest, Custom Matchers
Security	Helmet, express-rate-limit, express-validator
CI/CD	GitHub Actions (7-stage pipeline)

Technical Architecture

Concurrent Assignment Prevention

Two dispatchers assigning the same order simultaneously would cause double-assignment. The assignment service uses Sequelize SERIALIZABLE transactions with pessimistic row locking (SELECT ... FOR UPDATE) — the second transaction blocks until the first commits, then fails with a 409 conflict rather than silently creating a duplicate assignment.

Real-Time Events via Firebase

Firebase Realtime Database powers all live updates — driver GPS pings, order status changes, assignment notifications, and marketplace bid updates. Events are written to Firebase paths like /drivers/{id}/location and /orders/{id}/status, with clients subscribing to relevant paths for instant updates.

Multi-Tenant Data Isolation

Every table in the schema chains back to company_id. A tenantResolver middleware extracts the company scope from request headers and injects it into every query — Company A cannot read or write Company B's orders, drivers, or assignments.

Who Is This For

• Local and regional courier companies
• Last-mile delivery startups
• Businesses that rely on both full-time and freelance drivers
• Any delivery operation that has outgrown spreadsheets and WhatsApp coordination

Documentation

• System Design — Architecture, database, API design, UML diagrams
• Infrastructure — Conventions, patterns, and engineering standards
• Testing Guide — Unit, integration, and component testing patterns
• Testing Quick Start — 5-minute setup guide
• CI/CD Guide — GitHub Actions pipeline architecture

Getting Started

# Backend
cd backend
cp .env.example .env
npm install
npm run db:migrate
npm run dev        # → http://localhost:8000

# Production backend runtime (Render)
npm start          # do not use npm run dev in production

# Frontend
cd frontend
npm install
npm run dev        # → http://localhost:5173

Testing

# Run all tests
cd frontend && npm run test:unit && cd ../backend && npm run test

# Frontend tests (Vitest + React Testing Library)
cd frontend && npm run test:unit              # Run once
cd frontend && npm run test:unit -- --watch   # Watch mode

# Backend tests (Jest + Supertest)
cd backend && npm run test                    # Run with coverage
cd backend && npm run test -- --watch         # Watch mode
cd backend && npm run test:unit               # Unit tests only
cd backend && npm run test:integration        # Integration tests only

Test files:

• Frontend: frontend/src/__tests__/ (14 tests - hooks + components)
• Backend: backend/src/__tests__/ (18 tests - unit + integration)
• CI/CD: .github/workflows/ci-cd.yml (7-stage automated pipeline)

Auth Model

• Primary mode: HttpOnly JWT cookies (accessToken, refreshToken).
• Fallback mode: Bearer token headers for browsers/environments that block third-party cookies.
• Frontend sends credentials: include and can transparently refresh expired access tokens.

Deployment Status

Service	Platform	Status
Frontend	Vercel	✅ Live - Auto-deploys on main branch
Backend	Render	✅ Live - Running npm start
Database	Aiven MySQL	✅ Live - Managed with backups & SSL

Production Notes

Backend (Render)

• Start Command: npm start (production mode)
• Do NOT use npm run dev on Render (nodemon is dev-only)
• Ensure FRONTEND_URL exactly matches deployed frontend origin
• Set strong JWT_ACCESS_SECRET and JWT_REFRESH_SECRET env vars
• Migrations auto-run on deployment via Render scripts
• Email: Resend is configured for transactional emails

Frontend (Vercel)

• Auto-deploys on push to main branch
• Environment variables configured in Vercel dashboard
• CDN caching enabled for optimal performance
• SSL/TLS enabled by default

Database (Aiven MySQL)

• Automated daily backups
• SSL/TLS encryption enabled
• Real-time monitoring and alerts
• Connection pooling optimized
• Failover protection active

The Vision

dispatchCore is designed to grow. The foundation being built today is architected to support future capabilities like AI-powered route optimization, demand forecasting, predictive driver scheduling, and automated dispatch — transforming it from a coordination tool into an intelligent logistics engine.