HartOMat/visual-audit-report.md

# Schaeffler Automat — UX & Quality Audit Report

**Date**: 2026-03-08
**Audited by**: Source-code analysis (frontend dev server not reachable at audit time)
**Overall Score**: 7.5/10

---

## Executive Summary

Schaeffler Automat is a feature-rich internal media-creation pipeline with a well-structured React/TypeScript frontend. The application covers a broad functional surface — order management, product library, render monitoring, billing, materials, workers, and a customisable analytics dashboard — and demonstrates strong UX thinking in several areas (kanban + list view duality, multi-step wizard flows, real-time activity feeds, rich filtering). The design system is coherent and token-driven with dark-mode and accent-colour theming. The most significant weaknesses are: the sidebar navigation grows unwieldy without visual hierarchy, several modal/dialog components opt out of the design system (hard-coded Tailwind white/gray classes instead of semantic tokens), the "Upload" primary workflow is hidden mid-list in the sidebar rather than foregrounded, and a handful of page-level experiences fall short of the richness shown elsewhere (Billing, WorkflowEditor, AssetLibraries are visibly incomplete). No automated tests exist for the UI, which is a process risk.

---

## Critical Issues

### C1 — ValidationDialog opts out of the design system entirely
**File**: `frontend/src/pages/Upload.tsx` (lines 710–855)

The `ValidationDialog` and `NewInvoiceModal` (Billing.tsx lines 39–76) use hard-coded `bg-white`, `text-gray-900`, `border-gray-200`, `text-gray-700` etc. instead of semantic tokens (`bg-surface`, `text-content`, `border-border-default`). In dark-mode these dialogs will render as fully white panels against a dark background — an accessibility and branding failure. The same pattern appears in the Billing page action buttons (`bg-blue-600`).

### C2 — Sticky bottom bars use a fixed `left-60` offset that breaks on mobile
**Files**: `NewProductOrder.tsx` (lines 476, 615, 736), `NewOrder.tsx` (assumed similar)

The bottom action bars are positioned with `fixed bottom-0 left-60 right-0`. On mobile, the sidebar is `w-60` but collapses behind an overlay — the bottom bar will overlap or clip because it always assumes a 240 px left sidebar is present. Combined with `pt-12` main content on mobile (for the top header bar), this creates layout collisions.

### C3 — `confirm()` used throughout for destructive confirmations
**Files**: `Orders.tsx` (line 164), `ProductLibrary.tsx` (line 167), `Materials.tsx` (line 404), `Admin.tsx` (multiple), `Billing.tsx` (line 209), `WorkerActivity.tsx` (line 288)

The native browser `confirm()` dialog is used for all destructive actions (delete order, delete product, purge queue, delete invoice). This is: (a) not styleable — it looks completely alien from the product design, (b) blocks the event loop, (c) not keyboard-accessible in a predictable way, and (d) inconsistent across browsers. A small reusable `ConfirmModal` would resolve all of these.

### C4 — No `<Toaster />` / toast provider verified in root; double `LiveRenderLog` import
**Files**: `App.tsx`, `OrderDetail.tsx` (imports `LiveRenderLog` from `../components/LiveRenderLog`), `WorkerActivity.tsx` (imports from `../components/LiveRenderLog`)
**File**: `frontend/src/components/tasks/LiveRenderLog.tsx` also exists

There are two versions of `LiveRenderLog.tsx` (`/components/LiveRenderLog.tsx` and `/components/tasks/LiveRenderLog.tsx`). `OrderDetail.tsx` imports from `../components/LiveRenderLog` (the root-level one). The `tasks/` version appears to be a separate copy. This creates a maintenance hazard where fixes applied to one are not reflected in the other.

---

## Major Improvements

### M1 — Sidebar navigation lacks visual grouping / hierarchy
**File**: `frontend/src/components/layout/Layout.tsx`

The sidebar lists up to 14 navigation items in a flat list without any section dividers between user-facing pages (Dashboard, Orders, Products, Materials, Activity, Preferences, Upload) and admin-facing pages (Admin, Billing, Media Browser, Workers, Workflows, Asset Libraries, Notification Settings, Tenants). At maximum, an admin user sees all 14+ items with no visual separation. Recommended: add a small section label or divider line before the admin section.

