SupplyWaveSA
Live Now: https://supplywave-snowy.vercel.app Run it instantly — no setup needed. Free-tier hosted build by Kirov Dynamics.
SupplyWave B2B Supply Chain & Logistics OS 📦🌍
[](https://github.com/Raphasha27/SupplyWaveSA/actions/workflows/ci.yml)
[](http://makeapullrequest.com)
[](https://opensource.org/licenses/MIT)
[](https://flutter.dev)
[](https://fastapi.tiangolo.com)
[](https://react.dev)
**A comprehensive, native-first autonomous B2B supply chain cost-optimization & logistics mesh.**
*Real-time shipment tracking · Automated procurement · ML-powered inventory forecasting · SLA compliance*
[🚀 Quick Start](#-quick-start) · [🗺️ Architecture](#️-architecture) · [📋 Features](#-feature-matrix) · [🤝 Contributing](/SupplyWaveSA/CONTRIBUTING.md)
🌍 Overview
SupplyWave is a complete, end-to-end B2B supply chain operating system built for modern logistics networks. It connects Suppliers, Logistics Providers, Warehouse Managers, and Customers through a efficient, real-time dispatch and shipment tracking mesh — supporting a diverse fleet from light electric delivery scooters to multi-ton cargo containers.
Designed web and mobile native, backed by a FastAPI + Socket.IO production mesh, and monitored via a React-powered Admin Command Center with God-View cost intelligence and AI-driven risk mitigation.
🏗️ System Architecture
┌─────────────────────────────────────────────────────────┐
│ SupplyWave Ecosystem │
│ ├──────────────┬──────────────────┬───────────────────────┤
│ │Supplier Portal│ Logistics Driver │ Admin Command │
│ │ (React Web) │ (Flutter App) │ (React + Vite) │
│ │ Stateful │ Riverpod Mobile │ Leaflet maps │
│ └──────┬───────┴────────┬─────────┴───────────┬───────────┘
│ │ │ │
│ └────────────────┼─────────────────────┘
│ │ Socket.IO (V2 Mesh)
│ ▼
│ ┌─────────────────────────┐
│ │ FastAPI V2 Backend │
│ │ Port 8000 │
│ ├─────────────────────────┤
│ │ GeoEngine (Redis) │
│ │ RoutingEngine (TSP) │
│ │ JWT RBAC Auth │
│ │ SQLAlchemy ORM │
│ └─────────┬───────────────┘
│ │
│ ┌─────────▼───────────────┐
│ │ PostgreSQL + Redis │
│ │ (Shipments, Inventory) │
│ └─────────────────────────┘
💎 Feature Matrix
| Version | Feature | Status |
|---|---|---|
| V1–V3 | Real-time shipment tracking mesh & geospatial matching | ✅ |
| V4–V5 | Route optimization & persistent SQL database integration | ✅ |
| V6 | In-app bidirectional chat between warehouses & carriers | ✅ |
| V7 | Ledger & atomic transaction wallet for shipping settlements | ✅ |
| V8 | Multi-role JWT Role-Based Access Control (RBAC) | ✅ |
| V9 | Fleet analytics & admin telemetry | ✅ |
| V10 | SOS emergency protocol & immediate exception hijack | ✅ |
| V11 | Multi-modal fleet: Scooter, Small, 7-Seater, Heavy Van | ✅ |
| V12 | Animated real-time vehicle/delivery tracking | ✅ |
| V13 | Demand heatmap overlays & warehouse surge indicators | ✅ |
| V14 | VoIP call signaling with pulsing communications screen | ✅ |
| V15 | Predictive demand forecasting & inventory optimization (ML simulation) | ✅ |
| V16 | Glassmorphism UI & premium dark-mode console styling | ✅ |
| V17 | Proximity spotlighting for warehouse arriving zones | ✅ |
| V18 | PostGIS spatial geometry migration | 🔜 |
| V19 | Full WebRTC carrier voice calls | 🔜 |
| V20 | Driver/Carrier KYC verification pipeline | 🔜 |
| V21 | FCM push notifications for order statuses | 🔜 |
🗂️ Project Structure
SupplyWaveSA/
├── backend/
│ ├── app/ # 🚀 Core API Backend
│ │ ├── api/ # REST Routers & Sockets
│ │ ├── core/ # Redis client, Event Bus, Config
│ │ ├── db/ # Database session management
│ │ ├── models/ # SQLAlchemy Data Models (Trip, User, AuditLog)
│ │ └── services/ # MatchingService, Dispatch, Rate-limiting
│ ├── logiwave/ # Autonomous Logistics Engine
│ └── v2_production/ # FastAPI Production entry points
│
├── frontend/
│ └── apps/
│ ├── admin/ # 🖥️ SupplyWave Cost Intelligence (React + Vite)
│ ├── passenger/ # 🧑 Supplier Portal Web Client (React)
│ └── driver/ # 🚗 Logistics Carrier Terminal (React)
│
└── .github/
└── workflows/ci.yml # CI/CD Pipeline
🚀 Quick Start
Prerequisites
- Python 3.11+
- Node.js 20+
- Flutter 3.x
- Redis (local or Docker)
1. Start the Production Backend
cd backend/app
pip install -r ../requirements.txt
uvicorn main:app --reload
2. Start the Admin Dashboard
cd frontend/apps/admin
npm install
npm run dev
3. Simulate 100 Active Carriers
cd backend/v2_production
python simulation/stress_test_100.py
🚗 Vehicle Fleet & Shipping Fees
| Class | Vehicle | Fee Multiplier | Use Case |
|---|---|---|---|
| 🛵 Scooter | Electric Scooter | 0.6× | Documents, small parcels, rapid dispatch |
| 🚗 Small | Light Delivery Vehicle | 1.0× | Standard urban freight |
| 🚙 Medium | XL / Multi-tier Van | 1.5× | Multi-pallet delivery, heavy parcels |
| 🚐 Heavy | 8-Ton Cargo Truck | 2.2× | Bulk warehouse transport |
Base Shipping Formula: base_rate + (distance_rate × km) + (weight_rate × kg) × vehicle_multiplier
🤝 Contributing & Community
Join our global network of developers and supply chain logistics engineers! We appreciate contributions of all shapes and sizes.
- Found a Bug? Open an issue with a reproducible description.
- Want to Add a Feature? See our CONTRIBUTING.md to get started on the PR pipeline.
- Documentation: Help us translate and refine the logistics user guide!
❤️ Sponsors & Backing
Sponsorships support continuous integration testing, API sandbox servers, and active swarm research. Join our awesome backers!
- GitHub Sponsors: Become a Sponsor
- OpenCollective: Support SupplyWave
MIT © 2026 Raphasha27 / SupplyWave SA
Contributors
«««< Updated upstream This project is developed and maintained together with the team:
- Raphasha27 — Project lead & maintainer
-
DkMash — Teammate
Stashed changes