diff --git a/client/src/App.vue b/client/src/App.vue
index c2da05a5c..91c3f2785 100644
--- a/client/src/App.vue
+++ b/client/src/App.vue
@@ -1,42 +1,41 @@
 <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>
-        </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>
+  <div class="app-shell">
+    <AppSidebar
+      :nav-items="navItems"
+      v-model:collapsed="sidebarCollapsed"
+      v-model:mobile-open="mobileNavOpen"
+    >
+      <template #brand>
+        <h1 class="sidebar-brand-label">{{ t('nav.companyName') }}</h1>
+        <span class="sidebar-brand-subtitle">{{ t('nav.subtitle') }}</span>
+      </template>
+      <template #footer>
         <LanguageSwitcher />
         <ProfileMenu
           @show-profile-details="showProfileDetails = true"
           @show-tasks="showTasks = true"
         />
+      </template>
+    </AppSidebar>
+
+    <div class="app-content">
+      <div class="content-topbar">
+        <button
+          type="button"
+          class="mobile-nav-toggle"
+          aria-label="Open navigation"
+          @click="mobileNavOpen = true"
+        >
+          <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+            <path d="M3 6H17M3 10H17M3 14H17" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+          </svg>
+        </button>
+        <FilterBar />
       </div>
-    </header>
-    <FilterBar />
-    <main class="main-content">
-      <router-view />
-    </main>
+      <main class="main-content">
+        <router-view />
+      </main>
+    </div>
 
     <ProfileDetailsModal
       :is-open="showProfileDetails"
@@ -64,6 +63,7 @@ import ProfileMenu from './components/ProfileMenu.vue'
 import ProfileDetailsModal from './components/ProfileDetailsModal.vue'
 import TasksModal from './components/TasksModal.vue'
 import LanguageSwitcher from './components/LanguageSwitcher.vue'