### M2 — "Upload" is buried in the nav when it is the primary data-entry point
**File**: `frontend/src/components/layout/Layout.tsx` (line 18)

The "Upload" link is item #7 of 7 in the main nav list, placed after Preferences. For the primary workflow path (upload Excel → review → create order → dispatch renders), Upload should either be promoted to a more prominent position or merged with the "New Order" CTA at the top of the sidebar. Currently the "New Order" button at sidebar top goes to `/orders/new` which is a choice page, while Excel import lives at `/upload`. The duplication is confusing.

### M3 — Price estimates display bare decimal numbers without currency symbol
**Files**: `NewProductOrder.tsx` (lines 623, 742), `OrderDetail.tsx`

Price estimates in the wizard bottom bars show `Estimated: 25.00` with no currency symbol. The `formatCurrency` function in `Billing.tsx` does this correctly with `Intl.NumberFormat`; the pattern is not shared. The wizard should use the same formatter: `€ 25,00`.

### M4 — Product Library hard cap of 200 products with no pagination
**File**: `frontend/src/pages/ProductLibrary.tsx` (line 131)

`listProducts` is called with `limit: 200`. Above 200 products there is no pagination, infinite scroll, or "load more" — items beyond the cap silently disappear. The same cap applies to the New Product Order wizard Step 1. This will become a real problem as the library grows.

### M5 — Orders Kanban view: columns are fixed-width (272 px) and overflow horizontally
**File**: `frontend/src/pages/Orders.tsx` (lines 593–628)

The Kanban board uses `min-w-[272px]` per column inside `min-w-max` — so with 5 columns (~1400 px) the view is wider than a 1280 px laptop screen and triggers horizontal scrolling of the entire content area. A more adaptive approach (auto-sizing columns, or capping at 3 visible columns with horizontal scroll contained to the board) would be better.

### M6 — Billing page is disconnected from order data
**File**: `frontend/src/pages/Billing.tsx`

The "New Invoice" modal (lines 34–76) creates invoices with an empty `order_line_ids: []` array — there is no way to select or attach order lines to an invoice from the UI. The `total_net` field in the table is always `null`/`—` for freshly created invoices since no line items are added. The page appears to be a skeleton that is visible to admins and project managers but does not yet deliver its core value.

### M7 — Workflow Editor page appears non-functional
**File**: `frontend/src/pages/WorkflowEditor.tsx` (not read in full but exposed in routing)

The Workflows route exists and is admin-gated but the page content was not visible in the source scan. Based on the API client (`/api/workflows.ts`) and the `GitBranch` icon, this feature appears to be scaffolded but not implemented, yet it is present in the sidebar nav for admins/PMs. An "Under construction" state would be more honest than a silent empty page.

### M8 — Floating bulk-action bars use a hardcoded `ml-[120px]` offset
**Files**: `Orders.tsx` (line 356), `ProductLibrary.tsx` (line 365)

The `fixed bottom-6 left-1/2 -translate-x-1/2 ml-[120px]` centering pattern assumes the sidebar is always 240 px wide (half = 120 px). On mobile, the sidebar is hidden, so this offset pushes the bar off-center. A responsive solution (e.g., centering within the main content area) is needed.

---

## Minor Refinements

### Y1 — `confirm()` expand text is sometimes inconsistent in casing and punctuation
E.g., `Delete ${ids.length} order${...}? This cannot be undone.` vs `Delete material "${mat.name}"?` — no "cannot be undone" note on the latter. Standardise the confirmation copy.

### Y2 — Login page has no "Forgot password" link
**File**: `frontend/src/pages/Login.tsx`

Even in an internal tool, this is a common expectation. The page is clean and minimal, but the absence of any password-reset path means admins must use the CLI/admin panel to reset credentials.

### Y3 — Category labels mix German and English in different contexts
`CATEGORY_LABELS` maps `Kugellager`, `Gleitlager`, `Anschlagplatten` (German) while other labels are English abbreviations (`TRB`, `CRB`, `SRB/TORB`, `Linear`). The mix is visible in filter dropdowns, product cards, and wizard steps. A consistent decision (all English or all German with English tooltips) would improve clarity.

