Delivery Tracking Build

4 Stages · Flask + SQLite + JavaScript

Home › Apps › Delivery Tracking
4 stages · ~13–15 hours · In progress

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.

~13–15 hours Intermediate HTML · CSS · JavaScript · Python · Flask · SQLite 4 stages

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.

🚚
Stage 01 · CURRENT
Interface
In progress

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.

2–3 hours · HTML · CSS
⚡
Stage 02 · Upcoming
Interactions
Planned

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.

3–4 hours · JavaScript · DOM · localStorage · state machine
🐍
Stage 03 · Upcoming
Backend
Planned

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.

3–4 hours · Python · Flask · SQLite · event log · state machine
📊
Stage 04 · FINAL (Upcoming)
Advanced
Planned

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.

3–4 hours · SQL · Flask · reports · workflow

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.

After Stage 01
A three-view shell. Customer sees a centered card with a code input and a sample timeline — nothing works. Courier sees a delivery card with three big buttons that do nothing. Dispatcher sees KPIs, a map placeholder, and a hardcoded table. The tab toggles between views.
After Stage 02
The shell is alive. Enter a tracking code → the timeline derives from the event log. Courier logs an event → the delivery's status changes, and the state machine rejects invalid transitions. Dispatcher assigns a courier → the delivery moves from pending to assigned. Everything persists in localStorage.
After Stage 03
The same UI, now talking to Flask. Events persist in SQLite. The 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.
After Stage 04 — complete
The full system. Proof of delivery with photo or OTP. Failed deliveries that can be retried without becoming new deliveries. Bulk dispatch. Live map polling. A notification queue stub. Daily reports: deliveries per courier, average delivery time, failure rate. The build is finished.

Downloads

Available as each stage ships. Full files are delivered separately from lesson pages.

Stage demos
Stage 01 — interface demo
Coming with the next delivery.
Stage 02 — interactions demo
Coming with the Stage 02 delivery.
Stage 03 — backend frontend + source
Coming with the Stage 03 delivery.
Stage 04 — advanced frontend + source
Coming with the Stage 04 delivery.

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:

Delivery tracking
this build
Field service
technicians, jobs, on-site events (event log)
Ticketing
issues, transitions, resolution (state machine)
Order fulfilment
orders, packs, shipments (state machine)

Same four stages. Same event-log discipline. Same state machine pattern. The pattern is the reusable thing.

← Back to Apps
Delivery Tracking Build · 4 Stages · In progress