+import AppSidebar from './components/AppSidebar.vue'
 
 export default {
   name: 'App',
@@ -72,7 +72,8 @@ export default {
     ProfileMenu,
     ProfileDetailsModal,
     TasksModal,
-    LanguageSwitcher
+    LanguageSwitcher,
+    AppSidebar
   },
   setup() {
     const { currentUser } = useAuth()
@@ -80,6 +81,19 @@ export default {
     const showProfileDetails = ref(false)
     const showTasks = ref(false)
     const apiTasks = ref([])
+    const sidebarCollapsed = ref(false)
+    const mobileNavOpen = ref(false)
+
+    // Derived directly from the app's real routes (see main.js) — never
+    // hardcode this list separately from the router config.
+    const navItems = computed(() => [
+      { key: 'dashboard', label: t('nav.overview'), to: '/', icon: 'overview', exact: true },
+      { key: 'inventory', label: t('nav.inventory'), to: '/inventory', icon: 'inventory' },
+      { key: 'orders', label: t('nav.orders'), to: '/orders', icon: 'orders' },
+      { key: 'spending', label: t('nav.finance'), to: '/spending', icon: 'finance' },
+      { key: 'demand', label: t('nav.demandForecast'), to: '/demand', icon: 'demand' },
+      { key: 'reports', label: 'Reports', to: '/reports', icon: 'reports' }
+    ])
 
     // Merge mock tasks from currentUser with API tasks
     const tasks = computed(() => {
@@ -155,7 +169,10 @@ export default {
       tasks,
       addTask,
       deleteTask,
-      toggleTask
+      toggleTask,
+      sidebarCollapsed,
+      mobileNavOpen,
+      navItems
     }
   }
 }
@@ -176,101 +193,95 @@ body {
   -moz-osx-font-smoothing: grayscale;
 }
 
-.app {
+:root {
+  /* Spacing scale (4px base) — introduced fresh, this app had no prior scale */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-10: 40px;
+  --space-12: 48px;
+  --space-16: 64px;
+
+  /* Sidebar layout */
+  --sidebar-width-expanded: 240px;
+  --sidebar-width-collapsed: 64px;
+  --sidebar-transition: 180ms ease;
+  --topbar-height: 60px;
+  --z-sidebar: 100;
+  --z-sidebar-backdrop: 90;
+}
+
+.app-shell {
   display: flex;
-  flex-direction: column;
   min-height: 100vh;
 }
 
-.top-nav {
-  background: #ffffff;
-  border-bottom: 1px solid #e2e8f0;
-  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.05);
-  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;
-}
-
-.nav-container > .language-switcher {
-  margin-right: 1rem;
-}
-
-.logo {
-  display: flex;
-  align-items: baseline;
-  gap: 0.75rem;
-}
-
-.logo h1 {
-  font-size: 1.375rem;
+/* Content passed into AppSidebar's #brand slot renders with this file's
+   (global) style scope, not AppSidebar's scoped styles, so it needs its
+   own rules here even though the class names mirror AppSidebar's. */
+.sidebar-brand-label {
+  display: block;
+  font-size: 1.125rem;
   font-weight: 700;
   color: #0f172a;
   letter-spacing: -0.025em;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
-.subtitle {
-  font-size: 0.813rem;
+.sidebar-brand-subtitle {
+  display: block;
+  font-size: 0.75rem;
   color: #64748b;
   font-weight: 400;
-  padding-left: 0.75rem;
-  border-left: 1px solid #e2e8f0;
+  white-space: nowrap;
 }
 
-.nav-tabs {
+.app-content {
+  flex: 1;
+  min-width: 0;
   display: flex;
-  gap: 0.25rem;
+  flex-direction: column;
 }
 
-.nav-tabs a {
-  padding: 0.625rem 1.25rem;
-  color: #64748b;
-  text-decoration: none;
-  font-weight: 500;
-  font-size: 0.938rem;
-  border-radius: 6px;
-  transition: all 0.2s ease;
-  position: relative;
+.content-topbar {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  background: #f8fafc;
 }
 
-.nav-tabs a:hover {
-  color: #0f172a;
-  background: #f1f5f9;
+.mobile-nav-toggle {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--topbar-height);
+  height: var(--topbar-height);
+  flex-shrink: 0;
+  border: none;
+  background: transparent;
+  color: #334155;
+  cursor: pointer;
 }
 
-.nav-tabs a.active {
-  color: #2563eb;
-  background: #eff6ff;
+.mobile-nav-toggle:hover {
+  background: #f1f5f9;
 }
 
-.nav-tabs a.active::after {
-  content: '';
-  position: absolute;
-  bottom: -1px;
-  left: 0;
-  right: 0;
-  height: 2px;
-  background: #2563eb;
+@media (max-width: 768px) {
+  .mobile-nav-toggle {
+    display: flex;
+  }
 }
 
 .main-content {
   flex: 1;
-  max-width: 1600px;
   width: 100%;
-  margin: 0 auto;
   padding: 1.5rem 2rem;
 }
 
diff --git a/client/src/components/AppSidebar.vue b/client/src/components/AppSidebar.vue
new file mode 100644
index 000000000..a95daffeb
--- /dev/null
+++ b/client/src/components/AppSidebar.vue
@@ -0,0 +1,325 @@
+<template>
+  <div
+    v-if="mobileOpen"
+    class="sidebar-backdrop"
+    @click="setMobileOpen(false)"
+  ></div>
+
+  <aside
+      class="sidebar"
+      :class="{ collapsed: effectiveCollapsed, 'mobile-open': mobileOpen }"
+    >
+      <div class="sidebar-brand">
+        <slot name="brand">
+          <span class="sidebar-brand-label">{{ brandLabel }}</span>
+          <span v-if="brandSubtitle" class="sidebar-brand-subtitle">{{ brandSubtitle }}</span>
+        </slot>
+
+        <button
+          v-if="!isCompactViewport"
+          type="button"
+          class="sidebar-collapse-toggle"
+          :aria-expanded="!collapsed"
+          :aria-label="collapsed ? 'Expand sidebar' : 'Collapse sidebar'"
+          @click="toggleCollapsed"
+        >
+          <span aria-hidden="true">{{ collapsed ? '»' : '«' }}</span>
+        </button>
+      </div>
+
+      <nav class="sidebar-nav" aria-label="Primary">
+        <ul class="sidebar-list">
+          <li v-for="item in navItems" :key="item.key">
+            <router-link
+              :to="item.to"
+              class="sidebar-link"
+              :class="{ active: isActive(item) }"
+              :title="effectiveCollapsed ? item.label : null"
+              @click="onNavigate(item)"
+            >
+              <span class="sidebar-link-icon" aria-hidden="true">
+                <NavIcon :name="item.icon" />
+              </span>
+              <span v-if="!effectiveCollapsed" class="sidebar-link-label">{{ item.label }}</span>
+            </router-link>
+          </li>
+        </ul>
+      </nav>
+
+      <div class="sidebar-footer">
+        <slot name="footer"></slot>
+      </div>
+  </aside>
+</template>
+
+<script setup>
+import { computed, onMounted, onBeforeUnmount, ref } from 'vue'
+import { useRoute } from 'vue-router'
+import NavIcon from './NavIcon.vue'
+
+const props = defineProps({
+  navItems: {
+    type: Array,
+    required: true
+  },
+  collapsed: {
+    type: Boolean,
+    default: false
+  },
+  mobileOpen: {
+    type: Boolean,
+    default: false
+  },
+  brandLabel: {
+    type: String,
+    default: ''
+  },
+  brandSubtitle: {
+    type: String,
+    default: ''
+  },
+  storageKey: {
+    type: String,
+    default: 'app-sidebar-collapsed'
+  }
+})
+
+const emit = defineEmits(['update:collapsed', 'update:mobileOpen', 'navigate'])
+
+const route = useRoute()
+
+// Between the mobile drawer breakpoint (768px) and full desktop width, the
+// sidebar automatically switches to icon-only mode regardless of the user's
+// manual collapse preference — there isn't enough room for a labeled rail
+// alongside typical page content at these widths. The collapse toggle is
+// hidden in this range since the state isn't user-controlled there.
+const COMPACT_MEDIA_QUERY = '(min-width: 769px) and (max-width: 1099px)'
+const isCompactViewport = ref(false)
+let compactMediaQueryList = null
+
+function updateCompactViewport(event) {
+  isCompactViewport.value = event.matches
+}
+
+onMounted(() => {
+  compactMediaQueryList = window.matchMedia(COMPACT_MEDIA_QUERY)
+  isCompactViewport.value = compactMediaQueryList.matches
+  compactMediaQueryList.addEventListener('change', updateCompactViewport)
+})
+
+onBeforeUnmount(() => {
+  compactMediaQueryList?.removeEventListener('change', updateCompactViewport)
+})
+
+// On mobile, the sidebar opens as a full-width overlay drawer — collapse
+// (icon-only) mode is a desktop-only concept, so ignore `collapsed` while
+// the mobile drawer is open. In the compact viewport range, icon-only mode
+// is forced regardless of the user's stored preference.
+const effectiveCollapsed = computed(() => (props.collapsed || isCompactViewport.value) && !props.mobileOpen)
+
+function isActive(item) {
+  if (item.exact || item.to === '/') {
+    return route.path === item.to
+  }
+  return route.path === item.to || route.path.startsWith(item.to + '/')
+}
+
+function toggleCollapsed() {
+  const next = !props.collapsed
+  emit('update:collapsed', next)
+  try {
+    localStorage.setItem(props.storageKey, String(next))
+  } catch (err) {
+    // localStorage may be unavailable — collapse still works for the session.
+  }
+}
+
+function setMobileOpen(value) {
+  emit('update:mobileOpen', value)
+}
+
+function onNavigate(item) {
+  emit('navigate', item)
+  if (props.mobileOpen) {
+    setMobileOpen(false)
+  }
+}
+
+onMounted(() => {
+  try {
+    const stored = localStorage.getItem(props.storageKey)
+    if (stored !== null) {
+      emit('update:collapsed', stored === 'true')
+    }
+  } catch (err) {
+    // localStorage may be unavailable — fall back to the collapsed prop.
+  }
+})
+</script>
+
+<style scoped>
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  width: var(--sidebar-width-expanded);
+  height: 100vh;
+  position: sticky;
+  top: 0;
+  flex-shrink: 0;
+  background: #ffffff;
+  border-right: 1px solid #e2e8f0;
+  transition: width var(--sidebar-transition);
+  overflow-x: hidden;
+  z-index: var(--z-sidebar);
+}
+
+.sidebar.collapsed {
+  width: var(--sidebar-width-collapsed);
+}
+
+.sidebar-brand {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-4);
+  min-height: var(--topbar-height);
+  flex-shrink: 0;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.sidebar-brand-label {
+  font-size: 1.125rem;
+  font-weight: 700;
+  color: #0f172a;
+  letter-spacing: -0.025em;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.sidebar-brand-subtitle {
+  font-size: 0.75rem;
+  color: #64748b;
+  white-space: nowrap;
+  display: block;
+}
+
+.sidebar-collapse-toggle {
+  margin-left: auto;
+  border: 1px solid #e2e8f0;
+  background: white;
+  color: #64748b;
+  cursor: pointer;
+  padding: var(--space-1) var(--space-2);
+  border-radius: 6px;
+  flex-shrink: 0;
+}
+
+.sidebar-collapse-toggle:hover {
+  background: #f1f5f9;
+  color: #0f172a;
+}
+
+.sidebar-nav {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--space-2);
+}
+
+.sidebar-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.sidebar-link {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-4);
+  border-radius: 8px;
+  text-decoration: none;
+  color: #64748b;
+  font-weight: 500;
+  font-size: 0.938rem;
+  white-space: nowrap;
+  transition: all 0.2s ease;
+}
+
+.sidebar-link:hover {
+  color: #0f172a;
+  background: #f1f5f9;
+}
+
+.sidebar-link.active {
+  color: #2563eb;
+  background: #eff6ff;
+  font-weight: 600;
+}
+
+.sidebar-link-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  flex-shrink: 0;
+}
+
+.sidebar-link-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.sidebar.collapsed .sidebar-link {
+  justify-content: center;
+  padding-left: var(--space-2);
+  padding-right: var(--space-2);
+}
+
+.sidebar-footer {
+  flex-shrink: 0;
+  padding: var(--space-3);
+  border-top: 1px solid #e2e8f0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.sidebar-backdrop {
+  display: none;
+}
+
+@media (max-width: 768px) {
+  .sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    transform: translateX(-100%);
+    transition: transform var(--sidebar-transition);
+    width: var(--sidebar-width-expanded);
+  }
+
+  .sidebar.mobile-open {
+    transform: translateX(0);
+  }
+
+  .sidebar-backdrop {
+    display: block;
+    position: fixed;
+    inset: 0;
+    background: rgba(15, 23, 42, 0.4);
+    z-index: var(--z-sidebar-backdrop);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sidebar,
+  .sidebar-collapse-toggle {
+    transition: none;
+  }
+}
+</style>
diff --git a/client/src/components/FilterBar.vue b/client/src/components/FilterBar.vue
index 9e12b6945..ffb98238a 100644
--- a/client/src/components/FilterBar.vue
+++ b/client/src/components/FilterBar.vue
@@ -102,17 +102,17 @@ export default {
 
 <style scoped>
 .filters-bar {
+  flex: 1;
   background: #f8fafc;
   border-bottom: 1px solid #e2e8f0;
   padding: 0.75rem 0;
   position: sticky;
-  top: 70px;
+  top: 0;
   z-index: 90;
 }
 
 .filters-container {
-  max-width: 1600px;
-  margin: 0 auto;
+  width: 100%;
   padding: 0 2rem;
   display: flex;
   align-items: center;
diff --git a/client/src/components/LanguageSwitcher.vue b/client/src/components/LanguageSwitcher.vue
index dde97df19..a54805192 100644
--- a/client/src/components/LanguageSwitcher.vue
+++ b/client/src/components/LanguageSwitcher.vue
@@ -94,6 +94,7 @@ const selectLanguage = (locale) => {
 }
 
 .language-button {
+  width: 100%;
   display: flex;
   align-items: center;
   gap: 0.5rem;
@@ -108,6 +109,7 @@ const selectLanguage = (locale) => {
   color: #334155;
 }
 
+
 .language-button:hover {
   background: #f8fafc;
   border-color: #cbd5e1;
@@ -119,6 +121,8 @@ const selectLanguage = (locale) => {
 }
 
 .language-label {
+  flex: 1;
+  text-align: left;
   font-weight: 500;
 }
 
@@ -134,8 +138,8 @@ const selectLanguage = (locale) => {
 
 .dropdown-menu {
   position: absolute;
-  top: calc(100% + 0.5rem);
-  right: 0;
+  bottom: calc(100% + 0.5rem);
+  left: 0;
   min-width: 160px;
   background: white;
   border: 1px solid #e2e8f0;
diff --git a/client/src/components/NavIcon.vue b/client/src/components/NavIcon.vue
new file mode 100644
index 000000000..538aab019
--- /dev/null
+++ b/client/src/components/NavIcon.vue
@@ -0,0 +1,49 @@
+<template>
+  <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+    <template v-if="name === 'overview'">
+      <rect x="2.5" y="2.5" width="6" height="6" rx="1" stroke="currentColor" stroke-width="1.5"/>
+      <rect x="11.5" y="2.5" width="6" height="6" rx="1" stroke="currentColor" stroke-width="1.5"/>
+      <rect x="2.5" y="11.5" width="6" height="6" rx="1" stroke="currentColor" stroke-width="1.5"/>
+      <rect x="11.5" y="11.5" width="6" height="6" rx="1" stroke="currentColor" stroke-width="1.5"/>
+    </template>
+
+    <template v-else-if="name === 'inventory'">
+      <path d="M3 6.5L10 3L17 6.5V13.5L10 17L3 13.5V6.5Z" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/>
+      <path d="M3 6.5L10 10L17 6.5" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/>
+      <path d="M10 10V17" stroke="currentColor" stroke-width="1.5"/>
+    </template>
+
+    <template v-else-if="name === 'orders'">
+      <rect x="4" y="3" width="12" height="14.5" rx="1.5" stroke="currentColor" stroke-width="1.5"/>
+      <path d="M7.5 3V2.5C7.5 2 7.9 1.5 8.5 1.5H11.5C12.1 1.5 12.5 2 12.5 2.5V3" stroke="currentColor" stroke-width="1.5"/>
+      <path d="M7 9H13M7 12H13M7 15H10.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+    </template>
+
+    <template v-else-if="name === 'finance'">
+      <circle cx="10" cy="10" r="7.5" stroke="currentColor" stroke-width="1.5"/>
+      <path d="M10 5.5V14.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+      <path d="M12.5 7.5C12.5 6.5 11.4 6 10 6C8.6 6 7.5 6.7 7.5 7.7C7.5 8.7 8.4 9.1 10 9.5C11.7 9.9 12.5 10.3 12.5 11.3C12.5 12.3 11.4 13 10 13C8.6 13 7.5 12.5 7.5 11.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+    </template>
+
+    <template v-else-if="name === 'demand'">
+      <path d="M3 14.5L8 9.5L11 12.5L17 6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+      <path d="M13 6H17V10" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </template>
+
+    <template v-else-if="name === 'reports'">
+      <rect x="4" y="2" width="12" height="16" rx="1.5" stroke="currentColor" stroke-width="1.5"/>
+      <path d="M7 11.5V14.5M10 8.5V14.5M13 10V14.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+    </template>
+
+    <circle v-else cx="10" cy="10" r="3" fill="currentColor"/>
+  </svg>
+</template>
+
+<script setup>
+defineProps({
+  name: {
+    type: String,
+    default: null
+  }
+})
+</script>
diff --git a/client/src/components/ProfileMenu.vue b/client/src/components/ProfileMenu.vue
index 5706d24cf..92e70e4cf 100644
--- a/client/src/components/ProfileMenu.vue
+++ b/client/src/components/ProfileMenu.vue
@@ -121,6 +121,7 @@ const handleLogout = () => {
 }
 
 .profile-button {
+  width: 100%;
   display: flex;
   align-items: center;
   gap: 0.625rem;
@@ -153,6 +154,11 @@ const handleLogout = () => {
 }
 
 .profile-name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-align: left;
   font-size: 0.875rem;
   font-weight: 500;
   color: #0f172a;
@@ -169,8 +175,8 @@ const handleLogout = () => {
 
 .dropdown-menu {
   position: absolute;
-  top: calc(100% + 0.5rem);
-  right: 0;
+  bottom: calc(100% + 0.5rem);
+  left: 0;
   min-width: 280px;
   background: white;
   border: 1px solid #e2e8f0;
diff --git a/docs/architecture.html b/docs/architecture.html
new file mode 100644
index 000000000..accf83c7b
--- /dev/null
+++ b/docs/architecture.html
@@ -0,0 +1,366 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Factory Inventory Management System — Architecture</title>
+<style>
+  :root {
+    --ink: #0f172a;
+    --sub: #475569;
+    --muted: #64748b;
+    --border: #e2e8f0;
+    --bg: #f8fafc;
+    --card: #ffffff;
+    --blue: #2563eb;
+    --blue-bg: #eff6ff;
+    --green: #16a34a;
+    --green-bg: #f0fdf4;
+    --amber: #d97706;
+    --amber-bg: #fffbeb;
+    --purple: #7c3aed;
+    --purple-bg: #f5f3ff;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    color: var(--ink);
+    background: var(--bg);
+    line-height: 1.5;
+  }
+  .wrap { max-width: 1080px; margin: 0 auto; padding: 48px 24px 96px; }
+  header { margin-bottom: 40px; }
+  h1 { font-size: 28px; margin: 0 0 6px; letter-spacing: -0.01em; }
+  .subtitle { color: var(--sub); font-size: 15px; margin: 0; }
+  .badges { margin-top: 16px; display: flex; gap: 8px; flex-wrap: wrap; }
+  .badge {
+    font-size: 12px; font-weight: 600; padding: 4px 10px; border-radius: 999px;
+    background: var(--blue-bg); color: var(--blue); border: 1px solid #bfdbfe;
+  }
+  section { margin-bottom: 44px; }
+  h2 {
+    font-size: 13px; text-transform: uppercase; letter-spacing: 0.06em;
+    color: var(--muted); margin: 0 0 16px; font-weight: 700;
+  }
+  .card {
+    background: var(--card); border: 1px solid var(--border); border-radius: 10px;
+    padding: 20px;
+  }
+
+  /* Tech stack grid */
+  .stack-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; }
+  .stack-card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 18px; }
+  .stack-card .tag {
+    display: inline-block; font-size: 11px; font-weight: 700; letter-spacing: 0.03em;
+    text-transform: uppercase; padding: 3px 8px; border-radius: 6px; margin-bottom: 10px;
+  }
+  .stack-card.frontend .tag { background: var(--blue-bg); color: var(--blue); }
+  .stack-card.backend .tag { background: var(--green-bg); color: var(--green); }
+  .stack-card.data .tag { background: var(--amber-bg); color: var(--amber); }
+  .stack-card h3 { margin: 0 0 8px; font-size: 16px; }
+  .stack-card ul { margin: 0; padding-left: 18px; font-size: 13.5px; color: var(--sub); }
+  .stack-card li { margin-bottom: 4px; }
+  .port {
+    display: inline-block; margin-top: 10px; font-family: ui-monospace, Consolas, monospace;
+    font-size: 12px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px;
+    padding: 2px 8px; color: var(--ink);
+  }
+
+  /* Architecture diagram */
+  .diagram {
+    display: flex; align-items: stretch; gap: 0; overflow-x: auto; padding: 8px 0;
+  }
+  .diagram-col { flex: 1; min-width: 190px; display: flex; flex-direction: column; gap: 10px; }
+  .arrow-col { display: flex; flex-direction: column; align-items: center; justify-content: center; min-width: 56px; padding: 0 6px; }
+  .arrow-col .arrow { font-size: 22px; color: var(--muted); }
+  .arrow-col .arrow-label { font-size: 10px; color: var(--muted); text-align: center; margin-top: 4px; line-height: 1.3; }
+  .box {
+    border-radius: 8px; padding: 12px 14px; font-size: 13px; border: 1px solid var(--border);
+    background: var(--card);
+  }
+  .box .box-title { font-weight: 700; font-size: 13px; margin-bottom: 2px; }
+  .box .box-sub { font-size: 11.5px; color: var(--muted); }
+  .col-label {
+    font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.05em;
+    color: var(--muted); text-align: center; margin-bottom: 4px;
+  }
+  .col-frontend .box { background: var(--blue-bg); border-color: #bfdbfe; }
+  .col-backend .box { background: var(--green-bg); border-color: #bbf7d0; }
+  .col-data .box { background: var(--amber-bg); border-color: #fde68a; }
+
+  /* Data flow steps */
+  .flow { display: flex; flex-direction: column; gap: 0; }
+  .flow-step { display: flex; gap: 16px; padding: 14px 0; border-bottom: 1px solid var(--border); }
+  .flow-step:last-child { border-bottom: none; }
+  .flow-num {
+    flex: none; width: 28px; height: 28px; border-radius: 50%; background: var(--ink); color: #fff;
+    display: flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700;
+  }
+  .flow-body .flow-title { font-weight: 600; font-size: 14px; margin-bottom: 2px; }
+  .flow-body .flow-desc { font-size: 13px; color: var(--sub); }
+  .flow-body code { background: var(--bg); border: 1px solid var(--border); border-radius: 4px; padding: 1px 5px; font-size: 12px; }
+
+  /* Component tree */
+  .tree-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 14px; }
+  .tree-card h3 { font-size: 13px; margin: 0 0 10px; color: var(--ink); }
+  .tree-card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 16px 18px; }
+  .tree-list { margin: 0; padding: 0; list-style: none; font-size: 13px; }
+  .tree-list li { padding: 3px 0; color: var(--sub); font-family: ui-monospace, Consolas, monospace; font-size: 12.5px; }
+  .tree-list li b { color: var(--ink); font-family: inherit; font-weight: 600; }
+
+  /* API table */
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); padding: 8px 12px; border-bottom: 2px solid var(--border); }
+  td { padding: 9px 12px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  td.method {
+    font-family: ui-monospace, Consolas, monospace; font-size: 11.5px; font-weight: 700;
+    color: var(--green); white-space: nowrap;
+  }
+  td.path { font-family: ui-monospace, Consolas, monospace; font-size: 12.5px; white-space: nowrap; }
+  td.desc { color: var(--sub); }
+
+  footer { color: var(--muted); font-size: 12px; text-align: center; margin-top: 60px; }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --ink: #e2e8f0; --sub: #94a3b8; --muted: #64748b; --border: #1e293b;
+      --bg: #0b1220; --card: #111827;
+      --blue-bg: #0f2247; --green-bg: #0b2a17; --amber-bg: #2a1f06; --purple-bg: #1e1533;
+    }
+    .badge { border-color: #1e3a8a; }
+  }
+  :root[data-theme="dark"] {
+    --ink: #e2e8f0; --sub: #94a3b8; --muted: #64748b; --border: #1e293b;
+    --bg: #0b1220; --card: #111827;
+    --blue-bg: #0f2247; --green-bg: #0b2a17; --amber-bg: #2a1f06; --purple-bg: #1e1533;
+  }
+  :root[data-theme="dark"] .badge { border-color: #1e3a8a; }
+  :root[data-theme="light"] {
+    --ink: #0f172a; --sub: #475569; --muted: #64748b; --border: #e2e8f0;
+    --bg: #f8fafc; --card: #ffffff;
+    --blue-bg: #eff6ff; --green-bg: #f0fdf4; --amber-bg: #fffbeb; --purple-bg: #f5f3ff;
+  }
+  :root[data-theme="light"] .badge { border-color: #bfdbfe; }
+  @media (max-width: 720px) {
+    .stack-grid, .tree-grid { grid-template-columns: 1fr; }
+    .diagram { flex-direction: column; }
+    .arrow-col { flex-direction: row; padding: 6px 0; }
+    .arrow-col .arrow { transform: rotate(90deg); }
+  }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <header>
+    <h1>Factory Inventory Management System</h1>
+    <p class="subtitle">System architecture, tech stack, and data flow — Claude Code workshop demo app</p>
+    <div class="badges">
+      <span class="badge">Vue 3 + Vite</span>
+      <span class="badge">FastAPI</span>
+      <span class="badge">In-Memory JSON Data</span>
+      <span class="badge">No Database</span>
+    </div>
+  </header>
+
+  <section>
+    <h2>Tech Stack</h2>
+    <div class="stack-grid">
+      <div class="stack-card frontend">
+        <span class="tag">Frontend</span>
+        <h3>Vue 3 (Composition API)</h3>
+        <ul>
+          <li>Vite — dev server &amp; bundler</li>
+          <li>Vue Router — client-side routing</li>
+          <li>Axios — HTTP client</li>
+          <li>Custom SVG charts, CSS Grid layouts</li>
+        </ul>
+        <span class="port">localhost:3000</span>
+      </div>
+      <div class="stack-card backend">
+        <span class="tag">Backend</span>
+        <h3>Python FastAPI</h3>
+        <ul>
+          <li>Pydantic — request/response validation</li>
+          <li>CORS middleware (all origins, dev)</li>
+          <li>uv — dependency &amp; venv management</li>
+          <li>Auto-generated docs at <code>/docs</code></li>
+        </ul>
+        <span class="port">localhost:8001</span>
+      </div>
+      <div class="stack-card data">
+        <span class="tag">Data</span>
+        <h3>In-Memory JSON</h3>
+        <ul>
+          <li>7 JSON files in <code>server/data/</code></li>
+          <li>Loaded once at startup via <code>mock_data.py</code></li>
+          <li>No persistence — resets on restart</li>
+          <li>No database, no auth (demo only)</li>
+        </ul>
+        <span class="port">server/data/*.json</span>
+      </div>
+    </div>
+  </section>
+
+  <section>
+    <h2>System Architecture</h2>
+    <div class="card">
+      <div class="diagram">
+        <div class="diagram-col col-frontend">
+          <div class="col-label">Browser</div>
+          <div class="box">
+            <div class="box-title">Vue 3 SPA</div>
+            <div class="box-sub">Views · Components · Composables</div>
+          </div>
+          <div class="box">
+            <div class="box-title">api.js</div>
+            <div class="box-sub">Axios client, centralized calls</div>
+          </div>
+        </div>
+
+        <div class="arrow-col">
+          <span class="arrow">&#8644;</span>
+          <span class="arrow-label">HTTP / JSON<br>query params</span>
+        </div>
+
+        <div class="diagram-col col-backend">
+          <div class="col-label">FastAPI Server</div>
+          <div class="box">
+            <div class="box-title">main.py</div>
+            <div class="box-sub">Routes, filters, CORS</div>
+          </div>
+          <div class="box">
+            <div class="box-title">Pydantic Models</div>
+            <div class="box-sub">Validation &amp; response typing</div>
+          </div>
+        </div>
+
+        <div class="arrow-col">
+          <span class="arrow">&#8644;</span>
+          <span class="arrow-label">load at<br>startup</span>
+        </div>
+
+        <div class="diagram-col col-data">
+          <div class="col-label">Mock Data</div>
+          <div class="box">
+            <div class="box-title">mock_data.py</div>
+            <div class="box-sub">Reads JSON into memory</div>
+          </div>
+          <div class="box">
+            <div class="box-title">data/*.json</div>
+            <div class="box-sub">inventory, orders, demand,<br>backlog, spending…</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <section>
+    <h2>Request &amp; Data Flow</h2>
+    <div class="card">
+      <div class="flow">
+        <div class="flow-step">
+          <div class="flow-num">1</div>
+          <div class="flow-body">
+            <div class="flow-title">User adjusts a filter</div>
+            <div class="flow-desc">Time Period, Warehouse, Category, or Order Status changes in <code>FilterBar.vue</code>, updating shared state in the <code>useFilters</code> composable.</div>
+          </div>
+        </div>
+        <div class="flow-step">
+          <div class="flow-num">2</div>
+          <div class="flow-body">
+            <div class="flow-title">View calls the API client</div>
+            <div class="flow-desc">A view (e.g. <code>Dashboard.vue</code>) calls a function in <code>client/src/api.js</code>, which builds query params and sends a request via Axios.</div>
+          </div>
+        </div>
+        <div class="flow-step">
+          <div class="flow-num">3</div>
+          <div class="flow-body">
+            <div class="flow-title">FastAPI receives the request</div>
+            <div class="flow-desc">A route in <code>server/main.py</code> parses optional query params (<code>warehouse</code>, <code>category</code>, <code>status</code>, <code>month</code>).</div>
+          </div>
+        </div>
+        <div class="flow-step">
+          <div class="flow-num">4</div>
+          <div class="flow-body">
+            <div class="flow-title">In-memory filtering</div>
+            <div class="flow-desc"><code>apply_filters()</code> and <code>filter_by_month()</code> run against the in-memory lists loaded from JSON — no database query.</div>
+          </div>
+        </div>
+        <div class="flow-step">
+          <div class="flow-num">5</div>
+          <div class="flow-body">
+            <div class="flow-title">Pydantic validates the response</div>
+            <div class="flow-desc">Filtered results are coerced into typed models (<code>InventoryItem</code>, <code>Order</code>, etc.) before being serialized to JSON.</div>
+          </div>
+        </div>
+        <div class="flow-step">
+          <div class="flow-num">6</div>
+          <div class="flow-body">
+            <div class="flow-title">Vue renders derived state</div>
+            <div class="flow-desc">Raw response data lands in a <code>ref()</code>; computed properties derive chart data, KPIs, and totals, and the template re-renders reactively.</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <section>
+    <h2>Frontend Structure</h2>
+    <div class="tree-grid">
+      <div class="tree-card">
+        <h3>Views — <code>client/src/views/</code></h3>
+        <ul class="tree-list">
+          <li><b>Dashboard.vue</b> — KPIs, order health, category value</li>
+          <li><b>Inventory.vue</b> — stock levels by warehouse</li>
+          <li><b>Orders.vue</b> — order tracking &amp; status</li>
+          <li><b>Demand.vue</b> — forecasting &amp; trends</li>
+          <li><b>Backlog.vue</b> — delayed / at-risk items</li>
+          <li><b>Spending.vue</b> — cost analytics</li>
+          <li><b>Reports.vue</b> — quarterly / monthly trends</li>
+        </ul>
+      </div>
+      <div class="tree-card">
+        <h3>Components &amp; Composables</h3>
+        <ul class="tree-list">
+          <li><b>FilterBar.vue</b> — shared filter controls</li>
+          <li><b>*DetailModal.vue</b> — Inventory, Product, Cost, Backlog, Profile</li>
+          <li><b>useFilters.js</b> — shared filter state</li>
+          <li><b>useAuth.js</b> — auth/user state</li>
+          <li><b>useI18n.js</b> — locale switching (en / ja)</li>
+          <li><b>currency.js</b> — number/currency formatting</li>
+        </ul>
+      </div>
+    </div>
+  </section>
+
+  <section>
+    <h2>API Endpoints</h2>
+    <div class="card">
+      <table>
+        <thead>
+          <tr><th>Method</th><th>Path</th><th>Filters</th><th>Notes</th></tr>
+        </thead>
+        <tbody>
+          <tr><td class="method">GET</td><td class="path">/api/inventory</td><td class="desc">warehouse, category</td><td class="desc">No time dimension</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/inventory/{id}</td><td class="desc">—</td><td class="desc">Single item lookup</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/orders</td><td class="desc">warehouse, category, status, month</td><td class="desc">Month supports quarters (Q1-2025)</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/orders/{id}</td><td class="desc">—</td><td class="desc">Single order lookup</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/demand</td><td class="desc">none</td><td class="desc">Forecast trend data</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/backlog</td><td class="desc">none</td><td class="desc">Delayed items, PO status</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/dashboard/summary</td><td class="desc">all filters</td><td class="desc">Aggregated KPIs</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/spending/*</td><td class="desc">varies</td><td class="desc">summary, monthly, categories, transactions</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/reports/quarterly</td><td class="desc">—</td><td class="desc">Quarterly rollups</td></tr>
+          <tr><td class="method">GET</td><td class="path">/api/reports/monthly-trends</td><td class="desc">—</td><td class="desc">Monthly trend series</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <footer>
+    Generated from a live read of the codebase — client/src, server/main.py, server/mock_data.py, server/data/*.json
+  </footer>
+
+</div>
+</body>
+</html>