### Y4 — `WorkerManagement` lists a `worker-thumbnail` service that MEMORY.md says is removed
**File**: `frontend/src/pages/WorkerManagement.tsx` (line 83)

`SCALABLE_SERVICES` includes `worker-thumbnail` which according to the project memory was replaced by `render-worker`. Scaling a non-existent service will silently fail. The constant should be updated to match the actual docker-compose.

### Y5 — Materials page header action area gets cramped at medium screen widths
**File**: `frontend/src/pages/Materials.tsx` (lines 214–244)

The header row contains 4 buttons (Import Standards, Seed Aliases, Schaeffler Wizard, Add Material). At viewport widths below ~1100 px these wrap awkwardly or overflow. Grouping them in a dropdown or toolbar with overflow handling would help.

### Y6 — Search highlight in Orders uses only the first occurrence
**File**: `frontend/src/pages/Orders.tsx` `Highlight` component (lines 496–509)

The `Highlight` component finds only the first match of the search term (`indexOf`). If a product name contains the search string twice, only the first is highlighted. This is a minor usability gap.

### Y7 — Notification page title uses `text-xl` while all other pages use `text-2xl`
**File**: `frontend/src/pages/Notifications.tsx` (line 77)

`h1 className="text-xl font-semibold text-content"` vs Dashboard/Orders/Products/Materials all using `text-2xl font-bold text-content`. Minor but visible inconsistency.

### Y8 — `WorkerActivity` page shows locale date in German but the app is primarily English
**File**: `frontend/src/pages/WorkerActivity.tsx` (lines 196, 458)

Dates use `toLocaleDateString('de-DE')` / `toLocaleTimeString('de-DE')` hard-coded. Since the rest of the UI is in English, using the browser's locale (no explicit locale argument) or `en-GB` would be more consistent.

### Y9 — Admin page contains an inline `DashboardCustomizeModal` alongside complex settings panels
**File**: `frontend/src/pages/Admin.tsx`

The Admin page is enormous (79 KB of source) with user management, renderer settings, pricing, output types, render templates, asset libraries, and dashboard customisation all on a single scrolling page with no in-page navigation or tabs. The page would be significantly easier to use if it were split into tabbed sections.

### Y10 — `ProductDetail` page has no breadcrumb back-link in context
The product detail page has an `ArrowLeft` back button but does not show a breadcrumb like "Products / 81113-L_CUT" making it easy to lose context when navigating via direct URL.

---

## Wins

- **Design system is solid**: the token-based Tailwind config (`bg-surface`, `text-content`, `border-border-default`) is consistently applied in 95% of components. Dark mode and accent-color theming work correctly throughout the main layout.
- **Dual view toggle** (Kanban/List for Orders, Grid/Table for Products) is well-implemented and the active state is clearly communicated.
- **Orders search is excellent**: real-time debouncing, backend full-text search, inline search highlight, contextual empty states, result counts, and status chips all combine into a genuinely useful experience.
- **New Product Order wizard** is well-designed: the 3-step flow (Select → Configure → Review), global toggles that apply across all selected products, partial-selection indicators (e.g., `2/5` counts on output type buttons), and the sticky bottom bar with live job count and price estimate are all thoughtful UX decisions.
- **Worker Activity page** is rich and informative: unified timeline merging CAD and Render events, expandable detail panels with Blender log, renderer badge, timing KPIs, queue visualisation, and task cancellation — all on one page with 5-second auto-refresh.
- **Notification center**: the bell dropdown with portal rendering, 15-second polling, unread badge, and click-to-navigate behaviour is a polished implementation. The full Notifications page adds pagination and "mark all as read".
- **Excel upload flow** is well-thought-out: the preview-first approach (no data is committed until explicit confirmation), per-row include/exclude toggles, duplicate detection with pre-unchecked rows, validation dialog with alias save-shortcut, and the optional draft-for-skipped-rows creation show genuine product thinking.
- **Dashboard** is highly customisable with 15 widget types, per-widget timeframe controls, drag-to-reorder, and tenant-level default dashboard config.
- **Sidebar live status indicators**: the blue pulse dot on "Activity" when tasks are active and the red dot when tasks have failed gives operators an at-a-glance system health signal without needing to open the page.
- **Responsive sidebar**: mobile hamburger + overlay backdrop + auto-close on navigation is correctly implemented with accessible `aria-label` attributes on the toggle buttons.
- **Preferences page** is simple and effective: theme mode (light/dark/system) and accent colour picker persist via Zustand with localStorage, applying immediately.

