Backend Development for B2B Delivery Platform

# BlessShipping Backend MVP Development

## Project Overview

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

* Amazon sellers
* Temu sellers
* Shopify merchants
* Local wholesalers and distributors
* Depanneur and convenience store delivery networks

The objective is to build a production-ready backend capable of supporting real delivery operations, dispatch workflows, driver management, pricing, proof of delivery (POD), and ERP integration.

This project is **backend development only**.

Frontend applications (Driver App, Merchant Portal, Dispatcher Dashboard) are handled by separate teams and are not part of this scope.

---

# Primary Objective

Build a reliable, scalable, and maintainable backend capable of supporting:

* Real merchant orders
* Real dispatch operations
* Real driver workflows
* Real-time delivery status synchronization
* Pricing calculations
* Proof of delivery tracking
* ERP integration
* Production deployment

The system must be deployable on our own servers and all source code must be fully owned by the client.

---

# Preferred Technology Stack

Developers may propose the most suitable technology stack.

Examples:

* Node.js (NestJS preferred)
* FastAPI (Python)
* Laravel (PHP)
* Frappe Custom App

The architecture must support future scalability and team handoff.

---

# User Roles

The backend must support:

* Admin
* Dispatcher
* Merchant
* Driver

---

# Authentication & Authorization

Required:

* JWT Authentication
* Role-Based Access Control (RBAC)
* Secure API access
* Merchant data isolation
* Driver route isolation

---

# Merchant Management

Merchant profile management.

Required fields:

* Business information
* Contact information
* Preferred communication language
* Store availability rules
* Delivery instructions

Preferred communication language may include:

* English
* French
* Chinese
* Multiple languages

The purpose is to allow drivers and dispatchers to know which language can be used when communicating with the merchant.

---

# Store Business Availability Rules

Some stores require the owner or manager to be present before business can be conducted.

Required support:

* Owner required (Yes / No)
* Available days
* Available hours
* Preferred delivery window
* Appointment required
* Call before arrival
* Contact person
* Special instructions

Examples:

* Owner available only Thursday and Friday
* Manager available only during business hours
* Call before arrival
* Appointment required

The backend should expose these rules through APIs for dispatcher and driver applications.

---

# Driver Management

### Driver Tiers

Tier 1 – Active Driver

Tier 2 – Part-Time Driver

Tier 3 – On-Call Driver

Dispatch priority should consider driver tier.

### Driver Capacity

* Maximum parcel count
* Maximum weight
* Maximum volume

### Driver Preferred Service Areas

Drivers may select one or more preferred service areas.

Examples:

* South Shore
* Brossard
* Longueuil
* Montreal
* Laval
* West Island
* North Shore

Preferred areas should be treated as a positive dispatch scoring factor, not a hard restriction.

---

# Delivery Orders

### Order Lifecycle

Required statuses:

* CREATED
* SCHEDULED
* DISPATCHING
* OFFER_SENT
* ACCEPTED
* ARRIVED_PICKUP
* PICKED_UP
* DELIVERING
* DELIVERED
* COMPLETED
* FAILED
* CANCELLED

Status updates must be synchronized across connected systems.

---

# Customer Delivery Modes

The backend must support:

* Scheduled Delivery
* Recurring Delivery
* On-Call Delivery

Examples:

* Weekly deliveries
* Bi-weekly deliveries
* Monthly deliveries
* Customer-requested deliveries

---

# Customer Address Book

Merchants should be able to save and reuse:

* Recipients
* Addresses
* Contact information
* Delivery instructions

---

# Dispatch Engine

The dispatch engine should support:

* Driver availability
* Driver tier
* Driver preferred service areas
* Driver capacity
* Distance calculations

The architecture should allow future expansion for advanced optimization.

---

# Pricing Engine

Pricing must support:

* Base fee
* Distance fee
* Weight surcharge
* Size surcharge
* Service level surcharge
* GST
* QST

### Service Levels

* Instant Delivery
* Same Day Delivery
* Economy Delivery

### Multi-Package Pricing

Parcel #1 = 100%

Parcel #2 = 80%

Parcel #3 = 60%

Parcel #4 and above = 40%

---

# Proof of Delivery (POD)

Required:

* Delivery photo upload

Optional:

* Signature
* Failed delivery photo

Failed deliveries should support reason tracking.

---

# Driver Earnings

The backend should support:

* Base earnings
* Distance-based earnings
* Bonuses
* Manual adjustments

---

# Real-Time Infrastructure

The backend must support:

* WebSocket or equivalent real-time technology
* Dispatch updates
* Driver updates
* Delivery status updates

---

# ERP Integration Layer

ERPNext setup and administration are handled by a separate ERP team.

Backend responsibilities are limited to:

* Customer synchronization
* Invoice synchronization
* Payment synchronization
* Webhook processing
* ERP integration APIs

---

# Deployment Requirements

The system must be deployable on Ubuntu servers.

Required:

* Docker
* Docker Compose
* Environment variables
* Deployment documentation

---

# GitHub Development Requirements (Mandatory)

All development must be performed in client-owned GitHub repositories.

The selected developer or team will be added as collaborators only.

### Requirements

1. All source code must be committed directly to the client's GitHub repositories.

2. Development performed only on local machines or developer-owned repositories is not acceptable.

3. Source code must be uploaded continuously throughout development.

4. Commits must be meaningful and properly organized.

Examples:

* feat: add authentication API
* feat: implement dispatch engine
* fix: order status synchronization
* refactor: pricing calculation module

5. The client must be able to review progress at any time.

6. The client must always have access to the latest source code.

7. Pull Requests should be used when appropriate.

8. Real credentials and secrets must never be committed.

Use environment variables and `.env.example` files only.

### Required Repository Structure

/backend

/docs

### Required Documentation

* README.md
* .env.example
* API Documentation
* Database Schema Documentation
* Deployment Guide

### Source Code Ownership

The client must retain full ownership of:

* GitHub repositories
* Source code
* Documentation
* Database schema
* Deployment configurations

The developer may not withhold source code until final delivery.

Failure to continuously upload source code to the client-owned GitHub repository during development may be considered a project management failure and may affect milestone acceptance.

---

# Future Phases (Not Part of MVP)

The following are future enhancements and should not be included in the MVP estimate:

* Automated Call / SMS Notifications
* Advanced Dispatch Optimization
* Warehouse Integration
* Multi-Station Network Support
* Merchant Preferred Drivers
* Driver Block Lists
* Customer Rating System
* Driver Rating System

---

# Required With Proposal

Please provide:

* Similar logistics or dispatch projects
* Proposed architecture
* Technology stack
* Team structure
* Estimated timeline
* Weekly availability
* Deployment approach
* ERPNext integration experience
* Docker deployment experience

The priority of this project is:

* Real backend functionality
* Real delivery workflows
* Reliable dispatch operations
* Maintainable architecture
* Production-ready deployment
* Long-term scalability
* Full client ownership of source code