Smart Tools Hub
Smart Tools Hub is the web application we build and maintain for Three Bears Alaska - the single home for every store-based tool we've built for them. This page covers the application as a whole; each feature and flow within it is documented on its own page beneath this one.
Overview
Smart Tools Hub is a Next.js application hosted as a single Azure web app. It holds three separate flows - SmartPO, Tax Exemption, and Printer - that share a codebase, a web app, and a login, but are otherwise independent of one another and used by different staff on different devices.
- Stack: Next.js / React / TypeScript, MS SQL, Firebase auth
- Used by: Store staff - PICs on department handhelds, cashiers on front-of-store iPads
- Current focus: SmartPO
Repositories
| Repository | Purpose |
|---|---|
| client-three-bears-smart-tools | The application itself |
| client-three-bears-smart-tools-db-management | Database migrations for the application |
| tba-daily-excel | The Azure Functions behind purchase order files and tax exemption reports |
tba-daily-excel has a wiki covering how to call the functions. Very few of our projects have one, so
start there rather than reading the code.
History
Smart Tools Hub began as the replacement for the Warehouse Order Guide. The initial goal was to recreate WOG's warehouse purchase order building and then extend it with predictive analysis and predictive ordering, which remains the core of the application today. At that point the project was simply called SmartPO, and the tool itself still carries that name.
Early in SmartPO's development, Three Bears Alaska decided the tax exemption and printer flows were more important and should take precedence. Both were built and released. Tax exemption saw real use; the printer flow never saw actual use in stores. SmartPO then became the main focus and has remained there since.
Features & Flows
| Feature | Purpose | Status | Documentation |
|---|---|---|---|
| SmartPO | Purchase order building with predictive ordering | Main focus | SmartPO |
| Tax Exemption | Digital capture of tax-exempt purchases and signatures | In use | Tax Exemption |
| Printer | Printing item tags from a handheld device | Built and released, never adopted | Printer |
Why It's One Application
Whether tax exemption and SmartPO should be separate applications has been discussed back and forth. They are used by entirely different people in the store, which is the argument for splitting them. The argument against is cost: they were built in the same repo, so splitting them means development time to separate them and then ongoing maintenance and hosting for two repositories and two web apps.
A hub holding all the tools was proposed and accepted by the client, though they had no strong feelings either way about a central landing place. They later decided the tools should be separate on the basis of user roles - but there is only one login per store, so there is no way to tell a cashier from a PIC at sign in and route them to the right tool.
What shipped instead is separate flows in one application with no navigation between them. The devices do the routing: the iPads at the front of the store are bookmarked to the tax exemption flow, and the handhelds in each department are bookmarked to the SmartPO flow. A user never moves between tools because their device only ever points at one.
Architecture & Stack
A Next.js application using the Pages Router, written in TypeScript and packaged as a Docker image.
- Framework: Next.js 16, React 19, TypeScript
- UI: MUI 5 with Emotion, Sass, and Framer Motion
- State & data: Zustand for state, SWR for data fetching, React Hook Form with Zod for forms and validation
- Database: MS SQL, accessed through Sequelize over Tedious
- Auth: Firebase, both client and admin SDKs
- Azure: Identity and Blob Storage SDKs
- Testing: Jest with React Testing Library
Each flow is its own route tree under pages - order-guide for SmartPO, tax-exemption, and
printer - with a matching set of API routes under pages/api. The SmartPO routes are still named
order-guide, a holdover from the Warehouse Order Guide it replaced.
Data & Tables
Every database object the application depends on is catalogued in the Data Dictionary - tables, views, stored procedures and functions, each noting which side of the replication it lives on.
Not everything the application stores sits in the database. Tax exemption signatures are written to Azure blob storage, and the monthly tax exemption reports are written to SharePoint - see Tax Exemption for both.
Access & Permissions
Authentication is handled through Firebase, backed by the Microsoft tenant.
Each store has its own Microsoft account rather than individual accounts per employee, so a login identifies a store rather than a person. The store number appears in both the email address and the surname on the account.
How a given feature uses that store number can vary, so check the feature's own page for specifics.
Known Issues & Limitations
- No navigation between flows - a device bookmarked to one tool has no path to the other
- One login per store - there are no individual accounts, so flows cannot be routed by user role
- Printer flow unused - built and released, but never adopted by stores