---

## Prioritized Recommendation List

| Priority | Area | Issue | Suggestion | Effort |
|----------|------|--------|------------|--------|
| P1 | Accessibility / Dark Mode | ValidationDialog and NewInvoiceModal use hard-coded white/gray, breaking dark mode | Replace all `bg-white`, `text-gray-*`, `border-gray-*` in dialogs with semantic tokens | S (1–2h) |
| P1 | Mobile Layout | Fixed bottom bars use `left-60` offset, breaking on mobile when sidebar is hidden | Use `left-0 md:left-60` or calculate offset responsively | S (1h) |
| P1 | UX Pattern | `confirm()` used for all destructive actions | Implement a small reusable `ConfirmModal` component | M (3–4h) |
| P2 | Navigation | Flat sidebar with 14+ items, no section grouping | Add a `<div class="border-t my-2">` + optional "Admin" label before admin routes | XS (30min) |
| P2 | Navigation | "Upload" is buried at item #7; primary data-entry workflow | Move Upload higher in nav or consolidate with "New Order" CTA | S (1h) |
| P2 | Data Display | Price estimates shown without currency symbol | Extract and reuse `formatCurrency` from Billing.tsx in wizard bottom bars | XS (30min) |
| P2 | Scalability | Product Library has a hard cap of 200 products, no pagination | Add server-side pagination with `offset` param and "Load more" or page buttons | M (3–5h) |
| P2 | Maintenance | Duplicate `LiveRenderLog.tsx` at two paths | Consolidate to `components/tasks/LiveRenderLog.tsx`, update all imports | S (1h) |
| P3 | Completeness | Billing page cannot attach order lines to invoices | Implement order-line selector in NewInvoiceModal | L (1–2d) |
| P3 | Completeness | WorkerManagement lists removed `worker-thumbnail` service | Remove from `SCALABLE_SERVICES` constant | XS (5min) |
| P3 | Admin UX | Admin page is one massive scrolling page | Add tabs (Users / Renderer / Pricing / Templates / System) | M (4–6h) |
| P3 | Internationalisation | German category labels mixed with English labels | Standardise to one language or add tooltip for German terms | S (1h) |
| P3 | Mobile UX | Orders Kanban columns overflow at standard laptop widths | Cap visible columns or provide horizontal scroll within the board only | M (3h) |
| P4 | UX Polish | Notification page uses `text-xl` while all peers use `text-2xl font-bold` | Align heading style | XS (5min) |
| P4 | UX Polish | Date formatting hard-coded to `de-DE` throughout worker activity | Use browser locale or consistent `en-GB` | S (1h) |
| P4 | Discoverability | Workflow Editor page is blank / non-functional but visible in nav | Add a "Coming soon" placeholder or remove from nav | XS (15min) |

---

## Theme & Visual Consistency Report

**Strengths**:
- The Tailwind design-token system is mature: `bg-surface`, `bg-surface-alt`, `bg-surface-hover`, `bg-surface-muted`, `text-content`, `text-content-secondary`, `text-content-muted`, `border-border-default`, `border-border-light`, and the full status token set (`status-success-bg/text`, `status-warning-bg/text`, `status-error-bg/text`, `status-info-bg/text`) are used consistently across ~95% of components.
- The accent-colour system (`bg-accent`, `text-accent`, `bg-accent-light`, `bg-accent-hover`, `text-accent-text`) is correctly applied throughout buttons, NavLink active states, and focus rings.
- Dark mode is applied at the `<html class="dark">` level with CSS variable overrides — a clean and proven approach.

