BlessShipping MVP — B2B Last-Mile Delivery Platform

BlessShipping MVP — B2B Last-Mile Delivery Platform
Project Overview

BlessShipping is a Montreal-based B2B last-mile delivery platform designed for:

Amazon sellers
Temu sellers
Shopify merchants
Local wholesale/distribution businesses
Depanneur/station-based delivery networks

The platform will allow merchants to upload delivery orders, dispatchers to batch and assign deliveries, and drivers to complete deliveries with proof of delivery (POD).

The MVP must prioritize:

real operational workflow
backend reliability
dispatch logic
production architecture
maintainability

UI alone is NOT sufficient.

Primary Goal

Build a deployable production-ready MVP capable of handling:

real merchant orders
real dispatch operations
real driver workflows
real delivery status synchronization
real pricing calculation
real POD tracking

The system must be deployable on our own servers and fully owned by us.

Required Tech Stack
Backend
Required
ERPNext / Frappe

Used for:

authentication
roles
customers
invoicing
accounting integration
reporting
Custom Backend Layer (Required)

A custom Frappe app OR separate Node.js backend is acceptable if properly integrated.

Must support:

dispatch engine
driver assignment
routing
real-time updates
driver earnings
POD
delivery lifecycle
pricing engine
Frontend
Merchant Portal
Next.js
Driver App
PWA or Flutter

Must support:

Android first
mobile optimized
offline tolerance
Dispatcher Dashboard
Next.js or ERPNext Workspace
Deployment Requirements
Required
Docker-based deployment

Must support:

reverse proxy
SSL
environment variables
production restart
backups
Infrastructure

Must be deployable on our own Ubuntu servers.

Deployment should support:

Cloudflare
Docker
PM2/systemd
MongoDB or MariaDB/Postgres
Required User Roles
Roles
Merchant
Dispatcher
Driver
Warehouse Staff (optional)
Admin
Core Operational Workflow (CRITICAL)

The platform must support this REAL workflow:

Merchant creates/imports orders
→ Orders stored in backend database
→ Dispatcher schedules orders
→ Dispatch engine recommends drivers
→ Driver receives real-time offer
→ Driver accepts/declines
→ Route progresses through delivery lifecycle
→ POD uploaded
→ Merchant sees completed delivery + POD
→ Billing/export generated
Core Data Model
Minimum Required Entities
Merchant
Driver
Vehicle
DeliveryOrder
DispatchRun
RouteStop
ProofOfDelivery
DriverEarnings
DispatchOffer
DispatchLog
Delivery Workflow (MANDATORY)
Order Status Lifecycle
CREATED
SCHEDULED
DISPATCHING
OFFER_SENT
ACCEPTED
ARRIVED_PICKUP
PICKED_UP
DELIVERING
DELIVERED
COMPLETED
FAILED
EXCEPTION
CANCELLED

Status synchronization must work across:

Merchant Portal
Dispatcher Dashboard
Driver App
Backend APIs
Database
Merchant Portal Requirements (Next.js)
Authentication
secure login
JWT/session auth
merchant can only see own orders
CSV Upload (REQUIRED)

Must support:

bulk CSV import

Required:

validation
error reporting
duplicate prevention
import summary
Required CSV Result Format
{
"imported_count": 120,
"failed_rows": [
{
"row": 5,
"error": "Invalid postal code"
}
]
}
Merchant Features
Orders List

Filters:

status
date
service level
delivery state
Order Detail View

Must show:

tracking status
timestamps
assigned driver
POD photo link
delivery notes
Reorder Feature

Merchant can reorder previous shipments.

Dispatcher Dashboard Requirements
Dashboard Features
Ready-to-Schedule Queue

Dispatcher sees:

new orders
scheduled orders
delayed orders
failed deliveries
DispatchRun Creation

Dispatcher can:

create batch runs
assign delivery date/time
Route Optimization

Required:

OSRM or GraphHopper integration

Dispatcher must also support:

manual stop reorder
manual override
Driver Assignment

Dispatcher must see:

driver status
vehicle type
distance to pickup
tier
acceptance rate
completion rate
current active jobs
Operational Alerts

Required alerts:

driver delayed
offer expired
no driver nearby
POD missing
waiting too long
Driver App Requirements
Authentication

Secure login required.

Driver Availability

Driver can toggle:

ONLINE
OFFLINE
BUSY
Today Route

Must show:

ordered stops
customer details
delivery instructions
earnings estimate
navigation link
Delivery Actions

Required actions:

Arrived at Pickup
Picked Up
Delivered
Failed Delivery
Proof of Delivery (MANDATORY)

Driver MUST upload:

delivery photo

Optional:

signature
failed attempt photo
Failed Delivery Flow

Driver must select reason:

customer unavailable
wrong address
unsafe location
package damaged
other
Routing & Geocoding Requirements
MVP Routing

