From ba488b200a4cdef28d52c64590f9fded55ad4971 Mon Sep 17 00:00:00 2001
From: Weitzman <liweitzman@deloitte.com>
Date: Thu, 21 May 2026 10:57:33 -0700
Subject: [PATCH] Add Restocking feature and sidebar composable

- Add Restocking view with forecast-driven, budget-aware recommendations
- Add useSidebar composable with persistent collapse state and mobile breakpoint support
- Add /restocking POST endpoint to server with category-based lead time calculation
- Extend mock_data and demand_forecasts with restocking order fixtures
- Update App.vue and Orders.vue for sidebar and navigation integration
- Add docs/architecture.html
- Update CLAUDE.md
---
 CLAUDE.md                            |   3 +
 client/src/App.vue                   | 363 ++++++++++++-----
 client/src/api.js                    |  17 +
 client/src/composables/useSidebar.js |  67 ++++
 client/src/main.js                   |   2 +
 client/src/views/Orders.vue          | 135 ++++++-
 client/src/views/Restocking.vue      | 376 ++++++++++++++++++
 docs/architecture.html               | 572 +++++++++++++++++++++++++++
 server/data/demand_forecasts.json    |  82 ++--
 server/main.py                       | 136 ++++++-
 server/mock_data.py                  |   4 +
 11 files changed, 1621 insertions(+), 136 deletions(-)
 create mode 100644 client/src/composables/useSidebar.js
 create mode 100644 client/src/views/Restocking.vue
 create mode 100644 docs/architecture.html

diff --git a/CLAUDE.md b/CLAUDE.md
index d2086efa..0baaab87 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -53,6 +53,9 @@ npm install && npm run dev
 - `GET /api/demand`, `/api/backlog` - No filters
 - `GET /api/spending/*` - Summary, monthly, categories, transactions
 
+## Code Style
+- Always document non-obvious logic changes with comments
+
 ## Common Issues
 1. Use unique keys in v-for (not `index`) - use `sku`, `month`, etc.
 2. Validate dates before `.getMonth()` calls
diff --git a/client/src/App.vue b/client/src/App.vue
index c2da05a5..567f97d7 100644
--- a/client/src/App.vue
+++ b/client/src/App.vue
@@ -1,42 +1,181 @@
 <template>
   <div class="app">
-    <header class="top-nav">
-      <div class="nav-container">
-        <div class="logo">
-          <h1>{{ t('nav.companyName') }}</h1>
-          <span class="subtitle">{{ t('nav.subtitle') }}</span>
+    <aside class="sidebar" :class="{ collapsed: isCollapsed }">
+      <div class="sidebar-brand">
+        <h1>
+          <span class="logo-full">{{ t('nav.companyName') }}</span>
+          <span class="logo-mark">F</span>
+        </h1>
+        <span class="subtitle">{{ t('nav.subtitle') }}</span>
+      </div>
+
+      <button
+        type="button"
+        class="sidebar-toggle"
+        :aria-label="isCollapsed ? 'Expand sidebar' : 'Collapse sidebar'"
+        :disabled="isMobile"
+        :title="isMobile ? 'Sidebar locked at this width' : ''"
+        @click="toggle"
+      >
+        <svg
+          v-if="isCollapsed"
+          xmlns="http://www.w3.org/2000/svg"
+          width="18"
+          height="18"
+          viewBox="0 0 20 20"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <polyline points="7 4 13 10 7 16" />
+        </svg>
+        <svg
+          v-else
+          xmlns="http://www.w3.org/2000/svg"
+          width="18"
+          height="18"
+          viewBox="0 0 20 20"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <polyline points="13 4 7 10 13 16" />
+        </svg>
+      </button>
+
+      <nav class="sidebar-nav">
+        <router-link
+          to="/"
+          :title="t('nav.overview')"
+          :class="{ active: $route.path === '/' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <rect x="2.5" y="2.5" width="6" height="6" rx="1" />
+              <rect x="11.5" y="2.5" width="6" height="6" rx="1" />
+              <rect x="2.5" y="11.5" width="6" height="6" rx="1" />
+              <rect x="11.5" y="11.5" width="6" height="6" rx="1" />
+            </svg>
+          </span>
+          <span class="nav-label">{{ t('nav.overview') }}</span>
+        </router-link>
+
+        <router-link
+          to="/inventory"
+          :title="t('nav.inventory')"
+          :class="{ active: $route.path === '/inventory' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M2.5 6 10 2.5 17.5 6 10 9.5 2.5 6Z" />
+              <path d="M2.5 6v8L10 17.5V9.5" />
+              <path d="M17.5 6v8L10 17.5" />
+            </svg>
+          </span>
+          <span class="nav-label">{{ t('nav.inventory') }}</span>
+        </router-link>
+
+        <router-link
+          to="/orders"
+          :title="t('nav.orders')"
+          :class="{ active: $route.path === '/orders' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <rect x="4" y="4" width="12" height="14" rx="1.5" />
+              <rect x="7" y="2.5" width="6" height="3" rx="0.75" />
+              <line x1="7" y1="10" x2="13" y2="10" />
+              <line x1="7" y1="13" x2="13" y2="13" />
+            </svg>
+          </span>
+          <span class="nav-label">{{ t('nav.orders') }}</span>
+        </router-link>
+
+        <router-link
+          to="/restocking"
+          title="Restocking"
+          :class="{ active: $route.path === '/restocking' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M16.5 6.5A7 7 0 1 0 17 12" />
+              <polyline points="17 3 17 7 13 7" />
+            </svg>
+          </span>
+          <span class="nav-label">Restocking</span>
+        </router-link>
+
+        <router-link
+          to="/spending"
+          :title="t('nav.finance')"
+          :class="{ active: $route.path === '/spending' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <line x1="10" y1="2.5" x2="10" y2="17.5" />
+              <path d="M13.5 5.5H8.25a2.25 2.25 0 0 0 0 4.5h3.5a2.25 2.25 0 0 1 0 4.5H6" />
+            </svg>
+          </span>
+          <span class="nav-label">{{ t('nav.finance') }}</span>
+        </router-link>
+
+        <router-link
+          to="/demand"
+          :title="t('nav.demandForecast')"
+          :class="{ active: $route.path === '/demand' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <polyline points="2.5 15 7 10 10 12.5 17.5 5" />
+              <polyline points="13 5 17.5 5 17.5 9.5" />
+            </svg>
+          </span>
+          <span class="nav-label">{{ t('nav.demandForecast') }}</span>
+        </router-link>
+
+        <router-link
+          to="/reports"
+          title="Reports"
+          :class="{ active: $route.path === '/reports' }"
+        >
+          <span class="nav-icon" aria-hidden="true">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M4.5 2.5h7L15.5 6.5v11a0 0 0 0 1 0 0h-11a0 0 0 0 1 0 0Z" />
+              <polyline points="11.5 2.5 11.5 6.5 15.5 6.5" />
+              <line x1="7" y1="10.5" x2="13" y2="10.5" />
+              <line x1="7" y1="13" x2="13" y2="13" />
+              <line x1="7" y1="15.5" x2="11" y2="15.5" />
+            </svg>
+          </span>
+          <span class="nav-label">Reports</span>
+        </router-link>
+      </nav>
+
+      <div class="sidebar-footer">
+        <div class="sidebar-footer-item">
+          <LanguageSwitcher />
+        </div>
+        <div class="sidebar-footer-item">
+          <ProfileMenu
+            @show-profile-details="showProfileDetails = true"
+            @show-tasks="showTasks = true"
+          />
         </div>
