Realtime, by design
Every dashboard surface — KPIs, pipeline bar, needs-attention queue, live feed — subscribes to Postgres CDC. Aggregate queries debounce at 500ms; RLS scopes the channel automatically.
postgres_changes · cdcSDLS · Phase 1 · Admin Console
The handshake,
codified.
A real-time, append-only operations platform for small-to-mid logistics teams. Every parcel, every scan, every signoff — on the record. Built around a six-step Golden Path and a three-fence authorization model that holds even when one layer fails.
Live · Realtime CDC
PHASE 01Upload
PHASE 02Assign
PHASE 03Scan
PHASE 04Verify
PHASE 05Audit
500+Parcels / day
target
120kRows in postgres
~2MEvents / 8 mo.
9Security definer
RPCs
3Fences · RLS
trigger · RPC
0Client-direct
writes
02 · Canonical happy path
The Golden Path,
step by step.
Six handshakes from pickup to doorstep. Every feature has to compose with this without breaking it — the invariant the entire system defends.
- 01UploadOCR capture
- 02AssignRider routed
- 03DeliveryBarcode scan
- 04NotifyPoint-to-point
- 05CompleteUploader signs off
- 06AuditAppend-only log
03 · Capabilities
Everything the dispatch
console actually does.
What ships in Phase 1 — minus the marketing. Real subsystems backed by production code.
On-device OCR upload
Uploaders capture a printed slip with their phone camera; on-device OCR extracts customer + address fields. No data leaves the handset until the parcel is committed.
expo-camera · ml-kitBluetooth thermal labels
ESC/POS thermal printers receive the barcode the moment a parcel is created — even offline. The barcode encodes the client UUID so labels stay valid through queue replay.
esc/pos · bt 5300Riders scan, Uploaders verify
The Rider's terminal action is the scan; only the Uploader who created the parcel can mark it complete. This is the heart of the handshake — and it is hard-enforced.
point-to-point notifyThree-fence authorization
Postgres RLS, a state-machine trigger, and nine SECURITY DEFINER RPCs. Bypass any one and the other two still hold. Every override is logged in audit_events.
rls · trigger · rpcAppend-only audit
parcel_events is the source of truth; lifecycle columns on parcels are denormalized via trigger. Filters and sorts are backed by covering indexes — never JOIN events.
v_audit_log_combined04 · Invariants
Three independent fences.
Bypass one, the others hold.
The authorization model isn't a wrapper — it's three layers, each authoritative on its own. Defense in depth, expressed in SQL.
Row-Level Security
0008_rls.sqlparcels_read scopes visibility to the creator, the assignee, and admin/super_admin/verifier roles. parcels_no_update and parcels_no_delete are hard-deny — every mutation is forced through an RPC.
State-Machine Trigger
0009_transition_trigger.sqlA BEFORE INSERT on parcel_events validates the (from_status, event_kind, actor_role) tuple. AFTER INSERT updates denormalized lifecycle columns and fans out targeted notifications. Invalid transitions raise P0001.
RPC Guards
0010_rpcs.sqlNine SECURITY DEFINER functions — parcel_create, _assign, _reassign, _scan, _fail, _complete, _reopen, notification_mark_read, dashboard_kpis_today. Each starts with a caller-identity check.
05 · Who uses it
Four roles.
One source of truth.
Each role sees a different surface, all backed by the same row in parcel_events. RLS scopes what's visible; RPCs scope what's possible.
mobile
Uploader
Captures parcels via OCR, prints thermal labels, assigns to a rider, verifies the scan, and signs off completion.
mobile
Rider
Sees parcels assigned today, scans the barcode at destination. The scan is the rider's terminal action — never the closing one.
web
Admin / Super-Admin
Watches the full lifecycle, manages shops + riders + roles, resolves exceptions, generates manifests. Overrides are logged.
web
Verifier
Read-only oversight. Can view every parcel and audit row but cannot mutate state. Optional governance role.
06 · Questions
Frequently asked,
answered tersely.
01What is the Smart Delivery Logic System?
SDLS is a real-time, append-only operations platform that replaces chat-based dispatch with structured handshakes between Uploaders, Riders, and Admins. Every parcel moves through a six-step Golden Path — UPLOAD → ASSIGN → SCAN → NOTIFY → COMPLETE → AUDIT — and every transition is attributable.
02Who can mark a parcel complete?
Only the Uploader who created the parcel — never the Rider. The Rider's role is to scan; closing is a separate handshake. Admins can override, but every override is recorded.
03What happens with no internet on the field?
Scans queue locally with the client UUID baked into the barcode. On reconnect, the queue replays through the standard RPC — the state machine accepts replays and rejects duplicates idempotently.
04How is data secured?
Three independent fences — Postgres RLS, a state-machine trigger, and nine SECURITY DEFINER RPCs. Defense in depth. Bypass one, the others still hold.
05What hardware does it support?
Any iOS or Android phone with a camera (for OCR), and any ESC/POS-compatible Bluetooth thermal printer. Tested with the BT-BB 5300 series.
06What's in Phase 1 vs Phase 2?
Phase 1 ships the Golden Path, three fences, four roles, and the admin web. Phase 2 adds route optimization, customer-facing tracking, and SLA-driven auto-escalation.
07How does it scale?
Designed for 500+ parcels/day per tenant. Append-only events partition cleanly; covering indexes keep dashboard reads under 50ms at the 95th percentile through 8 months of retention.
Ready · operational
Hand the dispatch room
a console it can trust.
Sign in to the SDLS admin web. Authentication is Supabase SSR with email + password — middleware refreshes the session on every request, riders are blocked, and your role determines what surfaces you see.