From 621d711839cfabbbee43e5bcd036a0abc503d22b Mon Sep 17 00:00:00 2001 From: Saad ELBASSITI Date: Wed, 1 Jul 2026 11:44:38 +0200 Subject: [PATCH 1/2] Redesign client into SaaS-style UI with left sidebar navigation Replace the top nav bar with a left vertical navigation sidebar and apply a consistent design-token system across the shell and shared components: - App.vue: sidebar layout ("Catalyst Components" brand), design tokens, consistent spacing and polished professional styling - FilterBar, LanguageSwitcher, ProfileMenu: restyled to match the new sidebar shell - Add docs/architecture.html documenting the app architecture - Add saas-ui-redesign skill used to drive the redesign Note: App.vue now calls api.getTasks() on mount but the backend has no /tasks route yet (returns 404 on every page). Tracked as a follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/saas-ui-redesign/SKILL.md | 104 ++++ .../references/design-tokens.md | 100 ++++ .../references/sidebar-layout.md | 217 +++++++ client/src/App.vue | 543 +++++++++++++----- client/src/components/FilterBar.vue | 58 +- client/src/components/LanguageSwitcher.vue | 105 ++-- client/src/components/ProfileMenu.vue | 130 +++-- docs/architecture.html | 486 ++++++++++++++++ 8 files changed, 1486 insertions(+), 257 deletions(-) create mode 100644 .claude/skills/saas-ui-redesign/SKILL.md create mode 100644 .claude/skills/saas-ui-redesign/references/design-tokens.md create mode 100644 .claude/skills/saas-ui-redesign/references/sidebar-layout.md create mode 100644 docs/architecture.html diff --git a/.claude/skills/saas-ui-redesign/SKILL.md b/.claude/skills/saas-ui-redesign/SKILL.md new file mode 100644 index 00000000..ef9d72ba --- /dev/null +++ b/.claude/skills/saas-ui-redesign/SKILL.md @@ -0,0 +1,104 @@ +--- +name: saas-ui-redesign +description: Redesign the Vue 3 client in client/ into a modern SaaS-style interface with a left vertical navigation sidebar (replacing the top nav bar), a design-token system, consistent spacing, and a polished professional look. Use this skill when the user asks to redesign, modernize, or polish the frontend UI; move navigation to a sidebar / vertical nav / left nav; give the app a "SaaS look"; improve spacing, layout, or visual consistency; or restyle App.vue and the shell. +--- + +# SaaS UI Redesign + +This skill converts the Factory Inventory Management client (`client/`, Vue 3 + Vite) from its +current sticky **top nav bar** into a modern SaaS layout: a **left vertical sidebar** for +navigation, a **CSS custom-property design-token system**, a **consistent spacing scale**, and +a clean, professional finish. The existing slate/blue palette and Inter typeface are kept — this +is about layout structure, consistency, and polish, not a new color scheme. + +## Operating rules (non-negotiable) + +- **Delegate every `.vue` edit to the `vue-expert` subagent.** Per this repo's CLAUDE.md, any + time you create or significantly modify a `.vue` file you MUST use the `vue-expert` subagent. + Give it the relevant reference file content and the preservation checklist below. +- **Verify in a real browser with Playwright MCP** (`mcp__playwright__*`) against + `http://localhost:3000`. Start the servers with the `start` skill first. +- **Preserve behavior.** This is a visual/layout redesign. Routing, data loading, i18n, filters, + and modals must work exactly as before (see the checklist in Phase 6). +- **Document non-obvious changes with a brief comment** explaining the "why", matching the + surrounding style. + +## Target design language + +- **Left sidebar** (~248px): brand at top, vertical nav in the middle, `LanguageSwitcher` + + `ProfileMenu` in the footer. Collapses on narrow viewports. +- **Token-driven** color, spacing, radius, shadow, and z-index — one source of truth on `:root`. +- **8px spacing rhythm** so gaps, padding, and margins are consistent across cards, tables, and grids. +- **Card-based surfaces** on a soft `--color-bg`, restrained shadows, clear active-nav state. + +## Reference files + +- `references/design-tokens.md` — the `:root` custom-property block to add to `App.vue`, plus a + literal→token refactor map. **Read this before Phase 1.** +- `references/sidebar-layout.md` — the target `App.vue` template + shell CSS, FilterBar + repositioning, and dropdown notes. **Read this before Phase 2.** + +## Procedure + +Work in phases. After each phase that touches a `.vue` file, hand the change to `vue-expert`. + +### Phase 1 — Establish design tokens +1. Read `references/design-tokens.md`. +2. Have `vue-expert` add the `:root` token block to the top of the global ` diff --git a/client/src/components/FilterBar.vue b/client/src/components/FilterBar.vue index 9e12b694..17819492 100644 --- a/client/src/components/FilterBar.vue +++ b/client/src/components/FilterBar.vue @@ -102,50 +102,51 @@ export default { diff --git a/client/src/components/ProfileMenu.vue b/client/src/components/ProfileMenu.vue index 5706d24c..ecfdb005 100644 --- a/client/src/components/ProfileMenu.vue +++ b/client/src/components/ProfileMenu.vue @@ -2,23 +2,29 @@
@@ -78,6 +84,10 @@ import { ref, computed } from 'vue' import { useAuth } from '../composables/useAuth' import { useI18n } from '../composables/useI18n' +defineProps({ + collapsed: { type: Boolean, default: false } +}) + const { currentUser, logout, getInitials } = useAuth() const { t } = useI18n() @@ -121,28 +131,41 @@ const handleLogout = () => { } .profile-button { + width: 100%; display: flex; align-items: center; - gap: 0.625rem; - padding: 0.5rem 0.875rem; - background: white; - border: 1px solid #e2e8f0; - border-radius: 8px; + gap: var(--space-3); + padding: var(--space-2) var(--space-3); + background: var(--color-surface); + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); cursor: pointer; transition: all 0.2s ease; font-family: inherit; } .profile-button:hover { - background: #f8fafc; - border-color: #cbd5e1; + background: var(--color-bg); + border-color: var(--color-border-strong); +} + +.profile-button:focus-visible { + outline: 2px solid var(--color-primary); + outline-offset: 2px; +} + +/* Icon-only rail: just the avatar circle, no name/chevron overflow */ +.profile-button.collapsed { + width: 36px; + justify-content: center; + padding: var(--space-2); } .avatar { width: 32px; height: 32px; border-radius: 50%; - background: linear-gradient(135deg, #2563eb 0%, #1e40af 100%); + background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-primary-dark) 100%); color: white; display: flex; align-items: center; @@ -150,49 +173,57 @@ const handleLogout = () => { font-weight: 600; font-size: 0.75rem; letter-spacing: 0.025em; + flex-shrink: 0; } .profile-name { font-size: 0.875rem; font-weight: 500; - color: #0f172a; + color: var(--color-text-strong); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; } .chevron { - color: #64748b; + color: var(--color-text-muted); transition: transform 0.2s ease; + margin-left: auto; + flex-shrink: 0; } .chevron-open { transform: rotate(180deg); } +/* Sidebar footer sits at the bottom of the viewport - open upward/rightward so the + dropdown isn't clipped below the fold. */ .dropdown-menu { position: absolute; - top: calc(100% + 0.5rem); - right: 0; + bottom: calc(100% + var(--space-2)); + left: 0; min-width: 280px; - background: white; - border: 1px solid #e2e8f0; - border-radius: 10px; - box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1); - z-index: 1000; + background: var(--color-surface); + border: 1px solid var(--color-border); + border-radius: var(--radius-md); + box-shadow: var(--shadow-lg); + z-index: var(--z-dropdown); overflow: hidden; } .dropdown-header { - padding: 1rem; + padding: var(--space-4); display: flex; - gap: 0.875rem; + gap: var(--space-3); align-items: center; - background: #f8fafc; + background: var(--color-bg); } .avatar-large { width: 48px; height: 48px; border-radius: 50%; - background: linear-gradient(135deg, #2563eb 0%, #1e40af 100%); + background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-primary-dark) 100%); color: white; display: flex; align-items: center; @@ -210,14 +241,14 @@ const handleLogout = () => { .user-name { font-weight: 600; - color: #0f172a; + color: var(--color-text-strong); font-size: 0.938rem; - margin-bottom: 0.25rem; + margin-bottom: var(--space-1); } .user-email { font-size: 0.813rem; - color: #64748b; + color: var(--color-text-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; @@ -225,16 +256,16 @@ const handleLogout = () => { .dropdown-divider { height: 1px; - background: #e2e8f0; - margin: 0.5rem 0; + background: var(--color-border); + margin: var(--space-2) 0; } .dropdown-item { width: 100%; display: flex; align-items: center; - gap: 0.75rem; - padding: 0.75rem 1rem; + gap: var(--space-3); + padding: var(--space-3) var(--space-4); background: none; border: none; text-align: left; @@ -243,24 +274,29 @@ const handleLogout = () => { font-family: inherit; font-size: 0.875rem; font-weight: 500; - color: #334155; + color: var(--color-text); } .dropdown-item:hover { - background: #f8fafc; + background: var(--color-bg); +} + +.dropdown-item:focus-visible { + outline: 2px solid var(--color-primary); + outline-offset: -2px; } .dropdown-item svg { - color: #64748b; + color: var(--color-text-muted); flex-shrink: 0; } .dropdown-item.logout { - color: #dc2626; + color: var(--color-danger); } .dropdown-item.logout svg { - color: #dc2626; + color: var(--color-danger); } .dropdown-item.logout:hover { @@ -269,12 +305,12 @@ const handleLogout = () => { .task-badge { margin-left: auto; - background: #2563eb; + background: var(--color-primary); color: white; font-size: 0.75rem; font-weight: 600; - padding: 0.125rem 0.5rem; - border-radius: 12px; + padding: var(--space-1) var(--space-2); + border-radius: var(--radius-full); min-width: 20px; text-align: center; } diff --git a/docs/architecture.html b/docs/architecture.html new file mode 100644 index 00000000..d64ba993 --- /dev/null +++ b/docs/architecture.html @@ -0,0 +1,486 @@ + + + + + +Architecture — Factory Inventory Management System + + + + +
+
+

Factory Inventory Management System

+

System architecture, technology stack, and data flow for the full-stack inventory, orders, demand, and spending analytics demo.

+
+ Vue 3 + Vite + Python FastAPI + In-memory JSON data + REST over HTTP + Read-only API +
+
+
+ +
+ + +
+
+

01 Overview

+

A three-tier single-page application. A Vue 3 client renders dashboards and tables; a FastAPI backend serves a read-only REST API; data lives entirely in memory, loaded from JSON files at startup — there is no database.

+
+
+
+
+
Presentation
+

Vue 3 SPA

+
    +
  • 7 page views, 9 reusable components
    • +
  • Client-side routing (vue-router)
    • +
  • Global filter & i18n state
    • +
+
+
+
+
Application
+

FastAPI Service

+
    +
  • ~15 REST endpoints
    • +
  • Pydantic response validation
    • +
  • In-memory filtering & aggregation
    • +
+
+
+
+
Data
+

JSON Mock Store

+
    +
  • 7 JSON files loaded at boot
    • +
  • Held in memory (no persistence)
    • +
  • Restart to reload from disk
    • +
+
+
+
+ + +
+
+

02 Technology Stack

+

Frameworks, libraries, and tooling on each tier.

+
+
+
+
+
Frontend · port 3000
+

Client

+
    +
  • Vue 3.4 — Composition API
    • +
  • Vue Router 4 — web history
    • +
  • Axios 1.6 — HTTP client
    • +
  • Vite 5 — dev server & build
    • +
  • Custom SVG charts, scoped CSS
    • +
+
+
+
+
Backend · port 8001
+

Server

+
    +
  • Python 3.11+
    • +
  • FastAPI 0.110+ — routing
    • +
  • Uvicorn 0.24+ — ASGI server
    • +
  • Pydantic 2.5+ — validation
    • +
  • CORS middleware (wildcard, dev)
    • +
+
+
+
+
Data layer
+

Storage

+
    +
  • JSON files in server/data/
    • +
  • Loaded via mock_data.py
    • +
  • Inventory, orders, demand, backlog
    • +
  • Spending, transactions, purchase orders
    • +
  • No database, no ORM
    • +
+
+
+
+
Tooling
+

Dev & Ops

+
    +
  • uv — Python env & deps
    • +
  • npm — client deps
    • +
  • OpenAPI docs at /docs
    • +
  • pytest — backend tests
    • +
+
+
+
+ + +
+
+

03 System Architecture

+

Layered view of the runtime. Each tier communicates only with the one directly below it.

+
+ +
+ +
+ Browser · localhost:3000 +

Vue 3 Single-Page Application

+
App shell (App.vue) renders a header, global filter bar, and the active route view.
+
+ Dashboard + Inventory + Orders + Spending + Demand + Reports + Backlog +
+
+
+ FilterBar (4 filters) + Detail modals ×5 + Profile / Tasks + LanguageSwitcher +
+
+
+ useFilters() + useI18n() + useAuth() + api.js (Axios client) +
+
+ +
+ HTTP · REST · JSON + ⇅ +
+ + +
+ Backend · localhost:8001 +

FastAPI Application (main.py)

+
CORS middleware → route handlers → filter utilities → Pydantic response models.
+
+ /api/inventory + /api/orders + /api/dashboard/summary + /api/demand + /api/backlog + /api/spending/* + /api/reports/* +
+
+
+ apply_filters() + filter_by_month() + Pydantic models (validation) +
+
+ +
+ in-memory read + ⇅ +
+ + +
+ Data · loaded at startup +

In-Memory Mock Store (mock_data.py)

+
JSON files read once into memory. Reads are served from these structures; nothing is written back.
+
+ inventory.json + orders.json + demand_forecasts.json + backlog_items.json + spending.json + transactions.json + purchase_orders.json +
+
+
+
+ + +
+
+

04 Data Flow

+

A single request cycle, e.g. a user changing the Warehouse filter on the Orders page.

+
+
+
+
1
+

User changes a filter

+

A dropdown in FilterBar.vue updates a shared ref in useFilters().

+
+
+
2
+

Reactive watch fires

+

Views watch the filter refs and call their loadData() method.

+
+
+
3
+

API request

+

api.js maps filters to query params and issues an Axios GET.

+
+
+
4
+

FastAPI filters

+

Handler runs apply_filters() / filter_by_month() over in-memory lists.

+
+
+
5
+

Validate & respond

+

Pydantic models shape the JSON response returned to the client.

+
+
+
6
+

Render

+

Response fills reactive refs; computed properties drive tables & SVG charts.

+
+
+
+ + +
+
+

05 API Surface

+

Core read-only endpoints and the filters each accepts. Four global filters — warehouse, category, status, month — map from the UI filter bar.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointMethodReturnsFilters
/api/inventoryGETInventory items (SKU, stock, reorder point, cost, location)warehousecategory
/api/ordersGETOrders with line items & statuswarehousecategorystatusmonth
/api/dashboard/summaryGETAggregated KPIs (inventory value, low stock, pending orders, backlog)warehousecategorystatusmonth
/api/demandGETDemand forecasts (current vs. forecasted, trend)none
/api/backlogGETBacklog items enriched with has_purchase_ordernone
/api/spending/{summary,monthly,categories,transactions}GETSpending totals, 12-month breakdown, by category, and transactionsnone
/api/reports/{quarterly,monthly-trends}GETQuarterly performance & month-over-month trends (computed from orders)none
/api/inventory/{id} · /api/orders/{id}GETSingle item / order by id (404 if absent)path param
+
+
+ + +
+
+

06 The Four-Filter System

+

A single global filter bar drives every data view. Filter state is a shared singleton in useFilters(); "all" values are omitted from the query string.

+
+
+ + + + + + + + + + +
UI FilterComposable refAPI paramApplies to
Time PeriodselectedPeriodmonthOrders, Dashboard, Spending
Location (Warehouse)selectedLocationwarehouseInventory, Orders, Dashboard
CategoryselectedCategorycategoryInventory, Orders, Dashboard
Order StatusselectedStatusstatusOrders, Dashboard
+
+
+ +
+ +
+
+ Generated architecture reference for the Factory Inventory Management System demo · + Frontend client/ (Vue 3, port 3000) · + Backend server/ (FastAPI, port 8001) · + Data server/data/*.json +
+
+ + + From 6eb5d50e318a5a9d942ffbd1f4c8b7cb1d73c94b Mon Sep 17 00:00:00 2001 From: Saad ELBASSITI Date: Wed, 1 Jul 2026 12:08:13 +0200 Subject: [PATCH 2/2] Add /api/tasks CRUD endpoints backing the tasks feature The sidebar UI calls api.getTasks/createTask/toggleTask/deleteTask, but the backend had no /tasks routes, so every page logged a 404 + AxiosError on mount. Add the missing endpoints against an in-memory task store: - GET /api/tasks list tasks - POST /api/tasks create (starts pending; priority defaults to medium) - PATCH /api/tasks/{id} toggle pending<->completed - DELETE /api/tasks/{id} delete String ids ("task-N") avoid collisions with the frontend's numeric mock task ids. Adds tests/backend/test_tasks.py (9 tests) covering CRUD, toggle, 404s, and validation. Verified: all 6 routes now load with zero console errors; full backend suite passes (49 tests). Co-Authored-By: Claude Opus 4.8 (1M context) --- server/main.py | 61 +++++++++++++++++ tests/backend/test_tasks.py | 130 ++++++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 tests/backend/test_tasks.py diff --git a/server/main.py b/server/main.py index a0c2d8c5..6dcae773 100644 --- a/server/main.py +++ b/server/main.py @@ -120,6 +120,19 @@ class CreatePurchaseOrderRequest(BaseModel): expected_delivery_date: str notes: Optional[str] = None +class Task(BaseModel): + id: str + title: str + priority: str + # camelCase to match the frontend task shape (TasksModal / useAuth mock tasks) + dueDate: str + status: str + +class CreateTaskRequest(BaseModel): + title: str + priority: str = "medium" + dueDate: str + # API endpoints @app.get("/") def root(): @@ -304,6 +317,54 @@ def get_monthly_trends(): result.sort(key=lambda x: x['month']) return result +# In-memory task store. Tasks are mutable (create/delete/toggle), unlike the +# read-only JSON-backed data, so they live here and reset on server restart. +# String ids ("task-N") never collide with the frontend's numeric mock task ids. +tasks_store = [ + {"id": "task-1", "title": "Reconcile supplier invoices", "priority": "high", "dueDate": "2025-07-10", "status": "pending"}, + {"id": "task-2", "title": "Audit safety stock thresholds", "priority": "low", "dueDate": "2025-07-18", "status": "completed"}, +] +_next_task_id = 3 + +@app.get("/api/tasks", response_model=List[Task]) +def get_tasks(): + """Get all user-created tasks.""" + return tasks_store + +@app.post("/api/tasks", response_model=Task, status_code=201) +def create_task(request: CreateTaskRequest): + """Create a new task (starts in 'pending' status).""" + global _next_task_id + new_task = { + "id": f"task-{_next_task_id}", + "title": request.title, + "priority": request.priority, + "dueDate": request.dueDate, + "status": "pending", + } + _next_task_id += 1 + # Prepend so the newest task appears first, matching the frontend's unshift() + tasks_store.insert(0, new_task) + return new_task + +@app.patch("/api/tasks/{task_id}", response_model=Task) +def toggle_task(task_id: str): + """Toggle a task's status between 'pending' and 'completed'.""" + task = next((t for t in tasks_store if t["id"] == task_id), None) + if not task: + raise HTTPException(status_code=404, detail=f"Task {task_id} not found") + task["status"] = "completed" if task["status"] == "pending" else "pending" + return task + +@app.delete("/api/tasks/{task_id}") +def delete_task(task_id: str): + """Delete a task.""" + task = next((t for t in tasks_store if t["id"] == task_id), None) + if not task: + raise HTTPException(status_code=404, detail=f"Task {task_id} not found") + tasks_store.remove(task) + return {"success": True, "id": task_id} + if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8001) diff --git a/tests/backend/test_tasks.py b/tests/backend/test_tasks.py new file mode 100644 index 00000000..460ecb54 --- /dev/null +++ b/tests/backend/test_tasks.py @@ -0,0 +1,130 @@ +""" +Tests for tasks API endpoints (GET/POST/PATCH/DELETE /api/tasks). + +Tasks live in a mutable in-memory store, so each test creates the tasks it +needs and cleans them up to stay independent of ordering and seed state. +""" +import pytest + + +class TestTasksEndpoints: + """Test suite for task-related endpoints.""" + + def _create_task(self, client, title="Test task", priority="medium", + due_date="2025-08-15"): + """Helper: create a task and return its JSON body.""" + response = client.post( + "/api/tasks", + json={"title": title, "priority": priority, "dueDate": due_date}, + ) + assert response.status_code == 201 + return response.json() + + def test_get_all_tasks(self, client): + """Test getting all tasks returns a well-formed list.""" + response = client.get("/api/tasks") + assert response.status_code == 200 + + data = response.json() + assert isinstance(data, list) + + # Verify structure of every task + for task in data: + assert "id" in task + assert "title" in task + assert "priority" in task + assert "dueDate" in task + assert "status" in task + assert task["status"] in ("pending", "completed") + + def test_create_task(self, client): + """Test creating a task returns 201 with a pending task.""" + task = self._create_task( + client, title="Reorder connectors", priority="high", + due_date="2025-09-01", + ) + try: + assert task["title"] == "Reorder connectors" + assert task["priority"] == "high" + assert task["dueDate"] == "2025-09-01" + # New tasks always start pending, regardless of request + assert task["status"] == "pending" + assert isinstance(task["id"], str) + assert task["id"].startswith("task-") + finally: + client.delete(f"/api/tasks/{task['id']}") + + def test_create_task_defaults_priority(self, client): + """Test priority defaults to 'medium' when omitted.""" + response = client.post( + "/api/tasks", json={"title": "No priority", "dueDate": "2025-09-02"} + ) + assert response.status_code == 201 + task = response.json() + try: + assert task["priority"] == "medium" + finally: + client.delete(f"/api/tasks/{task['id']}") + + def test_created_task_appears_in_list(self, client): + """Test a created task is retrievable via GET.""" + task = self._create_task(client, title="Appears in list") + try: + data = client.get("/api/tasks").json() + assert any(t["id"] == task["id"] for t in data) + finally: + client.delete(f"/api/tasks/{task['id']}") + + def test_toggle_task(self, client): + """Test PATCH toggles status between pending and completed.""" + task = self._create_task(client, title="Toggle me") + try: + assert task["status"] == "pending" + + # pending -> completed + response = client.patch(f"/api/tasks/{task['id']}") + assert response.status_code == 200 + assert response.json()["status"] == "completed" + + # completed -> pending + response = client.patch(f"/api/tasks/{task['id']}") + assert response.status_code == 200 + assert response.json()["status"] == "pending" + finally: + client.delete(f"/api/tasks/{task['id']}") + + def test_delete_task(self, client): + """Test deleting a task removes it from the store.""" + task = self._create_task(client, title="Delete me") + + response = client.delete(f"/api/tasks/{task['id']}") + assert response.status_code == 200 + body = response.json() + assert body["success"] is True + assert body["id"] == task["id"] + + # Confirm it is gone + data = client.get("/api/tasks").json() + assert all(t["id"] != task["id"] for t in data) + + def test_toggle_nonexistent_task(self, client): + """Test toggling a task that doesn't exist returns 404.""" + response = client.patch("/api/tasks/nonexistent-999") + assert response.status_code == 404 + assert "not found" in response.json()["detail"].lower() + + def test_delete_nonexistent_task(self, client): + """Test deleting a task that doesn't exist returns 404.""" + response = client.delete("/api/tasks/nonexistent-999") + assert response.status_code == 404 + assert "not found" in response.json()["detail"].lower() + + def test_create_task_missing_required_field(self, client): + """Test creating a task without required fields returns 422.""" + # Missing dueDate + response = client.post("/api/tasks", json={"title": "Incomplete"}) + assert response.status_code == 422 + + # Missing title + response = client.post("/api/tasks", json={"dueDate": "2025-09-01"}) + assert response.status_code == 422