-        <nav class="nav-tabs">
-          <router-link to="/" :class="{ active: $route.path === '/' }">
-            {{ t('nav.overview') }}
-          </router-link>
-          <router-link to="/inventory" :class="{ active: $route.path === '/inventory' }">
-            {{ t('nav.inventory') }}
-          </router-link>
-          <router-link to="/orders" :class="{ active: $route.path === '/orders' }">
-            {{ t('nav.orders') }}
-          </router-link>
-          <router-link to="/spending" :class="{ active: $route.path === '/spending' }">
-            {{ t('nav.finance') }}
-          </router-link>
-          <router-link to="/demand" :class="{ active: $route.path === '/demand' }">
-            {{ t('nav.demandForecast') }}
-          </router-link>
-          <router-link to="/reports" :class="{ active: $route.path === '/reports' }">
-            Reports
-          </router-link>
-        </nav>
-        <LanguageSwitcher />
-        <ProfileMenu
-          @show-profile-details="showProfileDetails = true"
-          @show-tasks="showTasks = true"
-        />
       </div>
-    </header>
-    <FilterBar />
-    <main class="main-content">
-      <router-view />
-    </main>
+    </aside>
+
+    <div class="layout-content">
+      <FilterBar />
+      <main class="main-content">
+        <router-view />
+      </main>
+    </div>
 
     <ProfileDetailsModal
       :is-open="showProfileDetails"
@@ -59,6 +198,7 @@ import { ref, onMounted, computed } from 'vue'
 import { api } from './api'
 import { useAuth } from './composables/useAuth'
 import { useI18n } from './composables/useI18n'
+import { useSidebar } from './composables/useSidebar'
 import FilterBar from './components/FilterBar.vue'
 import ProfileMenu from './components/ProfileMenu.vue'
 import ProfileDetailsModal from './components/ProfileDetailsModal.vue'