Acceptable:

OSRM
GraphHopper
Google Maps temporarily

BUT architecture must remain replaceable.

The frontend must NOT directly depend on Google APIs.

Required Features
distance calculation
ETA
route optimization
driver-to-pickup distance
Pricing Engine (IMPORTANT)

The pricing engine must NOT use fixed mock pricing.

Pricing must support:

base fee
distance fee
service level surcharge
weight surcharge
size surcharge
peak surcharge
weather surcharge
driver shortage surcharge
GST/QST
Vehicle Recommendation Logic

Vehicle recommendation must consider:

weight
dimensions
quantity
cargo volume
special handling

NOT quantity alone.

Driver Earnings System

Driver earnings must support:

base fare
distance fee
bonuses
surge pricing
manual adjustments

Dispatcher/Admin must see:

customer paid
driver earnings
company margin
Billing Requirements
Merchant Billing

Must support:

monthly invoice export
CSV export
PDF export

Based only on:

completed deliveries
API Requirements
Merchant APIs
login
import CSV
list orders
order detail
tracking
Dispatcher APIs
create dispatch run
optimize route
assign driver
reassign driver
view live deliveries
Driver APIs
fetch route
accept/decline offer
update stop status
upload POD
update driver location
Real-Time Requirements (IMPORTANT)

The system must support real-time synchronization between:

Dispatcher
Driver
Merchant

Must support:

offer updates
status updates
delivery completion

WebSocket or equivalent preferred.

Security Requirements
Mandatory
role-based access
merchant isolation
driver route isolation
audit logs
upload validation
basic rate limiting
Logging & Audit Requirements

The system must log:

dispatch decisions
status changes
driver actions
POD uploads
pricing changes
Deliverables
Required Deliverables
Source Code

Must be uploaded to OUR GitHub repository.

Required structure:

/backend
/driver-app
/merchant-app
/dispatcher-panel
/docs
Documentation

Required:

README.md
.env.example
deployment guide
setup instructions
API documentation
database schema
backup basics
Deployment

Must deploy successfully on our server.

Required Demonstration

The team must demonstrate:

Merchant creates order
→ Backend stores order
→ Dispatcher receives order
→ Driver receives offer
→ Driver completes delivery
→ POD visible to Merchant

using REAL backend/database workflow.

Mock/demo-only systems are NOT acceptable.

Experience Requirements (STRICT)

Applicants must demonstrate REAL experience in:

ERPNext/Frappe customization
dispatch systems
last-mile delivery workflows
routing optimization
POD workflows
Next.js
PWA/mobile delivery systems
Docker deployment
production backend systems
Required With Proposal

Applicants must provide:

similar logistics projects
architecture proposal
deployment architecture
timeline
team structure
weekly availability
Required Milestone Structure
Milestone 1
Backend foundation
ERPNext setup
authentication
roles
CSV import
database schema
GitHub setup
Milestone 2
Dispatch engine
driver assignment
route optimization
status lifecycle
real backend workflow
Milestone 3
Driver workflow
POD
GPS
ETA
real-time updates
Milestone 4
Merchant tracking
billing export
deployment hardening
testing
production stabilization
Required CSV Format
merchant_reference_id
recipient_name
recipient_phone
street
city
province
postal_code
service_level
package_size
weight_kg
length_cm
width_cm
height_cm
notes
Final Note

This project is NOT a UI prototype.

The priority is:

real backend
real workflow
real dispatch logic
real operational reliability
maintainable architecture
production-ready deployment

The system must be designed for future scalability and team handoff capability.

All development must be continuously pushed to the client-owned GitHub repository during the development process.

The development team must NOT keep the source code only on local machines or private repositories.

Requirements:

1. The GitHub repository must be owned by the client.

2. The development team will be added only as collaborators/contributors.

3. Source code must be pushed continuously throughout development, not only at the final delivery stage.

4. Commits must be meaningful and properly organized.

Examples:
- feat: add dispatch offer API
- fix: driver status synchronization
- refactor: pricing engine

Avoid unclear commits such as:
- update
- final
- test

5. The repository must include:
- backend source code
- driver app source code
- merchant portal source code
- dispatcher dashboard source code
- documentation

6. Required repository structure:

/backend
/driver-app
/merchant-app
/dispatcher-panel
/docs

7. The repository must include:
- README.md
- .env.example
- setup instructions
- deployment guide
- API documentation
- database schema/models

8. Real secrets and credentials must NEVER be committed.

Examples:
- MongoDB passwords
- JWT secrets
- Google Maps keys
- Stripe keys
- SSH keys

Use .env.example files only.

9. The client must be able to:
- clone the repository
- install dependencies
- run the project locally
- deploy the project independently

10. Failure to continuously upload source code during development will be considered a project management violation.