Build a delivery tracking app.
Shell, client, server, advanced.
A complete delivery tracking app in four stages. Start with a static three-view shell — a public customer tracking page, a mobile courier event view, and a dispatcher dashboard with a map and active table. Add a client-side state machine, derived delivery status from an event log, and localStorage. Move to Flask + SQLite with five tables: customers, couriers, deliveries, delivery_events, and a derived delivery_legs cache. Then grow: proof of delivery, failed-delivery workflow, bulk dispatch, live map polling, and reports. The same four-stage arc as the CRM, Inventory, POS, and HR builds — shell, client logic, backend, advanced data layer. Each stage adds exactly one layer and stops.
What you end up with: a working delivery tracking system — customer-facing public tracking pages, a mobile courier view for logging delivery events, and a dispatcher dashboard for assigning couriers and monitoring active deliveries. A Flask + SQLite backend with five tables and an atomic event-log write that updates delivery status, refreshes the current delivery leg, and enforces the state machine. Proof-of-delivery evidence, failed-delivery handling, bulk dispatch, and daily reports. Runs on your laptop with three commands.
What it is not: real-time WebSocket updates, offline sync for couriers, real map tile integration, or a production-grade notification service. Those are separate concept courses, not Stage 05.
The four stages
Each stage adds exactly one layer. Stage 04 is the last one.
The static shell. Three audiences, three layouts: a public customer tracking page (centered card, tracking code input, event timeline), a mobile courier event view (delivery detail card, one big primary action button, two smaller secondary actions), and a dispatcher dashboard (4 KPI cards, map placeholder, active-deliveries table). One shared design system. No data, no logic, no timers.
Make it work. The customer tracking page derives its timeline from an event log. The courier view logs events that change the delivery's state — the state machine (pending → assigned → picked_up → in_transit → out_for_delivery → delivered) is enforced client-side. The dispatcher can assign a courier. Tapping "delivered" twice does not create two events. Everything persists in localStorage.
Give it a server. Flask + SQLite. Five tables — customers, couriers, deliveries, delivery_events (append-only), delivery_legs (derived cache) — with three foreign keys. The core lesson: atomic event recording. A single POST appends the event, updates the delivery status, and refreshes the current leg, all in one transaction. The state machine is enforced at the API. A public tracking endpoint serves the customer page without auth, returning only the necessary fields.
Make it a real system. Proof of delivery — a separate proof_of_delivery table with photo, signature, or OTP evidence, one row per completed delivery. Failed-delivery workflow — a delivery that fails can be retried without becoming a new delivery. Bulk dispatch — assign 20 deliveries to a courier in one transaction. Live map polling — the dispatcher dashboard refreshes every 30 seconds. Customer notification queue — a stub table, not sent, but the pattern is real. Reports — deliveries per courier per day, average delivery time, failure rate. This is the final stage.
The data model
Five tables, three foreign keys, one event log.
customers who ordered it ├── id ├── name ├── email UNIQUE ├── phone └── created_at couriers who delivers it ├── id ├── name ├── phone ├── vehicle 'bike' | 'car' | 'van' └── status 'available' | 'on_delivery' | 'off_duty' deliveries the parcel ├── id ├── tracking_code UNIQUE (public key, e.g. DEL-8F3A2B) ├── customer_id FK to customers ├── courier_id FK to couriers (nullable until assigned) ├── origin ├── destination ├── status 'pending' | 'assigned' | 'picked_up' │ | 'in_transit' | 'out_for_delivery' │ | 'delivered' | 'failed' | 'cancelled' ├── priority 'standard' | 'express' ├── created_at └── updated_at delivery_events append-only log of what happened ├── id ├── delivery_id FK to deliveries ON DELETE CASCADE ├── type 'assigned' | 'picked_up' | 'arrived_at_facility' │ | 'out_for_delivery' | 'delivered' | 'failed' │ | 'gps_ping' | 'note' ├── location (lat,lng or address string) ├── note ├── occurred_at ISO timestamp ├── created_at └── created_by 'courier:42' | 'dispatcher' | 'system' delivery_legs derived cache of the current journey ├── id ├── delivery_id FK to deliveries ON DELETE CASCADE ├── leg_index INTEGER (0 = pickup leg, 1 = transit, ...) ├── from_location ├── to_location ├── started_at ├── ended_at NULL while the leg is current └── status 'active' | 'completed' | 'failed' (Stage 04 adds proof_of_delivery as the sixth table)
Why the event log
A delivery is a sequence of facts: picked up at 9:14, out for delivery at 14:05, delivered at 15:47. Each fact has a timestamp. Editing them destroys the history. The event log preserves it.
Why delivery_legs exists
It's a cache. Walking every event for every delivery on every page load is slow. One row per leg answers "where is it in its journey" in one query. Same trade-off as shifts in HR.
Why CASCADE, not RESTRICT
An event has no meaning without its delivery. Delete the delivery, the event log goes too. This is the opposite of HR's payroll events, which must survive employee deletion.
Why tracking_code is separate
The customer uses it without login. It can be human-readable (DEL-8F3A2B) while the internal id stays an integer. The code doesn't leak volume (the "4,728th delivery").
The three audiences
Customer, courier, dispatcher. One design system.
Customer
Public. Not logged in. Tracking on a phone. The page has one job: show where the parcel is, in plain English. No navigation, no settings, no sidebar.
Courier
In a car, on a phone, often one-handed. The primary action is one unmissable button: "I delivered this." The event log is a tap, not a form.
Dispatcher
At a desk. Manages 50 deliveries at once. Needs a map, a table, and the ability to assign a courier in two clicks. Information-dense by design.
Why three layouts
A single layout that serves all three is a compromise. The customer sees noise. The courier sees too many buttons. The dispatcher loses the density they need.
What you build, stage by stage
A concrete picture of the app at each point.
pending to assigned. Everything persists in localStorage.delivery_legs cache updates atomically with each event. The public tracking endpoint returns the timeline without auth. The state machine is enforced at the API — you can't jump from pending to delivered. Concurrent event recordings are deduplicated.Downloads
Available as each stage ships. Full files are delivered separately from lesson pages.
Related tracks — not part of this build
Where to go after Stage 04.
The Delivery Tracking build is four stages and it will be complete. Real-time WebSocket updates, offline sync for couriers, real map tile integration, and production-grade notification services are separate concept courses. They apply to any delivery app, not just this one.
Build something new
The four-stage arc is a template. Shell, client logic, backend, advanced data layer works for any app that tracks state transitions under partial failure:
Same four stages. Same event-log discipline. Same state machine pattern. The pattern is the reusable thing.