@@ -77,6 +217,7 @@ export default {
   setup() {
     const { currentUser } = useAuth()
     const { t } = useI18n()
+    const { isCollapsed, isMobile, toggle } = useSidebar()
     const showProfileDetails = ref(false)
     const showTasks = ref(false)
     const apiTasks = ref([])
@@ -150,6 +291,9 @@ export default {
 
     return {
       t,
+      isCollapsed,
+      isMobile,
+      toggle,
       showProfileDetails,
       showTasks,
       tasks,
@@ -177,100 +321,133 @@ body {
 }
 
 .app {
-  display: flex;
-  flex-direction: column;
+  display: grid;
+  grid-template-columns: 240px 1fr;
   min-height: 100vh;
+  transition: grid-template-columns 200ms ease;
 }
+.app:has(.sidebar.collapsed) { grid-template-columns: 64px 1fr; }
+/* Fallback for browsers without :has — sidebar still works because of its own width transition */
 
-.top-nav {
+.sidebar {
   background: #ffffff;
-  border-bottom: 1px solid #e2e8f0;
-  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.05);
+  border-right: 1px solid #e2e8f0;
+  display: flex;
+  flex-direction: column;
+  width: 240px;
+  transition: width 200ms ease;
+  overflow: hidden;
   position: sticky;
   top: 0;
-  z-index: 100;
-}
-
-.nav-container {
-  max-width: 1600px;
-  margin: 0 auto;
-  display: flex;
-  align-items: center;
-  padding: 0 2rem;
-  height: 70px;
-}
-
-.nav-container > .nav-tabs {
-  margin-left: auto;
-  margin-right: 1rem;
+  height: 100vh;
 }
+.sidebar.collapsed { width: 64px; }
 
-.nav-container > .language-switcher {
-  margin-right: 1rem;
-}
-
-.logo {
+.sidebar-brand {
+  padding: 1.25rem 1rem;
+  border-bottom: 1px solid #e2e8f0;
   display: flex;
   align-items: baseline;
-  gap: 0.75rem;
+  gap: 0.5rem;
+  min-height: 64px;
 }
-
-.logo h1 {
-  font-size: 1.375rem;
+.sidebar-brand h1 {
+  font-size: 1.125rem;
   font-weight: 700;
   color: #0f172a;
   letter-spacing: -0.025em;
+  white-space: nowrap;
 }
-
-.subtitle {
-  font-size: 0.813rem;
+.sidebar-brand .subtitle {
+  font-size: 0.75rem;
   color: #64748b;
-  font-weight: 400;
-  padding-left: 0.75rem;
-  border-left: 1px solid #e2e8f0;
+  white-space: nowrap;
+  transition: opacity 150ms ease;
 }
+.sidebar.collapsed .sidebar-brand { padding: 1.25rem 0.5rem; justify-content: center; }
+.sidebar.collapsed .sidebar-brand .subtitle,
+.sidebar.collapsed .sidebar-brand .logo-full { display: none; }
+.sidebar:not(.collapsed) .sidebar-brand .logo-mark { display: none; }
 
-.nav-tabs {
+.sidebar-toggle {
+  appearance: none;
+  background: transparent;
+  border: 1px solid #e2e8f0;
+  color: #64748b;
+  border-radius: 6px;
+  padding: 0.375rem 0.5rem;
+  margin: 0.75rem;
   display: flex;
-  gap: 0.25rem;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: background 150ms ease, color 150ms ease;
 }
+.sidebar-toggle:hover:not(:disabled) { background: #f1f5f9; color: #0f172a; }
+.sidebar-toggle:disabled { opacity: 0.5; cursor: not-allowed; }
+.sidebar.collapsed .sidebar-toggle { margin: 0.75rem auto; }
 
-.nav-tabs a {
-  padding: 0.625rem 1.25rem;
+.sidebar-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  padding: 0.5rem;
+  flex: 1;
+}
+.sidebar-nav a {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.625rem 0.75rem;
   color: #64748b;
   text-decoration: none;
   font-weight: 500;
   font-size: 0.938rem;
   border-radius: 6px;
-  transition: all 0.2s ease;
-  position: relative;
+  transition: background 150ms ease, color 150ms ease;
+  white-space: nowrap;
+  overflow: hidden;
 }
-
-.nav-tabs a:hover {
-  color: #0f172a;
-  background: #f1f5f9;
+.sidebar-nav a:hover { background: #f1f5f9; color: #0f172a; }
+.sidebar-nav a.active {
+  background: #eff6ff;
+  color: #2563eb;
+}
+.sidebar-nav .nav-icon {
+  flex-shrink: 0;
+  width: 20px;
+  height: 20px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
 }
+.sidebar-nav .nav-label {
+  transition: opacity 150ms ease;
+}
+.sidebar.collapsed .sidebar-nav a { justify-content: center; padding: 0.625rem 0.5rem; }
+.sidebar.collapsed .sidebar-nav .nav-label { opacity: 0; width: 0; }
 
-.nav-tabs a.active {
-  color: #2563eb;
-  background: #eff6ff;
+.sidebar-footer {
+  border-top: 1px solid #e2e8f0;
+  padding: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
 }
+.sidebar.collapsed .sidebar-footer { padding: 0.75rem 0.25rem; }
 
-.nav-tabs a.active::after {
-  content: '';
-  position: absolute;
-  bottom: -1px;
-  left: 0;
-  right: 0;
-  height: 2px;
-  background: #2563eb;
+.layout-content {
+  display: flex;
+  flex-direction: column;
+  min-width: 0; /* allow children to overflow */
 }
 
+/* Keep main-content responsive in the new grid */
 .main-content {
   flex: 1;
-  max-width: 1600px;
   width: 100%;
-  margin: 0 auto;
+  max-width: none; /* was 1600px capped by old layout; now contained by the grid */
+  margin: 0;
   padding: 1.5rem 2rem;
 }
 
diff --git a/client/src/api.js b/client/src/api.js
index 11cb9db7..ef99e692 100644
--- a/client/src/api.js
+++ b/client/src/api.js
@@ -102,5 +102,22 @@ export const api = {
   async getPurchaseOrderByBacklogItem(backlogItemId) {
     const response = await axios.get(`${API_BASE_URL}/purchase-orders/${backlogItemId}`)
     return response.data
+  },
+
+  async getRestockingRecommendations(budget) {
+    const response = await axios.get(`${API_BASE_URL}/restocking/recommendations`, {
+      params: { budget }
+    })
+    return response.data
+  },
+
+  async createRestockingOrder(payload) {
+    const response = await axios.post(`${API_BASE_URL}/restocking-orders`, payload)
+    return response.data
+  },
+
+  async getRestockingOrders() {
+    const response = await axios.get(`${API_BASE_URL}/restocking-orders`)
+    return response.data
   }
 }
diff --git a/client/src/composables/useSidebar.js b/client/src/composables/useSidebar.js
new file mode 100644
index 00000000..5f1a7fd7
--- /dev/null
+++ b/client/src/composables/useSidebar.js
@@ -0,0 +1,67 @@
+import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
+
+const STORAGE_KEY = 'sidebar.collapsed'
+const MOBILE_BREAKPOINT = '(max-width: 1024px)'
+
+// Singleton state shared across components
+const userCollapsed = ref(loadStored())
+const isMobile = ref(false)
+
+function loadStored() {
+  try {
+    return window.localStorage.getItem(STORAGE_KEY) === 'true'
+  } catch {
+    return false
+  }
+}
+
+function persist(value) {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, value ? 'true' : 'false')
+  } catch {
+    // localStorage unavailable (private mode, quota); ignore — state still
+    // works for the session, just won't persist across reloads.
+  }
+}
+
+let mediaQuery = null
+let listener = null
+let mountedCount = 0
+
+export function useSidebar() {
+  // Effective collapsed state: forced when mobile, otherwise user preference.
+  // Mobile force does NOT overwrite the stored preference — when the user
+  // resizes back above the breakpoint, their last manual choice is restored.
+  const isCollapsed = computed(() => isMobile.value || userCollapsed.value)
+
+  const toggle = () => {
+    if (isMobile.value) return  // toggle is a no-op when force-collapsed
+    userCollapsed.value = !userCollapsed.value
+    persist(userCollapsed.value)
+  }
+
+  onMounted(() => {
+    mountedCount += 1
+    if (!mediaQuery) {
+      mediaQuery = window.matchMedia(MOBILE_BREAKPOINT)
+      isMobile.value = mediaQuery.matches
+      listener = (e) => { isMobile.value = e.matches }
+      mediaQuery.addEventListener('change', listener)
+    }
+  })
+
+  onBeforeUnmount(() => {
+    mountedCount -= 1
+    if (mountedCount === 0 && mediaQuery && listener) {
+      mediaQuery.removeEventListener('change', listener)
+      mediaQuery = null
+      listener = null
+    }
+  })
+
+  return {
+    isCollapsed,
+    isMobile,
+    toggle,
+  }
+}
diff --git a/client/src/main.js b/client/src/main.js
index 477c2d96..35668d24 100644
--- a/client/src/main.js
+++ b/client/src/main.js
@@ -4,6 +4,7 @@ import App from './App.vue'
 import Dashboard from './views/Dashboard.vue'
 import Inventory from './views/Inventory.vue'
 import Orders from './views/Orders.vue'
+import Restocking from './views/Restocking.vue'
 import Demand from './views/Demand.vue'
 import Spending from './views/Spending.vue'
 import Reports from './views/Reports.vue'
@@ -14,6 +15,7 @@ const router = createRouter({
     { path: '/', component: Dashboard },
     { path: '/inventory', component: Inventory },
     { path: '/orders', component: Orders },
+    { path: '/restocking', component: Restocking },
     { path: '/demand', component: Demand },
     { path: '/spending', component: Spending },
     { path: '/reports', component: Reports }
diff --git a/client/src/views/Orders.vue b/client/src/views/Orders.vue
index 7413f6e6..67154947 100644
--- a/client/src/views/Orders.vue
+++ b/client/src/views/Orders.vue
@@ -27,6 +27,45 @@
         </div>
       </div>
 
+      <div v-if="submittedOrders.length > 0" class="card restocking-card">
+        <div class="card-header">
+          <h3 class="card-title">Submitted Restocking Orders</h3>
+          <p class="card-subtitle">
+            {{ submittedOrders.length }} {{ submittedOrders.length === 1 ? 'order' : 'orders' }} submitted this session
+          </p>
+        </div>
+        <div class="table-container">
+          <table class="restocking-table">
+            <thead>
+              <tr>
+                <th class="text-left">Order #</th>
+                <th class="text-left">Items</th>
+                <th class="text-right">Total</th>
+                <th class="text-left">Status</th>
+                <th class="text-left">Submitted</th>
+                <th class="text-left">Expected Delivery</th>
+                <th class="text-right">Lead Time</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="ro in submittedOrders" :key="ro.order_number">
+                <td class="mono"><strong>{{ ro.order_number }}</strong></td>
+                <td>{{ ro.items.length }} items</td>
+                <td class="text-right">
+                  <strong>${{ Number(ro.total_cost).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) }}</strong>
+                </td>
+                <td>
+                  <span class="badge-submitted">Submitted</span>
+                </td>
+                <td>{{ shortDate(ro.submitted_at || ro.order_date) }}</td>
+                <td>{{ shortDate(ro.expected_delivery) }}</td>
+                <td class="text-right">{{ ro.lead_time_days }} days</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
       <div class="card">
         <div class="card-header">
           <h3 class="card-title">{{ t('orders.allOrders') }} ({{ orders.length }})</h3>
@@ -95,6 +134,7 @@ export default {
     const loading = ref(true)
     const error = ref(null)
     const orders = ref([])
+    const submittedOrders = ref([])
 
     // Use shared filters
     const {
@@ -124,6 +164,32 @@ export default {
       }
     }
 
+    // Independent fetch for restocking orders — failure here should not break
+    // the main orders view, so we handle errors locally.
+    const loadSubmittedRestockingOrders = async () => {
+      try {
+        const data = await api.getRestockingOrders()
+        submittedOrders.value = Array.isArray(data) ? data : []
+      } catch (err) {
+        // Silent failure: leave list empty so the card simply does not render
+        submittedOrders.value = []
+        console.error('Failed to load restocking orders:', err)
+      }
+    }
+
+    // Short ISO-style date (YYYY-MM-DD) for the restocking orders table
+    const shortDate = (value) => {
+      if (!value) return ''
+      const s = String(value)
+      // If value is already an ISO string, slicing the first 10 chars yields YYYY-MM-DD
+      if (s.length >= 10 && s[4] === '-' && s[7] === '-') {
+        return s.slice(0, 10)
+      }
+      const d = new Date(value)
+      if (isNaN(d.getTime())) return ''
+      return d.toISOString().slice(0, 10)
+    }
+
     // Watch for filter changes and reload data
     watch([selectedPeriod, selectedLocation, selectedCategory, selectedStatus], () => {
       loadOrders()
@@ -153,16 +219,21 @@ export default {
       })
     }
 
-    onMounted(loadOrders)
+    onMounted(() => {
+      // Fire both fetches in parallel; they are independent of each other.
+      Promise.all([loadOrders(), loadSubmittedRestockingOrders()])
+    })
 
     return {
       t,
       loading,
       error,
       orders,
+      submittedOrders,
       getOrdersByStatus,
       getOrderStatusClass,
       formatDate,
+      shortDate,
       currencySymbol,
       translateProductName,
       translateCustomerName
@@ -276,4 +347,66 @@ export default {
   font-size: 0.813rem;
   color: #64748b;
 }
+
+/* Submitted restocking orders card */
+.restocking-card {
+  margin-bottom: 1.5rem;
+}
+
+.card-subtitle {
+  font-size: 0.813rem;
+  color: #64748b;
+  margin: 0.25rem 0 0 0;
+}
+
+.restocking-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+}
+
+.restocking-table thead th {
+  text-align: left;
+  padding: 0.75rem 1rem;
+  background: #f8fafc;
+  color: #475569;
+  font-weight: 600;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.restocking-table tbody td {
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid #f1f5f9;
+  color: #0f172a;
+}
+
+.restocking-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.text-left {
+  text-align: left;
+}
+
+.text-right {
+  text-align: right;
+}
+
+.mono {
+  font-family: 'SFMono-Regular', Menlo, Monaco, Consolas, 'Courier New', monospace;
+  font-size: 0.813rem;
+}
+
+.badge-submitted {
+  display: inline-block;
+  padding: 0.25rem 0.625rem;
+  background: #dbeafe;
+  color: #1d4ed8;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+}
 </style>
diff --git a/client/src/views/Restocking.vue b/client/src/views/Restocking.vue
new file mode 100644
index 00000000..3d2c62a2
--- /dev/null
+++ b/client/src/views/Restocking.vue
@@ -0,0 +1,376 @@
+<template>
+  <div class="restocking">
+    <div class="page-header">
+      <h1>Restocking</h1>
+      <p class="subtitle">Forecast-driven recommendations that fit your budget.</p>
+    </div>
+
+    <!-- Budget card -->
+    <div class="card budget-card">
+      <div class="budget-value">{{ fmtWhole(budget) }}</div>
+      <input
+        type="range"
+        min="10000"
+        max="500000"
+        step="5000"
+        v-model.number="budget"
+        class="budget-slider"
+      />
+      <div class="slider-hints">
+        <span>$10,000</span>
+        <span>$500,000</span>
+      </div>
+    </div>
+
+    <!-- Success banner -->
+    <div v-if="successOrderNumber" class="success-banner">
+      Order {{ successOrderNumber }} submitted &mdash; view in Orders tab
+    </div>
+
+    <!-- Recommendations card -->
+    <div class="card recommendations-card">
+      <div class="card-header">
+        <h3 class="card-title">Recommended Items</h3>
+        <p class="card-subtitle">
+          {{ itemsIncluded }} items totaling {{ fmt(totalCost) }}, {{ fmt(remainingBudget) }} remaining
+        </p>
+      </div>
+
+      <div v-if="loading" class="state-message">Loading recommendations...</div>
+      <div v-else-if="error" class="state-message error">{{ error }}</div>
+      <div v-else-if="recommendations.length === 0" class="state-message">
+        No items need restocking at this budget. Try increasing the budget.
+      </div>
+      <div v-else class="table-container">
+        <table class="recommendations-table">
+          <thead>
+            <tr>
+              <th class="text-left">SKU</th>
+              <th class="text-left">Item</th>
+              <th class="text-left">Category</th>
+              <th class="text-right">Current Stock</th>
+              <th class="text-right">Forecast</th>
+              <th class="text-right">Shortfall</th>
+              <th class="text-right">Qty to Order</th>
+              <th class="text-right">Unit Cost</th>
+              <th class="text-right">Line Total</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="item in recommendations" :key="item.sku">
+              <td class="mono">{{ item.sku }}</td>
+              <td>{{ item.name }}</td>
+              <td>{{ item.category }}</td>
+              <td class="text-right">{{ item.current_stock.toLocaleString() }}</td>
+              <td class="text-right">{{ item.forecasted_demand.toLocaleString() }}</td>
+              <td class="text-right">{{ item.shortfall.toLocaleString() }}</td>
+              <td class="text-right">{{ item.quantity.toLocaleString() }}</td>
+              <td class="text-right">{{ fmt(item.unit_cost) }}</td>
+              <td class="text-right">{{ fmt(item.line_total) }}</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <div class="action-bar">
+        <div class="action-summary">
+          {{ itemsIncluded }} items &middot; {{ fmt(totalCost) }} total &middot; {{ fmt(remainingBudget) }} remaining
+        </div>
+        <button
+          class="submit-btn"
+          :disabled="recommendations.length === 0 || submitting"
+          @click="placeOrder"
+        >
+          {{ submitting ? 'Submitting...' : 'Place Order' }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref, onMounted, watch } from 'vue'
+import { api } from '../api'
+
+export default {
+  name: 'Restocking',
+  setup() {
+    const budget = ref(100000)
+    const recommendations = ref([])
+    const totalCost = ref(0)
+    const remainingBudget = ref(0)
+    const itemsIncluded = ref(0)
+    const loading = ref(false)
+    const submitting = ref(false)
+    const error = ref(null)
+    const successOrderNumber = ref(null)
+
+    // Inline debounce handle (no extra deps)
+    let debounceHandle = null
+
+    const fmt = (n) => {
+      return '$' + Number(n).toLocaleString('en-US', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2
+      })
+    }
+
+    // Whole-dollar formatter for the large budget display (no cents)
+    const fmtWhole = (n) => {
+      return '$' + Number(n).toLocaleString('en-US', {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0
+      })
+    }
+
+    const loadRecommendations = async () => {
+      try {
+        loading.value = true
+        error.value = null
+        const data = await api.getRestockingRecommendations(budget.value)
+        recommendations.value = data.recommendations || []
+        totalCost.value = data.total_cost || 0
+        remainingBudget.value = data.remaining_budget || 0
+        itemsIncluded.value = data.items_included || 0
+      } catch (err) {
+        error.value = 'Failed to load recommendations: ' + (err.message || 'unknown error')
+        recommendations.value = []
+        totalCost.value = 0
+        remainingBudget.value = 0
+        itemsIncluded.value = 0
+      } finally {
+        loading.value = false
+      }
+    }
+
+    const placeOrder = async () => {
+      if (recommendations.value.length === 0) return
+      try {
+        submitting.value = true
+        error.value = null
+        const result = await api.createRestockingOrder({
+          items: recommendations.value,
+          total_cost: totalCost.value
+        })
+        successOrderNumber.value = result.order_number
+        // Re-fetch since stock state may shift after order placement
+        await loadRecommendations()
+      } catch (err) {
+        error.value = 'Failed to submit order: ' + (err.message || 'unknown error')
+      } finally {
+        submitting.value = false
+      }
+    }
+
+    watch(budget, () => {
+      if (debounceHandle) clearTimeout(debounceHandle)
+      debounceHandle = setTimeout(loadRecommendations, 250)
+      successOrderNumber.value = null
+    })
+
+    onMounted(loadRecommendations)
+
+    return {
+      budget,
+      recommendations,
+      totalCost,
+      remainingBudget,
+      itemsIncluded,
+      loading,
+      submitting,
+      error,
+      successOrderNumber,
+      placeOrder,
+      fmt,
+      fmtWhole
+    }
+  }
+}
+</script>
+
+<style scoped>
+.restocking {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 24px;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+  color: #0f172a;
+}
+
+.page-header {
+  margin-bottom: 24px;
+}
+
+.page-header h1 {
+  font-size: 28px;
+  font-weight: 700;
+  color: #0f172a;
+  margin: 0 0 4px 0;
+}
+
+.subtitle {
+  color: #64748b;
+  margin: 0;
+  font-size: 14px;
+}
+
+.card {
+  background: #ffffff;
+  border: 1px solid #e2e8f0;
+  border-radius: 12px;
+  padding: 24px;
+  margin-bottom: 20px;
+}
+
+.budget-card {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.budget-value {
+  font-size: 28px;
+  font-weight: 600;
+  color: #0f172a;
+}
+
+.budget-slider {
+  width: 100%;
+  accent-color: #475569;
+  cursor: pointer;
+}
+
+.slider-hints {
+  display: flex;
+  justify-content: space-between;
+  font-size: 12px;
+  color: #64748b;
+}
+
+.success-banner {
+  background: #f0fdf4;
+  border: 1px solid #16a34a;
+  color: #16a34a;
+  padding: 12px 16px;
+  border-radius: 8px;
+  margin-bottom: 16px;
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.recommendations-card {
+  padding: 0;
+}
+
+.card-header {
+  padding: 20px 24px;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.card-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: #0f172a;
+  margin: 0 0 4px 0;
+}
+
+.card-subtitle {
+  font-size: 13px;
+  color: #64748b;
+  margin: 0;
+}
+
+.state-message {
+  padding: 40px 24px;
+  text-align: center;
+  color: #64748b;
+  font-size: 14px;
+}
+
+.state-message.error {
+  color: #dc2626;
+}
+
+.table-container {
+  overflow-x: auto;
+}
+
+.recommendations-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 14px;
+}
+
+.recommendations-table thead th {
+  text-align: left;
+  padding: 12px 16px;
+  background: #f8fafc;
+  color: #475569;
+  font-weight: 600;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.recommendations-table tbody td {
+  padding: 12px 16px;
+  border-bottom: 1px solid #f1f5f9;
+  color: #0f172a;
+}
+
+.recommendations-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.text-left {
+  text-align: left;
+}
+
+.text-right {
+  text-align: right;
+}
+
+.mono {
+  font-family: 'SFMono-Regular', Menlo, Monaco, Consolas, 'Courier New', monospace;
+  font-size: 13px;
+}
+
+.action-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 24px;
+  border-top: 1px solid #e2e8f0;
+  background: #f8fafc;
+  border-bottom-left-radius: 12px;
+  border-bottom-right-radius: 12px;
+}
+
+.action-summary {
+  color: #64748b;
+  font-size: 14px;
+}
+
+.submit-btn {
+  background: #2563eb;
+  color: #ffffff;
+  border: none;
+  padding: 10px 20px;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+
+.submit-btn:hover:not(:disabled) {
+  background: #1d4ed8;
+}
+
+.submit-btn:disabled {
+  background: #cbd5e1;
+  color: #ffffff;
+  cursor: not-allowed;
+}
+</style>
diff --git a/docs/architecture.html b/docs/architecture.html
new file mode 100644
index 00000000..e61fe4fe
--- /dev/null
+++ b/docs/architecture.html
@@ -0,0 +1,572 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Architecture — Factory Inventory Management System</title>
+<style>
+  :root {
+    --bg: #ffffff;
+    --surface: #f8fafc;
+    --border: #e2e8f0;
+    --text: #0f172a;
+    --muted: #64748b;
+    --accent: #334155;
+    --green: #16a34a;
+    --blue: #2563eb;
+    --yellow: #ca8a04;
+    --red: #dc2626;
+  }
+
+  * { box-sizing: border-box; }
+
+  html, body {
+    margin: 0;
+    padding: 0;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    font-size: 15px;
+    line-height: 1.55;
+  }
+
+  .container {
+    max-width: 1100px;
+    margin: 0 auto;
+    padding: 48px 32px 80px;
+  }
+
+  header.page {
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 24px;
+    margin-bottom: 40px;
+  }
+
+  header.page h1 {
+    margin: 0 0 8px;
+    font-size: 28px;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+  }
+
+  header.page p.tagline {
+    margin: 0 0 16px;
+    color: var(--muted);
+    font-size: 16px;
+  }
+
+  .callout {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 12px;
+    background: #fef3c7;
+    border: 1px solid #fde68a;
+    border-radius: 6px;
+    color: #92400e;
+    font-size: 13px;
+    font-weight: 500;
+  }
+
+  .callout::before {
+    content: "";
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--yellow);
+  }
+
+  section {
+    margin-bottom: 56px;
+  }
+
+  section h2 {
+    font-size: 20px;
+    font-weight: 600;
+    margin: 0 0 4px;
+    letter-spacing: -0.005em;
+  }
+
+  section h2 .sub {
+    font-size: 13px;
+    font-weight: 400;
+    color: var(--muted);
+    margin-left: 10px;
+  }
+
+  section p.section-intro {
+    color: var(--muted);
+    margin: 4px 0 24px;
+    max-width: 720px;
+  }
+
+  /* Tech stack grid */
+  .stack-grid {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 16px;
+  }
+
+  .stack-card {
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 20px 22px;
+    background: var(--surface);
+  }
+
+  .stack-card h3 {
+    margin: 0 0 4px;
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--muted);
+  }
+
+  .stack-card .stack-title {
+    font-size: 16px;
+    font-weight: 600;
+    margin-bottom: 14px;
+  }
+
+  .stack-card ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .stack-card li {
+    padding: 6px 0;
+    font-size: 14px;
+    color: var(--text);
+    border-top: 1px solid var(--border);
+  }
+
+  .stack-card li:first-child {
+    border-top: none;
+  }
+
+  .stack-card li .meta {
+    color: var(--muted);
+    font-size: 12px;
+    margin-left: 6px;
+  }
+
+  /* Diagram containers */
+  .diagram {
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 24px;
+    background: var(--surface);
+    overflow-x: auto;
+  }
+
+  .diagram svg {
+    display: block;
+    margin: 0 auto;
+    max-width: 100%;
+    height: auto;
+  }
+
+  /* Tables */
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    overflow: hidden;
+    font-size: 14px;
+  }
+
+  thead {
+    background: var(--surface);
+  }
+
+  th {
+    text-align: left;
+    padding: 10px 14px;
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--muted);
+    border-bottom: 1px solid var(--border);
+  }
+
+  td {
+    padding: 10px 14px;
+    border-bottom: 1px solid var(--border);
+    vertical-align: top;
+  }
+
+  tbody tr:last-child td {
+    border-bottom: none;
+  }
+
+  td.method {
+    width: 60px;
+    color: var(--green);
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 12px;
+    font-weight: 600;
+  }
+
+  td.path, td.view {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 13px;
+    color: var(--accent);
+    white-space: nowrap;
+  }
+
+  td.filters {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 12px;
+    color: var(--muted);
+  }
+
+  td.purpose {
+    color: var(--text);
+  }
+
+  .note {
+    font-size: 12px;
+    color: var(--muted);
+    margin-top: 10px;
+  }
+
+  /* Filter grid */
+  .filter-grid {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 12px;
+  }
+
+  .filter-card {
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 16px;
+    background: var(--surface);
+  }
+
+  .filter-card h4 {
+    margin: 0 0 6px;
+    font-size: 13px;
+    font-weight: 600;
+  }
+
+  .filter-card p {
+    margin: 0;
+    font-size: 12px;
+    color: var(--muted);
+  }
+
+  code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 0.9em;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    padding: 1px 5px;
+    border-radius: 4px;
+    color: var(--accent);
+  }
+
+  footer.page {
+    margin-top: 64px;
+    padding-top: 20px;
+    border-top: 1px solid var(--border);
+    color: var(--muted);
+    font-size: 12px;
+  }
+
+  @media (max-width: 800px) {
+    .stack-grid, .filter-grid {
+      grid-template-columns: 1fr;
+    }
+  }
+</style>
+</head>
+<body>
+<div class="container">
+
+  <header class="page">
+    <h1>Factory Inventory Management System</h1>
+    <p class="tagline">Full-stack demo: Vue 3 + Vite frontend, FastAPI backend, JSON-backed in-memory store.</p>
+    <span class="callout">Workshop demo — no database, no auth, CORS allow-all</span>
+  </header>
+
+  <!-- =================== TECH STACK =================== -->
+  <section>
+    <h2>Tech Stack <span class="sub">what's in the box</span></h2>
+    <p class="section-intro">Three layers, each independently runnable. The data layer is a set of JSON files loaded into Python memory at startup.</p>
+
+    <div class="stack-grid">
+      <div class="stack-card">
+        <h3>Frontend</h3>
+        <div class="stack-title">client/</div>
+        <ul>
+          <li>Vue 3 <span class="meta">Composition API</span></li>
+          <li>vue-router 4 <span class="meta">createWebHistory</span></li>
+          <li>axios <span class="meta">HTTP client</span></li>
+          <li>Vite 5 <span class="meta">dev server, port 3000</span></li>
+        </ul>
+      </div>
+
+      <div class="stack-card">
+        <h3>Backend</h3>
+        <div class="stack-title">server/</div>
+        <ul>
+          <li>FastAPI <span class="meta">routes + CORS</span></li>
+          <li>Pydantic <span class="meta">response validation</span></li>
+          <li>Uvicorn <span class="meta">ASGI, port 8001</span></li>
+          <li>uv <span class="meta">env + dependencies</span></li>
+        </ul>
+      </div>
+
+      <div class="stack-card">
+        <h3>Data</h3>
+        <div class="stack-title">server/data/</div>
+        <ul>
+          <li>inventory.json <span class="meta">SKUs by warehouse</span></li>
+          <li>orders.json <span class="meta">12 months of orders</span></li>
+          <li>demand_forecasts.json <span class="meta">trend data</span></li>
+          <li>backlog_items.json + purchase_orders.json</li>
+          <li>spending.json + transactions.json</li>
+        </ul>
+      </div>
+    </div>
+  </section>
+
+  <!-- =================== SYSTEM ARCHITECTURE =================== -->
+  <section>
+    <h2>System Architecture <span class="sub">layered view</span></h2>
+    <p class="section-intro">A request from the browser passes through Vue's router and view, into the centralized axios client, across to FastAPI, through the in-memory loader, and finally reaches the static JSON files on disk.</p>
+
+    <div class="diagram">
+      <svg viewBox="0 0 900 520" role="img" aria-label="Layered system architecture diagram">
+        <defs>
+          <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+            <path d="M 0 0 L 10 5 L 0 10 z" fill="#64748b"/>
+          </marker>
+        </defs>
+
+        <!-- Browser layer -->
+        <rect x="40" y="20" width="820" height="70" rx="8" fill="#ffffff" stroke="#e2e8f0" stroke-width="1.5"/>
+        <text x="60" y="50" font-size="11" font-weight="600" fill="#64748b" letter-spacing="1">BROWSER</text>
+        <text x="60" y="72" font-size="14" fill="#0f172a">User navigates routes, clicks FilterBar, fires HTTP requests</text>
+
+        <!-- Frontend layer -->
+        <rect x="40" y="110" width="820" height="120" rx="8" fill="#f8fafc" stroke="#e2e8f0" stroke-width="1.5"/>
+        <text x="60" y="138" font-size="11" font-weight="600" fill="#64748b" letter-spacing="1">FRONTEND — VUE 3 SPA (PORT 3000)</text>
+
+        <rect x="60" y="152" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="180" y="178" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">App.vue + FilterBar</text>
+        <text x="180" y="196" font-size="11" text-anchor="middle" fill="#64748b">global filter state, layout shell</text>
+
+        <rect x="320" y="152" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="440" y="178" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">Router Views</text>
+        <text x="440" y="196" font-size="11" text-anchor="middle" fill="#64748b">Dashboard, Orders, Inventory, etc.</text>
+
+        <rect x="580" y="152" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="700" y="178" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">api.js (axios)</text>
+        <text x="700" y="196" font-size="11" text-anchor="middle" fill="#64748b">URLSearchParams → /api/*</text>
+
+        <!-- Arrow: frontend to backend -->
+        <line x1="450" y1="240" x2="450" y2="278" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)"/>
+        <text x="460" y="265" font-size="11" fill="#64748b">HTTP — JSON over CORS-open</text>
+
+        <!-- Backend layer -->
+        <rect x="40" y="290" width="820" height="120" rx="8" fill="#f8fafc" stroke="#e2e8f0" stroke-width="1.5"/>
+        <text x="60" y="318" font-size="11" font-weight="600" fill="#64748b" letter-spacing="1">BACKEND — FASTAPI (PORT 8001)</text>
+
+        <rect x="60" y="332" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="180" y="358" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">Route handlers</text>
+        <text x="180" y="376" font-size="11" text-anchor="middle" fill="#64748b">main.py — 14 endpoints</text>
+
+        <rect x="320" y="332" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="440" y="358" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">apply_filters() helpers</text>
+        <text x="440" y="376" font-size="11" text-anchor="middle" fill="#64748b">in-memory filtering</text>
+
+        <rect x="580" y="332" width="240" height="60" rx="6" fill="#ffffff" stroke="#cbd5e1"/>
+        <text x="700" y="358" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">Pydantic models</text>
+        <text x="700" y="376" font-size="11" text-anchor="middle" fill="#64748b">InventoryItem, Order, ...</text>
+
+        <!-- Arrow: backend to data -->
+        <line x1="450" y1="420" x2="450" y2="458" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)"/>
+        <text x="460" y="445" font-size="11" fill="#64748b">read at startup (mock_data.py)</text>
+
+        <!-- Data layer -->
+        <rect x="40" y="470" width="820" height="40" rx="8" fill="#ffffff" stroke="#e2e8f0" stroke-width="1.5"/>
+        <text x="60" y="496" font-size="11" font-weight="600" fill="#64748b" letter-spacing="1">DATA</text>
+        <text x="120" y="496" font-size="13" fill="#0f172a">7 JSON files in server/data/ — loaded once into Python lists, no persistence</text>
+      </svg>
+    </div>
+  </section>
+
+  <!-- =================== DATA FLOW =================== -->
+  <section>
+    <h2>Data Flow <span class="sub">filter change → re-render</span></h2>
+    <p class="section-intro">The 4 filters in <code>FilterBar.vue</code> drive the entire app. When any filter changes, the affected views fire fresh API calls; the backend filters in memory and returns Pydantic-validated lists; Vue's computed properties derive display values from the new raw data.</p>
+
+    <div class="diagram">
+      <svg viewBox="0 0 920 280" role="img" aria-label="Data flow from filter change to re-render">
+        <defs>
+          <marker id="arrow2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+            <path d="M 0 0 L 10 5 L 0 10 z" fill="#64748b"/>
+          </marker>
+        </defs>
+
+        <!-- Step boxes -->
+        <g font-family="-apple-system, sans-serif">
+          <!-- 1 -->
+          <rect x="20" y="40" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="90" y="64" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 1</text>
+          <text x="90" y="86" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">FilterBar.vue</text>
+          <text x="90" y="104" font-size="11" text-anchor="middle" fill="#64748b">user changes filter</text>
+
+          <line x1="160" y1="80" x2="195" y2="80" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+          <!-- 2 -->
+          <rect x="200" y="40" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="270" y="64" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 2</text>
+          <text x="270" y="86" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">api.js</text>
+          <text x="270" y="104" font-size="11" text-anchor="middle" fill="#64748b">URLSearchParams</text>
+
+          <line x1="340" y1="80" x2="375" y2="80" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+          <!-- 3 -->
+          <rect x="380" y="40" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="450" y="64" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 3</text>
+          <text x="450" y="86" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">FastAPI route</text>
+          <text x="450" y="104" font-size="11" text-anchor="middle" fill="#64748b">GET /api/orders?...</text>
+
+          <line x1="520" y1="80" x2="555" y2="80" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+          <!-- 4 -->
+          <rect x="560" y="40" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="630" y="64" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 4</text>
+          <text x="630" y="86" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">apply_filters()</text>
+          <text x="630" y="104" font-size="11" text-anchor="middle" fill="#64748b">in-memory match</text>
+
+          <line x1="700" y1="80" x2="735" y2="80" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+          <!-- 5 -->
+          <rect x="740" y="40" width="160" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="820" y="64" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 5</text>
+          <text x="820" y="86" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">Pydantic response</text>
+          <text x="820" y="104" font-size="11" text-anchor="middle" fill="#64748b">JSON array</text>
+
+          <!-- Return arrow -->
+          <path d="M 820 130 L 820 170 L 270 170" fill="none" stroke="#64748b" stroke-width="1.5" stroke-dasharray="4 4" marker-end="url(#arrow2)"/>
+          <text x="545" y="160" font-size="11" text-anchor="middle" fill="#64748b">response — 200 OK</text>
+
+          <!-- 6: computed -->
+          <rect x="200" y="180" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="270" y="204" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 6</text>
+          <text x="270" y="226" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">refs + computed</text>
+          <text x="270" y="244" font-size="11" text-anchor="middle" fill="#64748b">derive view data</text>
+
+          <line x1="195" y1="220" x2="160" y2="220" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow2)"/>
+
+          <!-- 7: re-render -->
+          <rect x="20" y="180" width="140" height="80" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
+          <text x="90" y="204" font-size="11" font-weight="600" text-anchor="middle" fill="#64748b">STEP 7</text>
+          <text x="90" y="226" font-size="13" font-weight="600" text-anchor="middle" fill="#0f172a">DOM re-render</text>
+          <text x="90" y="244" font-size="11" text-anchor="middle" fill="#64748b">tables, charts, KPIs</text>
+        </g>
+      </svg>
+    </div>
+  </section>
+
+  <!-- =================== API ENDPOINTS =================== -->
+  <section>
+    <h2>API Endpoints <span class="sub">server/main.py — 14 routes</span></h2>
+    <p class="section-intro">Every endpoint returns JSON validated by a Pydantic model (where applicable). Query parameters are optional; absence means "no filter for that dimension."</p>
+
+    <table>
+      <thead>
+        <tr>
+          <th>Method</th>
+          <th>Path</th>
+          <th>Filters</th>
+          <th>Purpose</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr><td class="method">GET</td><td class="path">/</td><td class="filters">—</td><td class="purpose">Root health check</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/inventory</td><td class="filters">warehouse, category</td><td class="purpose">List inventory items (SKU, stock, location, cost)</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/inventory/{item_id}</td><td class="filters">—</td><td class="purpose">Single inventory item by SKU</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/orders</td><td class="filters">warehouse, category, status, month</td><td class="purpose">List orders with status and totals</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/orders/{order_id}</td><td class="filters">—</td><td class="purpose">Single order detail</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/demand</td><td class="filters">—</td><td class="purpose">Demand forecasts and trend data</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/backlog</td><td class="filters">—</td><td class="purpose">Backlog items with PO flags</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/dashboard/summary</td><td class="filters">warehouse, category, status, month</td><td class="purpose">KPIs: inventory value, low stock, pending orders, backlog</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/spending/summary</td><td class="filters">—</td><td class="purpose">Procurement, operational, labor, overhead totals</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/spending/monthly</td><td class="filters">—</td><td class="purpose">Spend per month for trend charts</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/spending/categories</td><td class="filters">—</td><td class="purpose">Spend by category breakdown</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/spending/transactions</td><td class="filters">—</td><td class="purpose">Recent transaction records</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/reports/quarterly</td><td class="filters">—</td><td class="purpose">Quarterly performance metrics</td></tr>
+        <tr><td class="method">GET</td><td class="path">/api/reports/monthly-trends</td><td class="filters">—</td><td class="purpose">Monthly order volume and revenue trends</td></tr>
+      </tbody>
+    </table>
+    <p class="note">CORS is wide open (<code>allow_origins=["*"]</code>) — fine for the workshop, not production-safe.</p>
+  </section>
+
+  <!-- =================== FRONTEND ROUTES =================== -->
+  <section>
+    <h2>Frontend Routes <span class="sub">client/src/main.js</span></h2>
+    <p class="section-intro">Vue Router 4 with <code>createWebHistory</code>, registered inline in <code>main.js</code> (no separate router file).</p>
+
+    <table>
+      <thead>
+        <tr>
+          <th>Path</th>
+          <th>View component</th>
+          <th>Purpose</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr><td class="path">/</td><td class="view">views/Dashboard.vue</td><td class="purpose">Top-level KPIs and summary cards</td></tr>
+        <tr><td class="path">/inventory</td><td class="view">views/Inventory.vue</td><td class="purpose">Inventory table across warehouses</td></tr>
+        <tr><td class="path">/orders</td><td class="view">views/Orders.vue</td><td class="purpose">Orders list, filterable by status/month</td></tr>
+        <tr><td class="path">/demand</td><td class="view">views/Demand.vue</td><td class="purpose">Demand forecasts and trend lines</td></tr>
+        <tr><td class="path">/spending</td><td class="view">views/Spending.vue</td><td class="purpose">Spending categories, monthly trends, transactions</td></tr>
+        <tr><td class="path">/reports</td><td class="view">views/Reports.vue</td><td class="purpose">Quarterly and monthly trend reports</td></tr>
+      </tbody>
+    </table>
+    <p class="note"><code>views/Backlog.vue</code> exists in the source tree but is not currently registered in the router — present as a component but unreachable via navigation.</p>
+  </section>
+
+  <!-- =================== FILTER SYSTEM =================== -->
+  <section>
+    <h2>Filter System <span class="sub">4 dimensions, one component</span></h2>
+    <p class="section-intro">The global <code>FilterBar.vue</code> drives every filterable endpoint. Selection state lives in a shared composable; affected views watch it and re-fetch via <code>api.js</code>. Each filter maps to a single query-string param.</p>
+
+    <div class="filter-grid">
+      <div class="filter-card">
+        <h4>Time Period</h4>
+        <p>Month / quarter — applies to orders, dashboard summary, spending trends.</p>
+      </div>
+      <div class="filter-card">
+        <h4>Warehouse</h4>
+        <p>Filters inventory, orders, dashboard summary by physical location.</p>
+      </div>
+      <div class="filter-card">
+        <h4>Category</h4>
+        <p>Circuit Boards, Sensors, Actuators, Controllers — applies to inventory, orders, dashboard.</p>
+      </div>
+      <div class="filter-card">
+        <h4>Order Status</h4>
+        <p>Delivered, Shipped, Processing, Backordered — applies to orders and dashboard.</p>
+      </div>
+    </div>
+    <p class="note">Inventory has no time dimension, so the time-period filter is a no-op for <code>/api/inventory</code>. Demand and backlog endpoints ignore all four filters.</p>
+  </section>
+
+  <footer class="page">
+    Generated reference for the inventory-management workshop demo. Source of truth: <code>server/main.py</code>, <code>client/src/main.js</code>, <code>client/src/api.js</code>.
+  </footer>
+
+</div>
+</body>
+</html>
diff --git a/server/data/demand_forecasts.json b/server/data/demand_forecasts.json
index e1b38838..ba64ead8 100644
--- a/server/data/demand_forecasts.json
+++ b/server/data/demand_forecasts.json
@@ -1,82 +1,82 @@
 [
   {
     "id": "1",
-    "item_sku": "WDG-001",
-    "item_name": "Industrial Widget Type A",
-    "current_demand": 300,
-    "forecasted_demand": 450,
+    "item_sku": "PCB-001",
+    "item_name": "Single Layer PCB Assembly",
+    "current_demand": 380,
+    "forecasted_demand": 700,
     "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "2",
-    "item_sku": "BRG-102",
-    "item_name": "Steel Bearing Assembly",
-    "current_demand": 150,
-    "forecasted_demand": 152,
-    "trend": "stable",
+    "item_sku": "PCB-003",
+    "item_name": "Multi Layer PCB Assembly",
+    "current_demand": 240,
+    "forecasted_demand": 500,
+    "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "3",
-    "item_sku": "GSK-203",
-    "item_name": "High-Temperature Gasket",
-    "current_demand": 500,
-    "forecasted_demand": 600,
+    "item_sku": "TMP-201",
+    "item_name": "Temperature Sensor Module",
+    "current_demand": 130,
+    "forecasted_demand": 250,
     "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "4",
-    "item_sku": "MTR-304",
-    "item_name": "Electric Motor 5HP",
-    "current_demand": 50,
-    "forecasted_demand": 35,
-    "trend": "decreasing",
+    "item_sku": "HMD-202",
+    "item_name": "Humidity Sensor Module",
+    "current_demand": 90,
+    "forecasted_demand": 200,
+    "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "5",
-    "item_sku": "FLT-405",
-    "item_name": "Oil Filter Cartridge",
-    "current_demand": 800,
-    "forecasted_demand": 950,
-    "trend": "increasing",
+    "item_sku": "SRV-301",
+    "item_name": "Micro Servo Motor",
+    "current_demand": 60,
+    "forecasted_demand": 90,
+    "trend": "stable",
     "period": "Next 30 days"
   },
   {
     "id": "6",
-    "item_sku": "VLV-506",
-    "item_name": "Pressure Relief Valve",
-    "current_demand": 120,
-    "forecasted_demand": 121,
+    "item_sku": "SRV-302",
+    "item_name": "Standard Servo Motor",
+    "current_demand": 40,
+    "forecasted_demand": 60,
     "trend": "stable",
     "period": "Next 30 days"
   },
   {
     "id": "7",
-    "item_sku": "PSU-501",
-    "item_name": "5V 10A Switching Power Supply",
-    "current_demand": 250,
-    "forecasted_demand": 252,
-    "trend": "stable",
+    "item_sku": "MCU-401",
+    "item_name": "8-bit Microcontroller",
+    "current_demand": 1100,
+    "forecasted_demand": 1500,
+    "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "8",
-    "item_sku": "SNR-420",
-    "item_name": "Temperature Sensor Module",
-    "current_demand": 180,
-    "forecasted_demand": 182,
-    "trend": "stable",
+    "item_sku": "DSP-403",
+    "item_name": "Digital Signal Processor",
+    "current_demand": 720,
+    "forecasted_demand": 1100,
+    "trend": "increasing",
     "period": "Next 30 days"
   },
   {
     "id": "9",
-    "item_sku": "CTL-330",
-    "item_name": "Logic Controller Board",
-    "current_demand": 95,
-    "forecasted_demand": 96,
+    "item_sku": "PSU-501",
+    "item_name": "5V 10A Switching Power Supply",
+    "current_demand": 280,
+    "forecasted_demand": 300,
     "trend": "stable",
     "period": "Next 30 days"
   }
diff --git a/server/main.py b/server/main.py
index a0c2d8c5..c92134f5 100644
--- a/server/main.py
+++ b/server/main.py
@@ -2,7 +2,12 @@
 from fastapi.middleware.cors import CORSMiddleware
 from typing import List, Optional
 from pydantic import BaseModel
-from mock_data import inventory_items, orders, demand_forecasts, backlog_items, spending_summary, monthly_spending, category_spending, recent_transactions, purchase_orders
+from datetime import datetime, timedelta
+from mock_data import (
+    inventory_items, orders, demand_forecasts, backlog_items,
+    spending_summary, monthly_spending, category_spending,
+    recent_transactions, purchase_orders, submitted_restocking_orders,
+)
 
 app = FastAPI(title="Factory Inventory Management System")
 
@@ -14,6 +19,17 @@
     'Q4-2025': ['2025-10', '2025-11', '2025-12']
 }
 
+# Restocking delivery lead time per category, in days. The longest lead time
+# across an order's items determines the order's expected delivery date —
+# a multi-category order only completes once its slowest item arrives.
+LEAD_TIMES_BY_CATEGORY = {
+    "Circuit Boards": 14,
+    "Controllers": 10,
+    "Actuators": 7,
+    "Sensors": 5,
+}
+DEFAULT_LEAD_TIME_DAYS = 10
+
 def filter_by_month(items: list, month: Optional[str]) -> list:
     """Filter items by month/quarter based on order_date field"""
     if not month or month == 'all':
@@ -120,6 +136,28 @@ class CreatePurchaseOrderRequest(BaseModel):
     expected_delivery_date: str
     notes: Optional[str] = None
 
+class RestockingOrderItem(BaseModel):
+    sku: str
+    name: str
+    category: str
+    quantity: int
+    unit_cost: float
+    line_total: float
+
+class RestockingOrder(BaseModel):
+    id: str
+    order_number: str
+    items: List[RestockingOrderItem]
+    total_cost: float
+    status: str
+    submitted_date: str
+    expected_delivery_date: str
+    lead_time_days: int
+
+class CreateRestockingOrderRequest(BaseModel):
+    items: List[RestockingOrderItem]
+    total_cost: float
+
 # API endpoints
 @app.get("/")
 def root():
@@ -304,6 +342,102 @@ def get_monthly_trends():
     result.sort(key=lambda x: x['month'])
     return result
 
+@app.get("/api/restocking/recommendations")
+def get_restocking_recommendations(budget: float = 0):
+    """Recommend items to restock under a given budget.
+
+    Joins demand_forecasts with inventory_items on SKU, computes shortfall
+    (forecasted_demand - quantity_on_hand), ranks shortfalls descending, then
+    greedily picks items whose full shortfall line cost still fits the budget.
+    Greedy fit is fine here — a tight budget may leave change on the table.
+    """
+    if budget < 0:
+        raise HTTPException(status_code=400, detail="budget must be non-negative")
+
+    inventory_by_sku = {item['sku']: item for item in inventory_items}
+
+    candidates = []
+    for forecast in demand_forecasts:
+        inv = inventory_by_sku.get(forecast['item_sku'])
+        if not inv:
+            continue
+        shortfall = forecast['forecasted_demand'] - inv['quantity_on_hand']
+        if shortfall <= 0:
+            continue
+        unit_cost = inv['unit_cost']
+        candidates.append({
+            'sku': inv['sku'],
+            'name': inv['name'],
+            'category': inv['category'],
+            'current_stock': inv['quantity_on_hand'],
+            'forecasted_demand': forecast['forecasted_demand'],
+            'shortfall': shortfall,
+            'quantity': shortfall,
+            'unit_cost': unit_cost,
+            'line_total': round(shortfall * unit_cost, 2),
+        })
+
+    # Largest shortfall first; ties broken by smaller line_total (cheap-to-fix
+    # wins so the budget reaches more items).
+    candidates.sort(key=lambda c: (-c['shortfall'], c['line_total']))
+
+    remaining = budget
+    picks = []
+    for c in candidates:
+        if c['line_total'] <= remaining:
+            picks.append(c)
+            remaining -= c['line_total']
+
+    total_cost = round(sum(p['line_total'] for p in picks), 2)
+    return {
+        'budget': budget,
+        'recommendations': picks,
+        'total_cost': total_cost,
+        'items_included': len(picks),
+        'remaining_budget': round(budget - total_cost, 2),
+    }
+
+@app.post("/api/restocking-orders", response_model=RestockingOrder)
+def create_restocking_order(request: CreateRestockingOrderRequest):
+    """Submit a restocking order. Expected delivery uses the longest per-category
+    lead time among the order's items — the whole order completes when its
+    slowest line arrives."""
+    if not request.items:
+        raise HTTPException(status_code=400, detail="order must include at least one item")
+
+    lead_time_days = max(
+        (LEAD_TIMES_BY_CATEGORY.get(item.category, DEFAULT_LEAD_TIME_DAYS) for item in request.items),
+        default=DEFAULT_LEAD_TIME_DAYS,
+    )
+
+    submitted_dt = datetime.utcnow()
+    expected_dt = submitted_dt + timedelta(days=lead_time_days)
+    submitted_iso = submitted_dt.replace(microsecond=0).isoformat()
+    expected_iso = expected_dt.replace(microsecond=0).isoformat()
+
+    year = submitted_dt.year
+    sequence = len(submitted_restocking_orders) + 1
+    order_number = f"RST-{year}-{sequence:04d}"
+
+    order = RestockingOrder(
+        id=str(sequence),
+        order_number=order_number,
+        items=request.items,
+        total_cost=round(request.total_cost, 2),
+        status="Submitted",
+        submitted_date=submitted_iso,
+        expected_delivery_date=expected_iso,
+        lead_time_days=lead_time_days,
+    )
+
+    submitted_restocking_orders.append(order.model_dump())
+    return order
+
+@app.get("/api/restocking-orders", response_model=List[RestockingOrder])
+def get_restocking_orders():
+    """List submitted restocking orders, newest first."""
+    return list(reversed(submitted_restocking_orders))
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host="0.0.0.0", port=8001)
diff --git a/server/mock_data.py b/server/mock_data.py
index 2a9cd7dc..b7e97d72 100644
--- a/server/mock_data.py
+++ b/server/mock_data.py
@@ -35,5 +35,9 @@ def load_json_file(filename):
 # Load purchase orders
 purchase_orders = load_json_file('purchase_orders.json')
 
+# In-memory restocking orders created at runtime. Not persisted across server
+# restarts — restocking is a workshop demo flow with no backing JSON file.
+submitted_restocking_orders = []
+
 # All data is now loaded from JSON files in the data/ directory
 # This allows for easier maintenance and updates of the sample data