Database isolation
Each service owns a private database. Inventory cannot reach into Financials to grab a journal entry. All data exchange happens through defined service contracts.
Distributed systems · Engineering brief 03
Build a merchandisemanagement system.
Build the software backbone that digitally mirrors the physical flow of goods and money through a retail business: from suppliers and purchasing to warehouse operations, checkout and accounting.
Architecture
8 services
Data ownership
Private databases
Delivery
4 phases
Review
Instructor / lead
RESTgRPC / ProtobufEvent busPrivate databasesFeature flags
Project vision
Follow the goods and the money.
You are building for a retail business that buys goods from suppliers, stores them in a warehouse and sells them in physical stores. Today, spreadsheets, paper receipts and manual data entry leave inventory counts stale, payments delayed and profitability unclear.
Build eight independently deployable backend services and the frontend components needed to operate them. Model purchasing, receiving, stock movement, sales, reconciliation and accounting through explicit service boundaries.
Divide the business into strict domains. Each module is a self-contained vertical slice: domain logic, private data and a frontend for human interaction. Together they form a distributed, modular Merchandise Management System (MMS).
Architectural mandate
Distributed by design.
Independent services are an architectural constraint of this exercise. The objective is to practise domain ownership, network contracts and recovery from partial failure. Keep point-of-sale, warehouse and accounting logic within their respective services.
Independent deployment
Deploy each module on its own. A bug fix in the warehouse app must not force a redeployment of the point-of-sale system.
Resilience
A Financials outage must not block receipt or sale recording. Preserve its events for recovery. Operations that require an immediate answer from an unavailable dependency must return a safe, explicit failure or pending state.
The communication contract
The islands communicate only over the network. Evaluate each interaction and choose the right tool for the nature of the data and the consumer.
Request / reply · JSON over HTTP
RESTful APIs
Use for frontend-facing web dashboards and mobile apps, and for general server-to-server retrieval where human readability and browser accessibility are valuable.
Typed service contracts · RPC
gRPC with Protocol Buffers
Use for backend calls that benefit from generated clients and typed contracts, such as stock reservation at checkout. Protocol Buffers define and serialise messages; gRPC provides the remote procedure call framework. Justify performance claims with measurements.
Asynchronous · Event bus
Domain events
Publish events such as GoodsReceived and ItemSold to a central message broker. Subscribers react at their own pace. Publishers do not need to know who is listening.
In this brief, request/reply means the business operation needs an answer before proceeding. It does not require blocking a thread: gRPC supports synchronous and asynchronous APIs, as well as streaming. Brokered events serve a different purpose: Receiving confirms a durable receipt without waiting for downstream bookkeeping. See the gRPC core concepts and Protocol Buffers overview.
The modules you will build
Eight domains. Clear ownership.
Every module below requires a backend service, a private database and its named frontend. Follow each domain’s responsibilities and boundaries.
01Vendor Management02Procurement (Purchasing)03Receiving (Inbound Goods)04Inventory (Stock Control)05Warehouse Operations (Space & Movement)06Retail Sales & Point of Sale (POS)07Sales Audit (Reconciliation)08Financials (Accounting & Ledger)
Module 01 · Phase 1
Vendor Management
“Who supplies our goods, and under what terms?”
The business problem
Supplier information is scattered across emails, spreadsheets and employees’ heads. There is no single place to find what a supplier sells, how long they take to deliver or their payment terms.
Core domain responsibilities
- Maintain a complete profile of every approved supplier, including contact details and how to pay them.
- Track which products each supplier is authorised to provide and at what cost.
- Record agreed lead times: how long a supplier takes to deliver after an order is placed.
- Maintain a historical record of supplier reliability, including whether deliveries arrived on time.
Frontend required
Vendor Management Portal
Procurement team and back-office administrators
A web dashboard to browse, add, edit and archive supplier records.
What this module does not do
- Does not decide when to order from a supplier.
- Does not track a specific purchase order. It owns who the suppliers are and what they offer.
Interaction rules
- Provides supplier catalogs, pricing, lead times and payment terms to Procurement when a purchase order is created.
Module 02 · Phase 1
Procurement (Purchasing)
“What are we committing to buy, how much will it cost us, and who approved it?”
The business problem
Buyers create purchase orders in spreadsheets or on paper. There is no visibility into orders, approvals or outstanding deliveries. Hallway conversations and forwarded emails create confusion and delays.
Core domain responsibilities
- Capture the intent to purchase as a formal request listing products, quantities and the supplier.
- Lock in unit costs and payment terms when the order is created so the expected commitment cannot change later.
- Enforce an approval workflow: an order is valid only after someone with the right authority signs off.
- Track the order lifecycle: draft, awaiting approval, sent to the supplier, fully received and closed.
Frontend required
Procurement Dashboard
Buyers and purchasing managers at the back office
A web dashboard to create purchase orders, route them for approval and view open orders.
What this module does not do
- Does not handle the physical arrival of goods.
- Does not check whether items are actually in the warehouse. It owns the intent to buy and the expected cost.
Interaction rules
- Publishes PurchaseOrderApproved events.
- Consumes GoodsReceived to reconcile received and outstanding quantities against individual order lines. Partial receipts do not automatically close an order.
- Listens for StockLow alerts from Inventory to trigger reorder suggestions.
Module 03 · Phase 2
Receiving (Inbound Goods)
“Did we actually receive what we ordered, in the right quantity, and in good condition?”
The business problem
At the loading dock, workers check boxes against paper lists or sign delivery notes without checking. Goods are lost, miscounted or accepted damaged, and problems surface weeks later during inventory counts.
Core domain responsibilities
- Match physical items arriving at the dock against an approved purchase order from Procurement.
- Record exactly what arrived: quantities, product codes and condition.
- Immediately flag shortages, overages or unordered items, and damaged goods.
- Produce a formal Goods Received Note (GRN) recording accepted, rejected and quarantined quantities. Physical arrival alone does not make every item sellable.
Frontend required
Warehouse Receiving App
Warehouse staff at the loading dock
A mobile/tablet app with barcode scanning to check items against a purchase order and finalise the receipt.
What this module does not do
- Does not decide where to store items.
- Does not update financial books directly. It confirms receipt of the physical goods.
Interaction rules
- Consumes PurchaseOrderApproved events to know what deliveries to expect.
- Validates open, approved orders through Procurement’s service contract.
- Publishes GoodsReceived events without waiting for Inventory or Financials to complete their bookkeeping.
Module 04 · Phase 1
Inventory (Stock Control)
“How much of each product do we own, where is it physically located, and what is it worth?”
The business problem
The warehouse thinks there are ten units, the store thinks there are three and the spreadsheet says zero. Customers are told items are out of stock while they sit in a backroom, or items are oversold when they do not physically exist.
Core domain responsibilities
- Maintain the authoritative stock record across physical locations, including the main warehouse and store backrooms. Apply incoming events as they are processed and make delayed updates visible.
- Own product master data, including the physical attributes used by warehouse operations.
- Increase stock when goods are received and decrease stock when goods are sold or returned to a supplier. Customer returns add stock back when applicable.
- Own inventory valuation and the cost assigned to each stock issue. Provide those costs to Financials through a contract so stock valuation and the ledger use the same basis.
- Distinguish stock on hand, sellable stock, reservations, quarantined stock, goods in transit and quantities on order. A transfer changes location without increasing total business stock.
Frontend required
Inventory Control Center
Inventory managers, buyers and the finance team at the back office
A web dashboard to browse stock levels, perform stock adjustments and view inventory valuation reports.
What this module does not do
- Does not decide which warehouse bin a product should be placed in.
- Does not process sales. It owns stock quantities, value and recorded locations.
Interaction rules
- Consumes GoodsReceived and ItemSold events, and updates quantities on order after PurchaseOrderApproved.
- Checks availability and reserves stock atomically for Retail Sales, preventing concurrent checkouts from reserving the same last unit.
- Publishes StockLow events when reorder points are hit.
Module 05 · Phase 2
Warehouse Operations (Space & Movement)
“Where exactly do we put things, where do we find them, and how do we move them between locations?”
The business problem
The warehouse is a maze of aisles, shelves and bins. Workers put boxes wherever there is space, then spend hours searching for products the inventory system says are somewhere in the building.
Core domain responsibilities
- Assign logical storage locations — bins, shelves and zones — to arriving products.
- Direct putaway by telling workers exactly where to place newly received items.
- Direct picking by telling workers where to retrieve items for store transfers or customer orders.
- Manage stock movements between locations, such as transferring 50 units from the central warehouse to Retail Store No. 3.
- Track warehouse capacity and space utilisation.
Frontend required
Warehouse Floor App
Warehouse pickers, forklift drivers and floor supervisors
A mobile/tablet app that directs workers to specific bins for putaway and picking.
What this module does not do
- Does not track overall stock quantities; Inventory owns that record.
- Does not order new stock. It owns physical geography and directs the movement of goods.
Interaction rules
- Consumes GoodsReceived events to create putaway tasks.
- Queries Inventory for physical attributes and historical demand, then communicates completed movements so Inventory can update stock locations.
Module 06 · Phase 3
Retail Sales & Point of Sale (POS)
“What did we sell, to whom, at what price, and how did they pay?”
The business problem
Checkout is where money enters the business. Cashiers need accurate prices, applicable discounts and stock availability. Wrong prices or a slow system drive customers away; incorrectly recorded sales lose money and visibility.
Core domain responsibilities
- Provide current retail prices and promotions at checkout.
- Validate that stock is available to sell before completing a transaction.
- Capture products, quantities, discounts, taxes and final totals for every sale.
- Process returns and exchanges by reversing prior sales and returning stock to inventory where applicable.
- Capture payment by cash, credit card, gift card or a combination of methods.
Frontend required
Point of Sale Terminal App
Cashiers at retail storefronts
A fast, touch-friendly app for scanning items, applying discounts, processing payments and printing receipts.
What this module does not do
- Does not track warehouse stock; it asks Inventory.
- Does not reconcile the cash drawer at day end; Sales Audit owns reconciliation. It captures sales as they happen.
Interaction rules
- Makes a synchronous call to Inventory to validate and reserve stock before finalising a sale.
- Publishes ItemSold after the transaction completes.
Module 07 · Phase 3
Sales Audit (Reconciliation)
“Does the money physically present in the store match what the sales system says it should be?”
The business problem
At day end, the expected cash balance is KES 500,000, but the drawer contains KES 400,850. Without reconciliation by payment method, cashier mistakes, unrecorded movements and payment-processing discrepancies go unnoticed or unresolved.
Core domain responsibilities
- Calculate expected totals by payment method and register, including opening float, completed sales, refunds and recorded cash movements.
- Capture the manager’s physical count of cash, credit card slips and other payment evidence.
- Compare expected and actual amounts and calculate overages or shortages per register, cashier and store.
- Require a manager’s investigation notes for discrepancies and sign-off before closing a register. An explanation does not make a shortage disappear.
- Keep a historical discrepancy log to identify patterns, including cashiers consistently coming up short.
Frontend required
Store Manager Dashboard
Store managers at retail branches
A web dashboard to enter cash counts, compare expected totals and close the day’s register.
What this module does not do
- Does not process original sales.
- Does not track inventory. It compares the POS record with actual money and payment evidence.
Interaction rules
- Consumes sale, refund and cash-movement events to calculate expected totals. Reconciles against POS at a defined register-session cutoff without counting the same transactions twice.
- Publishes DayClosed events for Financials after manager sign-off.
Module 08 · Phase 4
Financials (Accounting & Ledger)
“What does the business own, what does it owe, and is it making money?”
The business problem
Accountants manually re-enter goods receipts and sales into a separate system, calculate costs and record revenue. This is slow and error-prone, leaving the books weeks behind and profitability unclear.
Core domain responsibilities
- Automatically record accepted goods receipts, increasing inventory assets and the supplier receipt accrual. Distinguish goods received but not yet invoiced from invoice-backed accounts payable.
- Record balanced journal entries for sales: cash or payment clearing against revenue, and cost of goods sold against inventory assets. Use Inventory’s assigned issue cost.
- Track supplier obligations and due dates. Document how supplier invoices match receipts and how receipt accruals move to accounts payable without recording the liability twice.
- Track revenue and gross profit by product, store and business.
- Provide reliable financial reports without manual spreadsheet reconciliation.
Frontend required
Finance Portal
Accounting team and back-office executives
A web dashboard for accounts payable, the general ledger and profitability reports.
What this module does not do
- Does not physically count inventory, sell products or decide what to order.
- Translates events elsewhere in the business into debits, credits, assets, liabilities, revenue and expenses.
Interaction rules
- Consumes GoodsReceived, ItemSold and DayClosed, plus the valuation and correction contracts needed to post complete entries. Correlates receipts with Procurement’s frozen order lines through APIs or local event-derived records.
- Exposes read-only financial reports.
The big picture
How the modules work together.
Each module owns a distinct problem. The power of the system comes from how they coordinate. Follow the goods and money through these five business conversations.
Example assumptions
These examples use KES, a KES 10 unit cost and a KES 20 cash sale. Tax, discounts and payment fees are omitted from the arithmetic; their treatment still belongs in the implementation. The receipt example assumes accepted goods become business-owned stock and accrue a supplier obligation at receipt. GRNI means goods received not invoiced; invoice matching later transfers that balance to accounts payable. See Oracle’s receipt accrual and reconciliation documentation for an implementation of this distinction.
Scenario 1
Placing a purchase order
Procurement + Vendor Management
The business goal: A buyer needs to order 100 units of Product X from a supplier.
Request / reply · Procurement → Vendor Management
Procurement requests approved suppliers and pricing for Product X. Vendor Management returns suppliers, lead times and current wholesale costs. After the buyer selects Supplier A, Procurement asks for current payment terms. Vendor confirms Net 30 days; Procurement freezes those terms and prices on the purchase order.
Announcement · PurchaseOrderApproved
Purchase Order #1001 is approved for Supplier A. The business is committed to receiving the goods.
Subscribers
Receiving now expects the delivery. Financials records the purchase commitment for planning, without posting an inventory asset or trade payable merely because the PO was approved. Inventory updates quantity on order, keeping expected goods separate from stock on hand.
Scenario 2
The truck arrives at the dock
Receiving + Procurement + Warehouse Operations + Inventory + Financials
The business goal: Verify the arriving goods, prepare them for storage and account for the receipt.
Request / reply · Receiving → Procurement
Receiving checks the supplier’s delivery note against an open, approved purchase order. Procurement returns PO #1001 and the expected items and quantities.
Physical validation
Workers scan the delivery. Receiving compares 95 delivered units with 100 ordered units and flags the shortage of five immediately.
Announcement · GoodsReceived
Receiving accepts 95 undamaged units of Product X and records five outstanding. It durably saves GRN #500 together with the intent to publish GoodsReceived before confirming “Receipt Complete”. Subscribers finish their work independently.
Subscribers
Inventory adds 95 units on hand and reduces quantity on order to five. Procurement consumes the receipt to keep PO #1001 partially received until the remainder arrives or is explicitly cancelled. Warehouse Operations creates a putaway task. Financials obtains the frozen KES 10 unit cost using the PO-line reference, debits inventory assets KES 950 and credits goods received not invoiced (GRNI) KES 950. Matching the invoice later clears that accrual into accounts payable.
Scenario 3
Storing the goods
Warehouse Operations + Inventory
The business goal: Place the 95 units at a logical, traceable location in the warehouse.
Request / reply · Warehouse Operations → Inventory
Warehouse Operations requests Product X’s dimensions, weight and sales velocity. Inventory returns the physical attributes and historical demand data.
Putaway decision
Product X sells quickly, so Warehouse Operations directs the worker to Bin A-01 near shipping rather than deep in the warehouse.
Location confirmation · Warehouse Operations → Inventory
After placement, Warehouse Operations reports the 95 units in Main Warehouse, Bin A-01. Inventory acknowledges and updates its location record so other services can find available stock.
Scenario 4
A customer buys an item
POS + Inventory + Sales Audit + Financials
The business goal: Sell one unit of Product X at Retail Store No. 3.
Request / reply · POS → Inventory
Assume Warehouse Operations has transferred 50 of the 95 units to Store No. 3, leaving 45 in the main warehouse. POS requests one unit at the store. Inventory atomically checks and reserves it, returning a reservation ID so another checkout cannot claim it while payment is processed.
Payment and announcement · ItemSold
The customer pays KES 20 in cash. POS durably records transaction T-777 and the intent to publish ItemSold, including the reservation ID. The reservation remains protected until the sale is applied or an explicit recovery outcome resolves it.
Subscribers
Inventory applies the sale once, deducts the reserved unit and resolves the reservation: 49 units remain at the store and 45 in the warehouse, for 94 overall. Sales Audit adds KES 20 to Register No. 2’s expected cash. Financials debits cash KES 20 and credits revenue KES 20; using Inventory’s KES 10 issue cost, it debits cost of goods sold KES 10 and credits inventory KES 10. Gross profit is KES 10.
Scenario 5
Closing the store for the night
Sales Audit + POS + Financials
The business goal: Count the register, explain differences and finalise the trading day.
Request / reply · Sales Audit → POS
Sales Audit requests Register No. 2’s completed transactions up to an agreed session cutoff. For this example, all 150 transactions are cash, with no opening float, refunds or recorded cash movements. Expected cash is KES 5,000; card and gift-card reconciliation are separate.
Count and reconcile
The manager counts KES 4,950. Sales Audit calculates a KES 50 shortage and blocks closing until investigation notes and sign-off are recorded: “Recount completed; no supporting payout record found. KES 50 shortage accepted for investigation.” If evidence instead establishes a cleaning-supplies payout, record that cash movement and expense, then recalculate the variance.
Announcement · DayClosed
Sales Audit publishes DayClosed with the register session, cutoff, expected and actual amounts, KES 50 residual shortage and approval reference. Financials debits Cash Over/Short KES 50 and credits cash KES 50. Closing with approval preserves the discrepancy; it does not describe the register as balanced.
Share the facts each domain needs.
Receiving does not need to know the financial value of the goods. Financials does not need to know their warehouse bin. Retail Sales does not need to know the supplier. Include stable product, purchase-order-line, receipt and transaction references so each consumer can obtain authorised facts from the owning service. Local copies built from events are permitted; ownership and write authority remain with the source domain.
Architecture review
Design decisions to defend.
The scenarios describe successful business flows. Your design must also explain how those flows remain correct under concurrency, retries and partial failure. Record these decisions and demonstrate the relevant cases as each module reaches review.
Durable events and safe retries
- Explain how a committed receipt or sale survives a crash before publication. A transactional outbox saves the business change and pending event in one local transaction; a relay publishes it later. An alternative must provide equivalent recovery guarantees.
- Give events stable IDs and versions. Consumers must apply each business effect once even if delivery repeats. Document retry limits, failed-message storage, replay and handling of events received out of order. Do not assume the broker makes database writes exactly once.
Reservations and payment recovery
- Define reservation states, expiry, cancellation and confirmation. Test two checkouts competing for the last unit. Retrying the same reservation request must not reserve extra stock.
- Explain recovery when payment succeeds but the sale response or ItemSold event is delayed. An unresolved payment must not release stock blindly or trigger a second charge. Document how POS and Inventory reconcile the outcome, including compensation when completion fails.
Stock state and domain ownership
- Define how accepted, rejected and quarantined quantities affect on-hand, sellable and on-order balances. Specify partial receipts, over-receipt approval, transfers in transit and customer-return condition checks.
- Inventory owns product master data, stock balances and issue costs. Warehouse Operations owns bin geography and movement tasks. POS owns completed sales history; Inventory can derive demand from sales events. Vendor reliability can be derived from promised dates and actual receipts. Share facts through contracts, not shared tables.
Financial records and reconciliation
- Specify how Financials obtains frozen purchase costs and Inventory’s issue costs when their events arrive at different times. Keep incomplete postings pending and traceable. Every posted journal must balance and refer to the originating transaction.
- Choose and document the valuation method, currency representation, rounding and tax treatment. Correct posted entries through traceable reversals or adjustments. Reconcile refunds, split payments and gift-card liabilities as well as cash sales.
- Define the register-session cutoff and the treatment of late events and post-close corrections. Reconcile by payment method; a card payment is not cash in the drawer. Do not add a POS snapshot on top of the same sales already counted from events.
Service contracts and access
- Document request, response and event schemas, error outcomes, correlation IDs and compatibility rules. Identify who may publish, consume or invoke each contract, and expose only the data each role needs.
- Enforce purchase approval, stock adjustment and register sign-off authority on the backend. Feature flags and hidden menu items do not grant or revoke user permissions.
Failure behaviour and operational evidence
- Set request deadlines and define safe outcomes for unavailable synchronous dependencies. If Inventory cannot confirm a reservation, checkout cannot claim success. Financials being offline should not prevent a durably recorded sale.
- Document supported load, measured checkout latency, event-processing lag and recovery time. Show how an operator finds failed events and follows one transaction across services. Explain the chosen broker, retention policy and recovery limits rather than claiming unlimited availability.
Implementation references: transactional outbox, idempotent consumers and gRPC deadlines.
Feature flags
Build in four phases.
Do not build all eight modules at once. Use these module flags to control routes, event listeners and frontend visibility as development proceeds.
Phase 1
Foundation
Phase 2
Warehouse
Phase 3
Retail
Phase 4
Accounting
Developer handbook
Development workflow & standards.
Repository structure: monorepo
- Keep all modules’ source code in one monorepo to simplify shared utilities, dependency management and cross-module reviews. Each service still owns its domain logic and private database and must deploy independently.
- Shared libraries may contain infrastructure helpers and versioned contracts. Do not share persistence models or import another service’s business logic as a shortcut around its network boundary.
Feature flags
- Build in the four phases above. Use a configuration toggle for each module to hide incomplete or disabled functionality.
- Before deploying a new module, wrap its routes and event listeners in a feature-flag check.
- When a module is disabled, hide its frontend menu items or show a “Coming Soon” screen.
- A disabled consumer must not acknowledge and discard its events. Preserve its backlog or replay position and document retention limits. Provision durable subscriptions before publishing, or provide a replay/bootstrap path for modules introduced in later phases.
- Define dependent-feature behaviour when a required module is disabled. For example, disable checkout if stock reservation is unavailable.
Pull requests & code review
- Work on feature branches and submit pull requests; do not push directly to main.
- Use descriptive branch names such as feat/receiving-service, fix/inventory-reservation or docs/system-overview.
- Keep each PR to one module or one significant feature. Avoid unrelated changes and make small commits.
- When a module is ready, open a PR and request review from the instructor / lead architect.
- Merge only after tests pass, API documentation is updated, the phase’s feature flag is correctly configured and the README is updated for any new module.
README.md: the developer entry point
- Project overview: what the MMS does and the business problem it solves.
- Architecture diagram: modules and their synchronous versus event-driven interactions.
- Module directory: a table of each module, directory path, purpose and current phase status.
- Local development setup: step-by-step instructions to start the whole system, for example docker compose up.
- Feature flag configuration: how to enable or disable specific modules.
- Testing instructions: commands for unit and integration tests.
- API documentation link: how to access generated Swagger/OpenAPI documentation.
API documentation: OpenAPI & Protobufs
- Document every service contract before implementing business logic.
- REST: put Swagger/OpenAPI YAML or JSON specifications in contracts/openapi/. Where supported, generate documentation from code annotations and expose a Swagger UI endpoint such as /docs.
- gRPC: put .proto files in contracts/proto/. These are the source of truth for gRPC contracts. Generate server stubs and client libraries with buf or protoc.
- Document event schemas alongside service contracts, including producer, consumers, event ID, version, business references and compatibility rules. Generated API documentation must agree with the committed contract.
Testing standards
- Write both unit and integration tests. Untested code is not ready for review.
- Include evidence for duplicate event delivery, crashes around publication, concurrent reservations, partial receipts, payment recovery, returns, balanced journals and disabled-consumer recovery. Test each relevant failure path as its phase is introduced.
- Run tests in CI using GitHub Actions. All tests must pass before merging.
Submission checklist
The definition of done.
A module is ready for review only when all six conditions are met. Request review from the instructor / lead architect on the pull request.
- 01Source code lives in the correct monorepo directory.
- 02The feature flag for the module’s phase is correctly implemented.
- 03A pull request targeting main is open for instructor / lead architect review.
- 04Swagger/OpenAPI, .proto files and event schemas are updated wherever the module changes those contracts.
- 05Unit and integration tests pass in GitHub Actions CI.
- 06The root README.md reflects the module’s current status.