SmartWarehouse

Inspiration Most logistics and supply chain tools are black boxes — you put in an order, something happens behind the scenes, and a result comes out. We wanted to build the opposite: a system where every decision is explainable, every stage is visible, and the math is real. The hackathon challenge gave us a concrete problem — 50 warehouses, customers anywhere in the US, find the best fulfillment path — and we saw it as an opportunity to build something that felt like a real production system, not a demo with fake data and hardcoded answers. We were also drawn to the constraint of building without heavy dependencies. No mapping SDKs, no external databases, no UI frameworks. That meant every piece of logic had to be written from scratch, which turned out to be the most educational part of the whole project.

What it does SmartWarehouse is a full-stack allocation and shipping optimization engine. A customer selects their location — either by choosing a city or entering custom coordinates — picks the products they want, and submits an order. The system then runs a four-stage pipeline to produce a complete fulfillment plan: which warehouse or warehouses are fulfilling the order, which carrier was selected and why, what the estimated cost and delivery time are, and how inventory was split across locations if needed. Every stage of the decision is surfaced in the UI with pass/fail results and the reasoning behind each outcome. Nothing is hidden. Admins also get a live inventory matrix that doubles as a control panel — clicking any cell fires a direct backend update to simulate restocks or shrinkage in real time, immediately re-evaluating safety margins across the dashboard.

How we built it The backend is a Flask REST API running a modular Python pipeline. The frontend is a Vanilla JavaScript single-page application with no frameworks — all state management, DOM updates, and multi-step form logic handled manually. The pipeline runs through four agents. The Distance Calculator takes the incoming latitude and longitude, implements the Haversine formula natively to compute exact spherical distances to all 50 warehouses, and returns a distance-ranked dictionary in milliseconds — no third-party mapping SDK needed. The Inventory Auditor then filters that list, enforcing a strict 10% safety stock reserve. Any warehouse where fulfilling the order would drop inventory below that threshold gets flagged as FAIL and removed from the pool. The Allocation Orchestrator takes the surviving warehouses and strongly prefers single-origin fulfillment, packing the whole order from the nearest eligible location. If no single warehouse can cover the volume, it activates recursive split-order logic, sharding the payload outward across multiple nodes. Finally the Shipping Controller queries mock FedEx and UPS classes that react dynamically to payload weight and distance — FedEx uses a $4.99 base rate with weight multipliers and a ~600 ground-miles-per-day transit model — and scores every quote against a configurable time-versus-cost matrix to flag the optimal carrier. On confirmation, the state manager permanently mutates the global warehouse dictionary, deducts inventory, generates a unique ORD token, and persists the full JSON receipt — accessible instantly from the orders dashboard via /api/orders.

Challenges we ran into Managing mutable shared state across Flask requests without an external database was the first hurdle. All warehouse data, inventory arrays, and order receipts live in global Python dictionaries, so ensuring atomic inventory deductions without race conditions required careful design of the mutation logic. The split-order algorithm was harder than expected. The recursive sharding logic had to handle partial fills, safety stock boundaries mid-split, maintaining correct warehouse sort order throughout the iteration, and avoiding double-allocation of the same warehouse for the same order. It went through several complete rewrites before it was solid. Building realistic carrier pricing was also a challenge. A mock API that returns the same number every time is useless for demonstrating a decision engine. We needed FedEx and UPS to respond meaningfully to different weights, distances, and product combinations so the time-versus-cost matrix had something real to evaluate. Finally, building a fully reactive SPA in Vanilla JavaScript without a framework meant handling manually everything a library would abstract away — re-rendering pipeline steps as each stage completes, syncing the inventory matrix after order placement, and managing multi-step form state across the quote and confirmation flow.

Accomplishments that we're proud of Every number the system produces is real. The distances use genuine spherical geometry. The inventory checks enforce an actual business rule. The carrier quotes respond to real order parameters. Nothing is faked for the demo. The step-by-step pipeline UI is what we're most proud of. Most systems like this just return a result. We built something that shows its work — every agent's output is visible to the user, with distance values, per-warehouse inventory status, and a full carrier breakdown before anything is confirmed. Making the reasoning transparent was a deliberate design decision and it's what makes SmartWarehouse feel like a real tool rather than a hackathon prototype.

What we learned Breaking the pipeline into discrete, independently testable agents was the best architectural decision we made. When something broke, we could isolate exactly which stage was producing bad output without digging through a monolithic function. We'll carry that pattern forward. We also learned that in-memory state is genuinely underrated for prototypes. No database overhead, simple data flow, easy to reason about. And we came away with a much deeper appreciation for how much complexity hides inside decisions that seem simple on the surface — picking a warehouse sounds easy until you're accounting for distance, inventory, safety stock, split orders, and carrier optimization all at once. Biggest takeaway: a decision engine is only as good as how clearly it communicates its reasoning. The algorithm mattered, but the UI that explains what the algorithm did and why ended up mattering just as much.

What's next for SmartWarehouse The immediate next step is replacing the in-memory store with a real database so the system can handle concurrent requests and persist state across restarts. After that, we want to integrate live carrier APIs — actual FedEx and UPS endpoints — to replace the mock classes with real-time quotes. On the geo side, we plan to add support for real address input with geocoding rather than requiring raw coordinates. Longer term, we want to build a returns and reverse logistics module, add demand forecasting so the system can flag warehouses likely to run low before orders come in, and explore route optimization for multi-stop deliveries. The core pipeline architecture is designed to be modular, so each of these can slot in without rebuilding from scratch.