Inventory Management with a State Machine
Modelled warehouse stock movement as a finite state machine — safer transitions, zero ghost-stock bugs.
The problem
The internal Inventory Management System had grown into a tangle of boolean flags. 'Reserved but not picked', 'returned but not restocked' — edge cases multiplied. Warehouse operators manually reconciled stock nightly.
Approach
- Modelled every stock item as a finite state machine with explicit transitions (AVAILABLE → RESERVED → PICKED → SHIPPED / RETURNED).
- Encoded invariants as database constraints and transition guards, not application-layer booleans.
- Built 5+ vendor onboarding adapters as pluggable modules — one surface, many vendor quirks.
- Event-sourced every transition for auditability and post-hoc debugging.
Key decisions
Application-level FSM alone lets bad data sneak in via direct DB writes. Constraints at the schema level enforced the contract for every consumer.
Each vendor has its own quirks (units, timezones, idempotency). An adapter interface kept the core pipeline vendor-agnostic and testable.
Trade-offs
- Event-sourced log adds storage — bounded with retention + snapshots.
- Adding a new state requires a schema migration — worth the safety.
Impact
- Ghost-stock bugs eliminated post-launch.
- Warehouse teams shifted from nightly reconciliation to exception-only triage.
- Onboarding new vendors dropped from weeks to days.
Have a system that needs to scale — or stop breaking?
I work with a small number of teams each month on architecture reviews, scaling, and hands-on backend engineering. If that sounds like you, let's talk.