Build a Two-Room Stock and Order Book
A one-person candle shop keeps its stock in a spare room and a friend's garage, and once sold the same gift set twice. You will build the small order book that counts both rooms, takes an order only when every line can be filled, and tells the owner what to make next.
The brief
The client
I make candles and small ceramic dishes and sell them online, about ten orders on a good day. I keep the stock in two places: the spare room in my flat and my friend Ilija's garage, where the big batches go. The counts live in a notebook and a spreadsheet, and I update them when I remember.
Once I sold the last "Winter Set" twice, because I had already packed one for a market stall and never wrote it down. I spent an evening apologising to a customer by email. I want one small tool that knows how many of each thing I have in each place, takes an order only when I can fill all of it, and tells me what to make next.
The problem
Stock counts live in two places and a notebook, so no single number says how many of a product can be sold. An order is accepted without a check, and the shortfall is found when the parcel is packed. That costs an apology and sometimes a refund.
The owner also does not know which products are running low until a customer asks for one. She makes everything by hand, so a product that runs out stays out until she has time to make more.
The client's name and figures are invented for this brief; the rules and the failures are ones that real businesses of this kind work with.
The spec
Requirements
- Add products with a price and a reorder level, and record how many units of each sit in the spare room and in the garage.
- Change a product's price. Orders already placed keep the price they were placed at.
- Show, for any product, its count in each room and its total across both.
- Place an order of one or more lines, and take the units from the spare room first and from the garage for the rest. If the same product appears on two lines, the lines are checked together.
- Look up one order, and list all orders.
- Refuse an order that cannot be filled in full, say which product is short and by how many, and change no count.
- Cancel a placed order and put each unit back in the room it came from.
- List the products whose total across both rooms is at or below their reorder level.
- Keep every count and order after the program is stopped and started again.
Deliverables
- A product that starts with one documented command. The owner can use it through whichever interface you chose: a web page, an HTTP API that other programs call by sending requests, or a command-line tool.
- A README that gets a reviewer from a fresh copy of your repository to a refused order, a split order and a cancelled order in 10 minutes.
- A short note of the shop's stock rules with three hand-worked example orders.
- Automated checks, code that drives the product and compares its answers with what you expect, that a reviewer can run with one command, covering the edges of the order rule.
- A way to replay one week of orders with a time supplied for each, and the hand-worked table of expected results it is compared against.
Out of scope
- Two people ordering the last unit at the same moment. One person uses the tool at a time here. The next project up, Build a Two-Location Online Shop, takes on the last-unit race.
- Taking payment or refunding. An order records a total in cents and nothing more, because payment would add rules that teach nothing about stock.
- Shipping, parcels and returns. An order is either placed or cancelled; shipping part of an order or receiving a return is a later problem.
- Customer details such as names, addresses and email. They would add forms and rules that teach nothing about stock.
- Logins and user accounts. One person uses the tool on one machine. Do not put it on the internet: with no login, anyone who can reach it can read the orders and change the stock.
- A search page or a shop front. The owner enters orders herself.
- Moving stock from one room to the other. Setting the two counts by hand is enough.
- More than two rooms, or choosing the room by distance or cost. The order of rooms is fixed, so the rule can be checked.
- Running on more than one machine, or as a hosted service. One person uses it on one machine, so the stock rule is the whole project.
Architectural constraints
- Amounts are in euro and exact to the cent. A price, a line price or an order total is never a fraction of a cent.
- Every time shown carries its time zone, or is shown in Europe/Amsterdam. The person or the request can supply the current time, so a reviewer can place an order at 00:30 without waiting for midnight. This exists for testing.
- A refused order changes nothing: no count, no order.
- A count never goes below zero.
- A quantity is a whole number of units greater than zero.
- An order shows the price per unit it was sold at and how many units on each line came from each room, and that stays the same after later price and count changes.
- Counts and orders survive stopping and starting the program.
Prerequisites
You can write a small program in a language of your choice and have saved data to a database or a file once. You do not need to know any framework, and you do not need to have written automated tests. You do not need to know how a home maker keeps stock in two places; the first Phase explains the business and the words the brief uses. Having kept track of anything in a spreadsheet and watched it drift from reality will make the problem familiar.
Free to start. An account is what keeps track of the checkpoints you finish.
Write the rules and count the stock
Produces a one-page note of the shop's stock rules and a program that holds products with a count in each room, shown per room and in total. Leaves orders for the next Phase.
Acceptance criteria
You write a note in your repository that states four rules in plain sentences. An order is filled in full or refused in full. Units come from the spare room first and the garage covers the rest. A refused order changes no count. Cancelling an order returns each unit to the room it came from.
The note also says what happens when one product appears on two lines of the same order, and says in one sentence what "short" means for a product (the units wanted are more than the spare room and the garage hold together).
You work three example orders by hand, and the note shows each with the counts before and after. One order is fully covered by the spare room. One is split across both rooms. One is refused, and its "after" counts are identical to its "before" counts. A reviewer who has only the note can recompute every "after" number.
Architectural guidance
An order that is half covered, a cancel and a product that appears twice on one order each need an answer before anything is built, or the shop's counts come out different depending on who handled the order. Worked examples with numbers settle those answers while changing one still costs a sentence.
Acceptance criteria
A product is added with a name that identifies it, a price in whole cents and a reorder level, and the count in the spare room and the count in the garage are set. Load the shop's twelve products: seven candles, three dishes and two gift sets, one of the gift sets named Winter Set. Prices run from 900 cents for a dish to 4800 cents for a gift set. The reorder level is 5 for candles and 3 for dishes and gift sets. Pick the starting counts yourself, at most about 30 in the spare room and about 100 in the garage. Nothing refuses a count above those figures.
Stop the program completely and start it again. Every product, price, reorder level and both counts come back unchanged.
Bad input is refused with a message and nothing changes: a count of -1, a count of 2.5, a price of -100, a price of 1250.5, and a second product with a name that is already taken. After the refusal the first product keeps its old numbers.
A product's price can be changed later. The new price is shown for that product, and its counts and reorder level are unchanged.
Architectural guidance
A price of 12.50 euro that drifts by a fraction of a cent produces an order total that is one cent off, and that cannot be explained to a customer. A tool that forgets its stock when it is stopped is a calculator, and the client finds out the first morning she opens it. A count or price that is accepted when it is nonsense corrupts every order after it.
Acceptance criteria
Asking for a product with 4 in the spare room and 6 in the garage shows the product's name, 4 for the spare room, 6 for the garage and 10 as the total. Set the garage count to 9 and ask again: the total is now 13, with no other change made.
A product with 0 in both rooms shows 0, 0 and 0. It does not answer "not found".
Asking for a product that does not exist gives a clear "not found" answer that names what was asked for. It does not show zero counts, and the program keeps running.
Architectural guidance
A total that is wrong is worse than none, because the owner sells against it. If one room's count can change while the total stays put, the total matches neither room and nobody can say which number is right. A mistyped product name that shows zero in stock looks like an empty shelf, and she makes candles she already has.
Architectural walkthrough
How a home maker keeps stock in two places
A maker of candles and small ceramic dishes sells her work online, about ten orders on a good day. She makes everything by hand, so a product that runs out stays out until she has time to make more. Her stock sits in two places: the spare room in her flat, which holds about 30 units, and a friend's garage, where the big batches go.
An order can name several products, and a customer expects all of it or none of it. One of her products is the Winter Set. Each product has a price and a reorder level, the count at which she wants to make more. She wants to know at any time how many of a product she can sell, and which products are running low.
The words this brief uses:
Product: one thing she sells, with a price and a reorder level.
Room: one of the two places stock is kept, the spare room or the garage.
Count: the number of units of a product in one room.
Total: a product's count in both rooms added together.
Order line: one product and a quantity inside an order.
Reorder level: the total at or below which she wants to make more.
Short: not enough units to fill an order line.
Why the rules go into a note first
Before the program exists, the rules go into a note with numbers in it. If "filled in full", which room is used first and what a cancel does live only in the owner's head, each gets decided differently every time it comes up, and the client finds the difference when a count is wrong. The three worked examples in the note come back later as the first automated checks, so the effort is not spent twice.
The shop's numbers first go wrong in three plain ways: a total that disagrees with the rooms, a price that drifts by a fraction of a cent, and stock forgotten on a restart.
Counts are plain numbers here and the room sizes are not enforced. The spare room holding about 30 units is a rough size, not a limit for the program to police.
Take orders that cannot oversell
Produces placing an order that takes stock from the right room and refuses one that cannot be filled in full, with automated checks on the edges of that rule. Leaves cancelling and the reorder list for the next Phase.
Acceptance criteria
Take a candle priced at 1800 cents with 3 in the spare room and 5 in the garage. Placing an order for 2 candles leaves 1 in the spare room and 5 in the garage. The answer shows the order with its lines (the product and the units), the price per unit as 1800, the line price and the order total as 3600 cents, the status "placed" and the time it was placed with its time zone.
An order with two lines of different products shows both lines, and its total is the sum of the two line prices in whole cents.
The person or the request can supply the current time when placing an order. This exists for testing, so a reviewer can check a time without waiting for it. When no time is supplied, the real clock is used. Place an order with the time supplied as 00:30 on 6 Nov 2026 in Europe/Amsterdam. The order shows 00:30 on 6 Nov 2026 in Amsterdam time, or the same instant as 23:30 UTC on 5 Nov 2026, with the zone or offset written next to it. It never shows 00:30 with no zone.
Look up the order by its identifier and get the same lines, total and time. List all orders and it appears in the list. Looking up an identifier that does not exist gives a clear "not found" answer.
Change the candle's price to 2000 cents afterwards. Looking the order up again still shows 1800 and 3600. After stopping and starting the program, the order and the new counts are still there.
Architectural guidance
If editing a price today changes the total of an order placed last week, her records stop matching what the customer paid. A time shown without its zone names two different dates depending on who reads it, so an order placed at 00:30 can land in the wrong day, and the owner reads her day in Amsterdam time. A reviewer who has to wait until midnight to check that case will not check it.
Acceptance criteria
Take a product with 3 in the spare room and 5 in the garage. An order for 5 leaves 0 in the spare room and 3 in the garage, and the order line records 3 units from the spare room and 2 from the garage.
Start again from 3 and 5. An order for 3 leaves 0 and 5: the garage count is not touched while the spare room can cover the whole line. Start again from 3 and 5 once more. An order for 2 leaves 1 and 5 and records 2 from the spare room and 0 from the garage.
An order with two lines of different products, each needing both rooms, records its own split on each line. Looking the order up again, and listing all orders, shows the same split after the program is stopped and started.
Architectural guidance
Spare room first and garage for the rest is the client's rule. If orders follow it unevenly, the counts stop matching where she physically took things from, and she walks to the garage for a candle that is on the spare room shelf. Counts and shelves change after the order, so where each unit came from has to be readable on the order afterwards, or a later cancel has nothing to go on.
Acceptance criteria
Take a candle with 3 in the spare room and 5 in the garage, and a dish with 1 in the spare room and 1 in the garage. An order with a line of 2 candles followed by a line of 4 dishes is refused. The answer names the dish as short and says it is short by 2. The candle counts are still 3 and 5, the dish counts are still 1 and 1, and the list of all orders is exactly as it was before. The refused order is not in the list in any form, not even as a cancelled one.
Put the short line first and the covered line second and the result is the same. If two lines are short, the answer names both products and both shortfalls.
A line with a quantity of 0, -2, 1.5 or the word "two" is refused, the answer says a quantity must be a whole number greater than zero, and no count changes. A line for a product that does not exist is refused, and the answer names it. An order with no lines is refused.
An order for the exact stock of a product is not refused. That edge is tested in the next Checkpoint.
Architectural guidance
If an order is refused after some of its lines have already taken their units, the shop's counts are lower than its shelves and no order explains the difference. That is the notebook problem the client came with. A refused order that still shows up in her list, even as cancelled, records a sale that never happened.
Acceptance criteria
One command runs the checks and prints, for each case, its name and whether it passed. The checks include at least these four cases, each starting from stock it sets up itself so none depends on another.
A product with 3 in the spare room and 5 in the garage: an order for 8 succeeds and leaves 0 and 0, and an order for 9 is refused with a shortfall of 1 and leaves 3 and 5. A product with 3 and 2: an order with two lines of that product, 3 and 3, is refused with a shortfall of 1 (6 wanted, 5 held), and an order with two lines, 2 and 3, succeeds and leaves 0 and 0. An order with a quantity of 0 is refused and leaves the counts as they were. The example orders from your rules note are checked too, with the numbers you wrote in it.
Break the rule on purpose: change the program so it checks each line alone and ignores the combined quantity of a repeated product. At least one check now fails and says which one. Put the program back and every check passes.
Architectural guidance
Counting bugs sit at the edges: exactly enough stock, one unit too many, the same product twice. Retrying them by hand after every change is tedious, so they get skipped, and the owner meets the first one on a real order. A check that has never failed proves little, so seeing one fail on purpose matters. Checks that lean on leftovers from earlier checks pass or fail depending on the order they run in.
Architectural walkthrough
This Phase has to survive an order that cannot be filled in full: a covered first line followed by a short second line, or one product on two lines whose combined quantity is more than the stock.
Afterwards the order must still show where each unit came from, what it sold for and when it was placed, in a time that carries its zone. The Phase ends with automated checks on the edges of the rule.
Cancel, restock and prove a week
Produces cancelling with each unit returned to the room it came from, a list of products to make next, and a repeatable replay of a week of orders checked against a hand-worked table. Leaves payment and shipping out.
Acceptance criteria
Set a product to 3 in the spare room and 5 in the garage, and place an order for 5. The counts are 0 and 3, and the order records 3 from the spare room and 2 from the garage. Cancel the order. The counts are 3 and 5 again, and the order shows the status "cancelled". The cancelled order still appears in the list of all orders, marked as cancelled.
Cancel the same order a second time. Both counts stay at 3 and 5, and the answer says the order was already cancelled. It does not report a failure that changes anything.
An order that took 2 from the spare room and 0 from the garage puts 2 back in the spare room and nothing in the garage. An order with two lines returns each line to its own rooms.
Cancelling an identifier that does not exist gives a clear "not found" answer and changes no count. After stopping and starting the program, the cancelled status and the restored counts are still there.
Architectural guidance
Cancelling has to reverse exactly what placing did. Putting every unit back in the spare room is simpler, and each cancelled order then moves the counts further from the shelves. A second cancel that puts the units back again leaves counts above what she holds, and the next order promises stock that is not there.
Acceptance criteria
A candle with a reorder level of 5, 2 in the spare room and 3 in the garage has a total of 5. It appears in the list with its total of 5 and its level of 5. Raise the garage count to 4 and the total is 6: the candle no longer appears.
A candle with 0 in the spare room, 20 in the garage and a level of 5 does not appear, because the comparison uses the total across both rooms.
A product with 0 in both rooms appears. Place an order that takes a product to or below its level and the product appears in the list straight away. Cancel that order and the product leaves the list.
When no product is at or below its level, the list is empty and says that nothing is low, so an empty answer cannot be taken for a failure.
Architectural guidance
The owner finds out a product is running low when a customer asks for it, and she makes everything by hand, so a product that runs out stays out until she has time. A list that is out of date after an order or a cancel sends her to make the wrong thing. The case where the total equals the level is the one that is easy to get wrong.
Acceptance criteria
A script or test run starts from a stated set of products and counts and places at least 12 orders in a fixed order, supplying a placed time for each. Several orders are split across both rooms, two are refused, and two are cancelled. Orders have one to three lines of one to four units each, as the client's real orders do.
You write a table in your repository that lists the expected counts for each product in each room after the run, the expected reorder list and the expected total of each order. It was worked out by hand from the rules note before the run. The run compares its final counts, reorder list and order totals with that table and reports every difference. A run with no differences ends by saying so.
After each order, placed, refused or cancelled, the run checks that no count is below zero. Restarting the program after the run and asking for the counts and orders gives the same answers.
Part-way through the week one product's price is changed. Orders placed before the change show their old line prices and totals, and orders placed after it show the new ones. The table says which totals are old and which are new.
Architectural guidance
Each Checkpoint can pass on its own and the shop can still be wrong when they run together: a cancel after a split order, a refused order between two good ones, a price edit in the middle of the week. A table copied from the program's own output agrees with the program even where the program is wrong. A count that dips below zero at any moment means the owner was told something false at that moment, even if the end counts look right.
Architectural walkthrough
Cancelling has to undo exactly what placing did, once, however often it is asked. The reorder list has to be right at the moment the owner looks.
The last Checkpoint replays a week against a table worked out by hand before anything runs.
Architectural walkthrough
An order is filled in full or not at all
The client's trouble was selling the last Winter Set twice. A notebook cannot refuse anything, so the shortfall surfaced when she packed the parcel and ended in an apology. The product has to refuse an order it cannot fill in full, and it has to do that without costing her stock she still holds.
A refused order that still takes stock
An order can have a covered first line and a short second line. If the units of the first line leave the count before the shortage on the second line shows, the order is refused and the candles have still vanished from the spare room. The counts are then lower than the shelves, which is the notebook problem again, with no order to explain the difference.
The same hole opens when one product appears on two lines. Three Winter Sets on one line and three on another each look fine against five in stock, and together they want six.
Cancelling into the wrong room
A cancelled order has to put units back on the shelf they were taken from. If everything goes back to the spare room, its count rises above what the shelf holds and the garage count falls below its shelf. The next order then promises units from a room that has none, and she finds out while packing.
Cents, prices and midnight
A total that is one cent off cannot be explained to a customer, and amounts like 0.1 + 0.2 do not add up exactly in most languages. Changing a price today must not rewrite last week's orders, or her records stop matching what customers paid. An order placed at 00:30 on the 6th in Amsterdam is still the 5th on a server in another zone, so a day's orders land in the wrong day unless every time shows its zone.
Where it shows if you cut a corner
A week of orders, worked out by hand before the run, shows what the earlier Checkpoints missed: counts a few units off after the refused orders, units back on the wrong shelf after a cancel, or old orders that changed when a price did. A table copied from the program's own output would agree with the program even where it is wrong.
The next project up in this domain is Build a Two-Location Online Shop. It keeps this rule and adds what happens when two people order the last unit at the same moment.