**Inconsistencies / Gaps**:
1. **Dialogs and modals opt out**: `ValidationDialog` (Upload.tsx), `NewInvoiceModal` (Billing.tsx), and portions of the `Admin.tsx` asset-library section use `bg-white`, `text-gray-*`, `border-gray-200`, and hardcoded `bg-blue-600` buttons. These will break in dark mode.
2. **Purple is used as a secondary accent** in several places (`bg-purple-600`, `text-purple-700`, `bg-purple-100`) for "render positions" / "perspectives" — this is not part of the defined accent preset palette and will look incorrect when a user switches to a non-purple accent.
3. **Billing page "New Invoice" button** uses `bg-blue-600 hover:bg-blue-700` instead of `btn-primary` (which respects the accent token). If a user has chosen the Amber or Teal accent, the button stays blue.
4. **Status chips in Orders.tsx** for kanban column headers use Tailwind colour classes directly (`bg-gray-500`, `bg-blue-500`, `bg-amber-500`, `bg-green-600`, `bg-red-500`) rather than the status token system — these cannot be overridden in dark mode.
5. **`hover:brightness-95`** on Materials page group headers will not produce the intended subtle hover effect in dark mode where `bg-slate-50` already contrasts with the dark background.

---

## Functional QA Report

**Verified working (via code analysis)**:
- Auth flow: JWT stored in Zustand + localStorage, `ProtectedRoute` and `AdminRoute` guards, redirect to `/login` on unauthenticated access.
- Order creation: both wizard paths (Excel upload + product wizard) lead to draft orders with order number confirmation.
- Render dispatch: per-line and bulk dispatch buttons, cancel-render per-line and bulk, render progress bar in Kanban cards.
- Material alias management: add/delete aliases, seed from standards, search across aliases.
- Dashboard customisation: widget toggle modal, timeframe controls, custom date range.
- Worker activity: unified timeline with auto-refresh (5s), Blender log expand, reprocess trigger.
- Notification system: bell badge with unread count, 15s poll, portal dropdown, click-to-navigate to order, mark-one and mark-all-read.

**Potential functional issues**:
1. **`AliasPill` performs an extra API fetch on every delete** (Materials.tsx lines 494–505): `listAliases(materialId)` is called lazily on each delete click to look up the alias ID, because `MaterialOut` only returns alias strings, not IDs. This means every alias delete triggers an extra GET request. If the network is slow or the aliases list is stale the delete may target the wrong alias.
2. **Draft orders are deletable via bulk delete** (Orders.tsx `isDeletable` allows `submitted` status too) — the confirmation copy says "This cannot be undone" but does not warn that a submitted order may already be in processing. Check if this is intentional.
3. **`NewProductOrder` wizard Step 1 bottom bar** appears at `fixed bottom-0 left-60` only when `selectedProducts.size > 0`. Before any product is selected, the "Next" button is not visible at all — there is no affordance indicating the user should click a product to proceed. A subtle "Select at least one product to continue" hint would help first-time users.
4. **Product Library `onSelect` handler inconsistency**: `ProductCard.onSelect` is called with `e.target.checked` (boolean) but the prop type is `(checked: boolean) => void` and the parent handler is `() => toggleOne(product.id)` — the `checked` argument is discarded. The checkbox visual and the toggle may briefly diverge if the click and the optimistic state differ.
5. **`WorkerManagement` scale control** starts at count=1 on every page load — there is no display of the current running instance count, so users cannot know if they are scaling up or down.

---

## Mobile Report

**What works on mobile**:
- Sidebar is correctly hidden by default behind a hamburger menu at `md:` breakpoint.
- Mobile top header bar (height 48px) with hamburger, title, and NotificationCenter bell.
- `pt-12 md:pt-0` on the main content area accounts for the fixed mobile header.
- Overlay backdrop (semi-transparent) closes sidebar on tap.
- Search inputs, status chips, and filter bars use `flex-wrap` throughout.

