Meet the Package Tracker: Plan It, Build It
The second pass starts with Lakeside Parcel's package tracker: what it does, its class diagram and the sequence diagram of its main call, version 1 in five languages, and the list of what's likely to change, which turns into this pass's problems.
Apprentice · OOP · Software Development · Updated
After this lesson you can
- Plan an app's first version with a class diagram and a sequence diagram of its main call
- List what's likely to change in an app, and say where each change would land in version 1's code
Key takeaways
- Plan with two pictures: a class diagram for what exists (packages, the tracker, the scanner, a route) and a sequence diagram for the call that matters most.
- Version 1 only has to work: a package's status is a word, and a route is a list of streets.
- Asking "what's likely to change?" before the requests arrive tells you which parts to keep easy to find.
- In this pass the changes are bigger than the bakery's: rules that depend on status, routes stored new ways, more carriers, shipments with many parts, and undo.
Before this: Meet the Bakery App: Plan It, Build It (Pass 1), and the two sequence-diagram lessons right before this one.
Pass 1's bakery was a small app with small change requests. Real apps grow: they get statuses with rules, data stored in new ways, partners who each do things differently, and people who need to undo a mistake. This pass follows one such app from the start. As with the bakery, the first job is to plan it, build a version that works, and ask the question every pass starts with: what's likely to change?
What the app does
Lakeside Parcel delivers packages around town. Version 1 does three things:
- It keeps track of each package: its number (such as 42), who it's for (Maya), and its status, the word that says where it is (
orderedat first). - When the depot worker scans a package onto a truck, its status becomes
shipped, and the scanner showsPackage 42: shipped. - It shows driver Dana her route for the day: Maple St, Oak Ave, Pine Rd, Cedar Ln.
Plan it: what exists
The nouns in that story are the classes: a package, the tracker that holds every package, the scanner at the depot, and a route. As a class diagram:

The scanner uses the tracker; the tracker holds any number of packages; the route stands on its own, because version 1's route is a list the driver's app reads.
Plan it: what happens
The call that matters most is the scan. You drew it two lessons ago; here it is again in Mermaid's text form, so it can live beside the code:
sequenceDiagram
actor Worker as depot worker
participant Scanner
participant Tracker
participant P42 as Package 42
Worker->>Scanner: read(42)
Scanner->>Tracker: scanned(42)
Tracker->>P42: ship()
P42-->>Tracker: done
Tracker-->>Scanner: Package 42: shipped
Two pictures, five minutes. Together they say what exists and what happens, which is most of what anyone needs to know before reading the code.
Build version 1
Tracker tracker = new Tracker();
tracker.Add(new Package(42, "Maya"));
tracker.Add(new Package(43, "Sam"));
foreach (Package parcel in tracker.All())
{
Console.WriteLine( quot;Package {parcel.Id} for {parcel.Recipient}: {parcel.Status}");
}
Scanner scanner = new Scanner(tracker);
scanner.Read(42);
Route route = new Route("Dana", new List<string> { "Maple St", "Oak Ave", "Pine Rd", "Cedar Ln" });
Console.WriteLine( quot;{route.Driver}'s route: {string.Join(", ", route.Stops)}");
class Package
{
public int Id { get; }
public string Recipient { get; }
public string Status { get; private set; } = "ordered";
public Package(int id, string recipient) { Id = id; Recipient = recipient; }
public void Ship() { Status = "shipped"; }
}
class Tracker
{
private readonly Dictionary<int, Package> packages = new Dictionary<int, Package>();
public void Add(Package parcel) { packages[parcel.Id] = parcel; }
public List<Package> All() => packages.Values.ToList();
public string Scanned(int id)
{
Package parcel = packages[id];
parcel.Ship();
return quot;Package {id}: {parcel.Status}";
}
}
class Scanner
{
private readonly Tracker tracker;
public Scanner(Tracker tracker) { this.tracker = tracker; }
public void Read(int id) => Console.WriteLine( quot;Scanner shows: {tracker.Scanned(id)}");
}
class Route
{
public string Driver { get; }
public List<string> Stops { get; }
public Route(string driver, List<string> stops) { Driver = driver; Stops = stops; }
}
Package 42 for Maya: ordered
Package 43 for Sam: ordered
Scanner shows: Package 42: shipped
Dana's route: Maple St, Oak Ave, Pine Rd, Cedar Ln
class Package {
int id;
String recipient;
String status = "ordered";
Package(int id, String recipient) { this.id = id; this.recipient = recipient; }
void ship() { status = "shipped"; }
}
class Tracker {
Map<Integer, Package> packages = new LinkedHashMap<>();
void add(Package parcel) { packages.put(parcel.id, parcel); }
List<Package> all() { return new ArrayList<>(packages.values()); }
String scanned(int id) {
Package parcel = packages.get(id);
parcel.ship();
return "Package " + id + ": " + parcel.status;
}
}
class Scanner {
Tracker tracker;
Scanner(Tracker tracker) { this.tracker = tracker; }
void read(int id) { IO.println("Scanner shows: " + tracker.scanned(id)); }
}
class Route {
String driver;
List<String> stops;
Route(String driver, List<String> stops) { this.driver = driver; this.stops = stops; }
}
void main() {
Tracker tracker = new Tracker();
tracker.add(new Package(42, "Maya"));
tracker.add(new Package(43, "Sam"));
for (Package parcel : tracker.all()) {
IO.println("Package " + parcel.id + " for " + parcel.recipient + ": " + parcel.status);
}
Scanner scanner = new Scanner(tracker);
scanner.read(42);
Route route = new Route("Dana", List.of("Maple St", "Oak Ave", "Pine Rd", "Cedar Ln"));
IO.println(route.driver + "'s route: " + String.join(", ", route.stops));
}
Package 42 for Maya: ordered
Package 43 for Sam: ordered
Scanner shows: Package 42: shipped
Dana's route: Maple St, Oak Ave, Pine Rd, Cedar Ln
class Package:
def __init__(self, id, recipient):
self.id = id
self.recipient = recipient
self.status = "ordered"
def ship(self):
self.status = "shipped"
class Tracker:
def __init__(self):
self.packages = {}
def add(self, parcel):
self.packages[parcel.id] = parcel
def all(self):
return list(self.packages.values())
def scanned(self, id):
parcel = self.packages[id]
parcel.ship()
return f"Package {id}: {parcel.status}"
class Scanner:
def __init__(self, tracker):
self.tracker = tracker
def read(self, id):
print(f"Scanner shows: {self.tracker.scanned(id)}")
class Route:
def __init__(self, driver, stops):
self.driver = driver
self.stops = stops
tracker = Tracker()
tracker.add(Package(42, "Maya"))
tracker.add(Package(43, "Sam"))
for parcel in tracker.all():
print(f"Package {parcel.id} for {parcel.recipient}: {parcel.status}")
scanner = Scanner(tracker)
scanner.read(42)
route = Route("Dana", ["Maple St", "Oak Ave", "Pine Rd", "Cedar Ln"])
print(f"{route.driver}'s route: {', '.join(route.stops)}")
Package 42 for Maya: ordered
Package 43 for Sam: ordered
Scanner shows: Package 42: shipped
Dana's route: Maple St, Oak Ave, Pine Rd, Cedar Ln
class Package {
status = "ordered";
constructor(id, recipient) {
this.id = id;
this.recipient = recipient;
}
ship() {
this.status = "shipped";
}
}
class Tracker {
packages = new Map();
add(parcel) {
this.packages.set(parcel.id, parcel);
}
all() {
return [...this.packages.values()];
}
scanned(id) {
const parcel = this.packages.get(id);
parcel.ship();
return `Package ${id}: ${parcel.status}`;
}
}
class Scanner {
constructor(tracker) {
this.tracker = tracker;
}
read(id) {
console.log(`Scanner shows: ${this.tracker.scanned(id)}`);
}
}
class Route {
constructor(driver, stops) {
this.driver = driver;
this.stops = stops;
}
}
const tracker = new Tracker();
tracker.add(new Package(42, "Maya"));
tracker.add(new Package(43, "Sam"));
for (const parcel of tracker.all()) {
console.log(`Package ${parcel.id} for ${parcel.recipient}: ${parcel.status}`);
}
const scanner = new Scanner(tracker);
scanner.read(42);
const route = new Route("Dana", ["Maple St", "Oak Ave", "Pine Rd", "Cedar Ln"]);
console.log(`${route.driver}'s route: ${route.stops.join(", ")}`);
Package 42 for Maya: ordered
Package 43 for Sam: ordered
Scanner shows: Package 42: shipped
Dana's route: Maple St, Oak Ave, Pine Rd, Cedar Ln
class Package {
id: number;
recipient: string;
status = "ordered";
constructor(id: number, recipient: string) {
this.id = id;
this.recipient = recipient;
}
ship(): void {
this.status = "shipped";
}
}
class Tracker {
packages = new Map<number, Package>();
add(parcel: Package): void {
this.packages.set(parcel.id, parcel);
}
all(): Package[] {
return [...this.packages.values()];
}
scanned(id: number): string {
const parcel = this.packages.get(id)!;
parcel.ship();
return `Package ${id}: ${parcel.status}`;
}
}
class Scanner {
tracker: Tracker;
constructor(tracker: Tracker) {
this.tracker = tracker;
}
read(id: number): void {
console.log(`Scanner shows: ${this.tracker.scanned(id)}`);
}
}
class Route {
driver: string;
stops: string[];
constructor(driver: string, stops: string[]) {
this.driver = driver;
this.stops = stops;
}
}
const tracker = new Tracker();
tracker.add(new Package(42, "Maya"));
tracker.add(new Package(43, "Sam"));
for (const parcel of tracker.all()) {
console.log(`Package ${parcel.id} for ${parcel.recipient}: ${parcel.status}`);
}
const scanner = new Scanner(tracker);
scanner.read(42);
const route = new Route("Dana", ["Maple St", "Oak Ave", "Pine Rd", "Cedar Ln"]);
console.log(`${route.driver}'s route: ${route.stops.join(", ")}`);
Package 42 for Maya: ordered
Package 43 for Sam: ordered
Scanner shows: Package 42: shipped
Dana's route: Maple St, Oak Ave, Pine Rd, Cedar Ln
It works, and it's small on purpose. A status is a word, a route is a list of streets, and nothing in it is a pattern. That's a good version 1.
Try it. Add package 44 for Nia and scan it too. The list should show three packages, and the scanner should show Package 44: shipped.
What's likely to change?
Before the first change request, ask the people who run the depot. Lakeside Parcel's dispatcher keeps a list on the whiteboard:

| Likely to change | Why | Where it lives in version 1 |
|---|---|---|
| What a package can do, depending on its status | Customers can cancel only before it ships; a delivered package can be returned | a status word, changed by ship() with no rules at all |
| How a route is stored | Routes are being split into zones, and next year they'll come from a route server, a page at a time | a plain list that every reader loops over |
| The carriers | QuickShip today; EcoFreight and SameDay sign on next month, each pricing and labeling its own way | nowhere yet |
| What a shipment holds | Insurance, a signature, gift wrap; boxes packed inside boxes on a pallet | nowhere yet |
| Fixing mistakes | The dispatcher assigns packages to drivers all day, and needs an undo button | nowhere yet |
And some things won't change: a package has a number and a recipient, and the tracker finds a package by its number. Those can stay plain.
Where the patterns come from
Each row is a chapter of this pass. The first row comes first: the customer website wants a Cancel button, and ship() is about to grow rules. Watch how quickly a status word with rules turns into the same check in every method, and what teams found to do about it.
Check yourself
2 questions to try on the lesson page.
So what
A class diagram, one sequence diagram and a list of what's likely to change: that's a plan, and it took less time than reading this lesson. Each change on the whiteboard is a problem you'll meet in this pass, and each one has a fix that teams found so often that it has a name.