Boxio $\cdot$ Operations & Inventory Command Center

A lightning-fast, backend-agnostic stock tracking engine built to scale from local garages to global warehouses.

---

🌟 Executive Summary

Boxio is a modern inventory command center designed to give teams absolute visibility over their physical supply chain. It immediately surfaces stock health—what's on hand, what's low, what's on order, and where items live.

Built with an immaculate design philosophy using Geist typography, fluid layouts, and hidden scrollbars, Boxio transitions seamlessly from public landing experiences to deep operational management.

---

📐 System Architecture & Data Topology

+--------------------------------------------------------------------------+
|                             Client Tier                                  |
|   [TanStack Router SSR] + [Tailwind v4] + [shadcn/ui] + [Recharts]       |
+--------------------------------------------------------------------------+
                                     |
                                     v
+--------------------------------------------------------------------------+
|                        Unified Data Hooks Layer                          |
|         useInventoryData.ts (Reads) & useInventoryMutations.ts (Writes)  |
+--------------------------------------------------------------------------+
                     |                               |
        (Interactive Demo Mode)             (Production Cloud Mode)
                     |                               |
                     v                               v
         +-----------------------+       +-----------------------+
         |      DemoStore        |       |     Lovable Cloud     |
         | (In-Memory Version)   |       | (PostgreSQL Database) |
         +-----------------------+       +-----------------------+

---

✨ Key Features

• 📊 Live Stock Health Dashboard: Instantly view total SKUs, healthy stock, low-stock alerts, and out-of-stock items paired with a real-time event activity feed.
• 📦 Comprehensive Catalog & Asset Tracking: Filterable and sortable data tables featuring detail sheets, custom fields, printable barcode/QR asset labels, and complete movement audit histories.
• ledger️ Immutable Movement Ledger: All item quantities are derived strictly from a ledger tracking Received, Shipped, Adjusted, and Transferred operations for bulletproof accountability.
• 🛒 Automated Purchase Orders (POs): Intelligent workflow that picks suppliers, auto-suggests low-stock items with pre-filled reorder quantities, and tracks shipments from draft to receipt.
• 🏢 Hierarchical Locations Tree: Warehouse $\rightarrow$ Zone $\rightarrow$ Aisle $\rightarrow$ Shelf $\rightarrow$ Bin structural mapping with targeted location summaries and transfer tracking.
• 👥 Role-Based Access Control (RBAC): Granular 3-tier permission matrix (Admin, Manager, Requestor) enforced across navigation, route guards, and component gates.
• 📈 Advanced Analytics & Reporting: Recharts-powered data visualizations tracking turnover ratios, movement trends, supplier scorecards, and spend analytics with CSV export.
• 🤖 Built-in AI Intelligence Engines: Pure TypeScript modules handling dynamic reorder point calculations, statistical anomaly outlier detection, and natural language conversational search.

---

🚀 Core Functional Modules

+--------------------------------------------------------------------------+
|                         Boxio Core Modules                               |
|                                                                          |
|  +--------------------+  +--------------------+  +--------------------+  |
|  |     Dashboard      |  |   Catalog & SKU    |  |  Movements Ledger  |  |
|  |  (Metrics & Alarms)|  | (Barcodes & Sheets)|  | (Audit Trail Log)  |  |
|  +---------+----------+  +---------+----------+  +---------+----------+  |
|            |                       |                       |             |
|  +---------+----------+  +---------+----------+  +---------+----------+  |
|  |  Purchase Orders   |  |   Locations Tree   |  |     Suppliers      |  |
|  |  (Auto Reordering) |  | (Warehouse/BinMap) |  | (Scorecards & Lead)|  |
|  +--------------------+  +--------------------+  +--------------------+  |
+--------------------------------------------------------------------------+

• Dashboard: Real-time stock counts, critical low-stock alerts, 20-event activity feeds, and quick search.
• Catalog: Sortable grid with bulk actions, printable asset labels, custom fields, and complete movement timelines.
• Movements Ledger: Immutable ledger tracking Received, Shipped, Adjusted, and Transferred operations. Quantities are mathematically derived directly from this ledger.
• Purchase Orders: Auto-generates line items for below-threshold stock, tracking drafts through receipt confirmation.
• Locations Hierarchy: Zone $\rightarrow$ Aisle $\rightarrow$ Shelf $\rightarrow$ Bin tracking with support for in-transit stock transfers.
• AI Intelligence Engines: Dynamic reorder thresholds (reorder-engine.ts), anomaly detection (anomaly-engine.ts), and natural language search parsing.

---

🔒 Security & Role-Based Access Control (RBAC)

Boxio utilizes a strict 3-tier permission matrix mapped across routing layers, UI gates, and database attributes:

                  [User Authentication]
                           |
            +--------------+--------------+
            |                             |
      (Live Auth)                   (Try Demo)
            |                             |
            v                             v
    [Lovable Cloud User]           [In-Memory Session]
            |                             |
            +--------------+--------------+
                           |
                           v
        [Role Matrix: Admin / Manager / Requestor]
                           |
       +-------------------+-------------------+
       |                   |                   |
       v                   v                   v
[Route Guarding]   [Sidebar Filtering]   [Component Gates]

---

📂 Route Structure (src/routes/)

src/routes/
├── __root.tsx           # HTML shell, head metadata, providers, and toaster
├── index.tsx            # Public marketing landing page & authentication hub
├── app.tsx              # Authenticated layout shell (sidebar, header, mobile nav)
├── app.dashboard.tsx    # Central metrics, attention panels, and quick search
├── app.catalog.tsx      # Inventory item management, filters, and barcode labels
├── app.movements.tsx    # Immutable ledger for received/shipped/adjusted stock
├── app.locations.tsx    # Hierarchical location tree and bin mapping
├── app.suppliers.tsx    # Vendor profiles, trade terms, and performance scorecards
├── app.purchase-orders.tsx # PO lifecycle management and receiving workflows
├── app.requests.tsx     # Item request queue for staff and managers
├── app.analytics.tsx    # Deep analytics, trend charts, and CSV data export
├── app.ai-insights.tsx  # Demand forecasting charts and anomaly alerts
├── app.settings.tsx     # System admin, custom fields, and user roles
└── app.help.tsx         # User guides and keyboard shortcuts documentation

---

🛠️ Technology Stack

• Core Framework: TanStack Start v1 (React 19, TanStack Router with SSR capabilities), Vite 7.
• Styling & UI: Tailwind CSS v4 (src/styles.css), shadcn/ui components, Recharts data-visualization, sonner toast notifications.
• Typography: Geist Sans (Interface UI) & Geist Mono (SKUs, quantities, and metrics).
• Backend Integration: Native Lovable Cloud (PostgreSQL) paired with Supabase Auth (Email & Google OAuth) alongside an optional sandboxed Demo Store mode.

---

📦 Getting Started & Quick Local Setup

1. Clone the Repository:

git clone https://github.com/your-username/boxio.git
cd boxio

2. Install Dependencies:

npm install

3. Run Development Server:

npm run dev

4. Build for Production:

npm run build

---

⌨️ Keyboard Shortcuts & Power Actions

• **⌘K / Ctrl + K**: Open the global command palette for rapid navigation and quick actions.
• Esc: Close active modals, detail sheets, and overlays.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.