Wasla Express
An operations platform for Egyptian shipping companies covering parcel intake, branch hubs, courier run-sheets, proof of delivery, COD collection and merchant settlements across six role-based app variants
- Role
- Full-stack engineering & UI design
- Timeline
- 2025 – 2026
- Platforms
- Android · iOS · Windows · Web · Server
- 6 تطبيقات
- role-based app variants
- باركود
- AWB & parcel scanning
- COD
- cash collection & settlements
- automated status updates
Overview
Business problem & context
Egyptian shipping carriers coordinate thousands of daily parcels across hubs, couriers and merchants. When operations rely on spreadsheets and manual WhatsApp threads, parcel state drifts, courier cash custody mixes with merchant balances and financial settlements stall
System Architecture
System layers & components
A single Flutter codebase compiles into six role-scoped variants (Full, Admin, Merchant, Customer, Courier, Employee) via dart-define flags and Android flavors, backed by a 230-migration Supabase/PostgreSQL core, 19 Edge Functions and a dedicated Node.js/Express WhatsApp automation server
Clients · Flutter (6 Variants)
Android, iOS, Windows & Web from one codebase
- wasla_admin (Win/Mobile)
- wasla_merchant (Win/Mobile)
- wasla_courier
- wasla_customer
- wasla_employee
- Riverpod + GoRouter
Edge & Automation Services
Server workflows & real-time messaging
- 19 Supabase Edge Functions
- Outbox Notification Sender
- wasla-whatsapp-server (Node/WS)
- Ecommerce Webhooks & Partner API
Data & Ledger Core · PostgreSQL
Multi-company RLS, hub transfers & COD ledger
- 230 Declarative Migrations
- Strict Row Level Security
- RPCs (SECURITY DEFINER)
- Signed Release Manifests (SHA-256)
Data Model
Database schema & core tables
A multi-company relational schema linking the parcel lifecycle from AWB generation through hub sorting and courier runsheets down to COD cash collection and merchant settlement
| Table | Role in the system |
|---|---|
shipments / shipment_items | Parcel record, items, customer coordinates & COD amount |
shipment_history | Immutable audit trail for every status transition |
hubs / hub_transfers | Branches, warehouses and inter-hub dispatch manifests |
runsheets / courier_location_events | Courier delivery sheets and live GPS telemetry |
financial_transactions | Courier cash custody, merchant settlements & invoices |
merchant_pricing_rules / awb_configs | Per-merchant zone pricing rules and AWB print templates |
Implementation
Key technical decisions
Single codebase, six apps via APP_VARIANT
Instead of maintaining five diverging repositories, `--dart-define=APP_VARIANT=...` and automated build scripts isolate package IDs, signing and entry routes per role while restricting Windows desktop builds to Admin and Merchant
Coupling delivery proof with financial settlement
Marking a parcel as delivered does not merely flip a status column; guarded RPCs atomically record courier cash custody and merchant receivable entries so balances never drift
Isolated WhatsApp server with rate limiting & session persistence
Offloaded WhatsApp group notifications into a standalone Node.js/Express service (`wasla-whatsapp-server`) with per-group token-bucket rate limiting and persistent session storage
SHA-256 signed release manifest center
Managed binary distribution through `wasla-app-releases` with `manifest.json` and `checksums.sha256` verified against a canonical release certificate
Security
Security & access control
- Client apps ship with the publishable key only; zero service_role keys in client code, with all access enforced by PostgreSQL RLS
- Sensitive mutations (settlements, role changes, runsheet handover) execute inside hardened RPC wrappers audited against RLS recursion
- 155 test files, SQL benchmark suites and explicit foreign-key indexes across high-frequency operational tables
Code Highlight
Per-group rate limiter & queue guard in wasla-whatsapp-server
export class GroupRateLimiter {
constructor({ windowMs = 60_000, maxPerGroup = 12 } = {}) {
this.windowMs = windowMs;
this.maxPerGroup = maxPerGroup;
this.buckets = new Map();
}
allow(groupId, now = Date.now()) {
const recent = (this.buckets.get(groupId) ?? []).filter((t) => now - t < this.windowMs);
if (recent.length >= this.maxPerGroup) return { ok: false, retryAfterMs: this.windowMs - (now - recent[0]) };
recent.push(now);
this.buckets.set(groupId, recent);
return { ok: true, remaining: this.maxPerGroup - recent.length };
}
} Product Screens
System screenshots
Web & desktop interfaces
Mobile app screens
Brand & product illustrations
Summary
Outcome & status
Live in production at `wasla-system.site`, running the full shipping lifecycle across five mobile apps, two Windows desktop apps and the web portal on top of 230 versioned database migrations