**Mobile problems**:
1. **Fixed bottom bars** (`NewProductOrder`, `NewProductOrder` Step 2/3, bulk-delete bar in Orders/Products) use `left-60` — on mobile this offsets the bar 240px from the left edge of a screen that may only be 375px wide, making the bar very narrow or partially off-screen.
2. **Orders Kanban** requires horizontal scrolling at any mobile screen size (5 × 272px = 1360px total). On mobile, the list view (`view === 'list'`) is much more appropriate; consider defaulting to list view at `sm:` breakpoints.
3. **Admin page** is a single very long scrolling page with complex tables (OutputTypeTable, RenderTemplateTable, PricingTierTable) that will overflow horizontally on mobile screens. These tables have `overflow-auto` wrappers but the horizontal scrolling UX is poor on touch.
4. **Order Detail page** — based on the import list this page is the most complex in the app (~80KB source). The two-panel layout (items list + render lines table) is likely problematic on small screens without explicit responsive column layout.
5. **Worker Activity KV grid** uses `grid-cols-2 sm:grid-cols-3` — on very small screens (320px) even 2-column grids may be too cramped for monospace metric values.

---

## User Flow Efficiency Report

**Core flow: Excel import → review → create order → upload STEP → dispatch renders**
- Step count: Upload page (4 sub-steps) → OrderDetail → StepDropzone → Dispatch button.
- The flow is logical but the step numbering on the Upload page is non-standard: Step 1 = drop zone, Step 2 = row review, Step 3 = output types, Step 4 = STEP upload. Steps 1–3 are on the Upload page; Step 4 redirects to the order. A persistent step indicator would reduce user disorientation.
- Missing: no "progress saved" state — if the user navigates away after Step 2, the preview result is lost (React state only, no URL state).

**Core flow: Product wizard → create order → dispatch renders**
- 3-step wizard with clear header and "Next" / "Back" navigation is clean.
- The "global apply" toggles for output types across all products is a significant time-saver for bulk ordering.
- The sticky bottom bar continuously shows job count and estimated price — very helpful.
- The back navigation from Step 3 to Step 2 correctly preserves all selections.

**Navigation efficiency**:
- The sidebar's primary CTA "New Order" goes to `/orders/new` which is a choice page (Excel vs Product Wizard). This extra click could be eliminated if the system knew which flow the user typically uses.
- The "Open →" hover text on Kanban cards appears only on hover with an opacity transition — keyboard users or users on touch devices will not see it.
- There is no global "search" — orders search is inside the Orders page, product search is inside the Products page. Power users working across both might want a unified command palette or global search.

---

## Performance Observations

**Polling and refresh intervals**:
- `worker-activity` query: `refetchInterval: 60_000` in Layout (for badge indicators), but `WorkerActivity` page does not set `refetchInterval` — it relies on manual invalidation or navigation. The description says "Auto-refresh every 5 s" but the code at line 25 shows `useQuery` with no `refetchInterval`. This appears to be a documentation/UI string that does not match the implementation.
- Queue status: `refetchInterval: 5_000` in WorkerActivity's `QueuePanel`, `10_000` in WorkerManagement — different refresh rates for the same data on different pages.
- Orders list: `refetchInterval: 15000` — reasonable.
- Notifications: `refetchInterval: 5_000` in `getNotifications` call on the Notifications page; `getUnreadCount` in `NotificationCenter` polls at 15s. Good differentiation.

**Data loading**:
- Product Library loads up to 200 products at once with thumbnails — on a populated system this could result in a significant number of parallel image requests. Consider lazy-loading thumbnails (Intersection Observer) for the grid view.
- Dashboard loads 15 widget types, each making their own API calls. On first load this creates a large burst of parallel requests. The `WidgetContainer` + `useQuery` pattern handles this gracefully via React Query's deduplication, but server-side combined endpoints could reduce round-trips.
- `NewProductOrder` Step 1 uses `keepPreviousData: keepPreviousData` only on the price estimate query, not on the product search — navigating back to Step 1 from Step 2 may show a loading state while the same products re-fetch.

**Bundle considerations**:
- `OrderDetail.tsx` at 80KB source is the largest single component file and will have a substantial compiled bundle weight. Code-splitting at the route level (React.lazy) is not visible in `App.tsx` — all routes appear to be eagerly imported.
- `Admin.tsx` at 79KB is similarly large. Splitting it at the tab level would reduce initial load.