Frontend Guide

Frontend Guide

The ShelfWise frontend is a vanilla JavaScript single-page application. It is intentionally dependency-free to keep the bundle small and the runtime predictable.

Files

frontend/
├── index.html    # App shell
├── app.js        # Application logic
├── styles.css    # Dark theme and responsive layout
└── sw.js         # Service worker for offline caching

Design Principles

• Accessibility first: WCAG 2.1 AA compliant.
• No build step: plain HTML, CSS, and ES modules are not required.
• Responsive: works on desktop, tablet, and mobile.
• Offline capable: service worker caches static assets.

UI Sections

Input Panel

• UPC textarea (one per line)
• CSV file input
• Process UPCs, Load Demo, Upload CSV, and Clear buttons

Job Status Panel

• Live progress bar
• Counts: total, queued, running, completed, failed
• SSE connection status indicator

Product Grid

• Sort by confidence, name, brand, or category
• Search/filter by keyword
• Product cards showing image, name, brand, category, confidence badge, and citations

Product Card Actions

• View Trace: opens a modal with the step-by-step reasoning trace.
• View Image: opens a lightbox.

Export Panel

• Buttons for CSV, JSON, Shopify, Amazon, WooCommerce, eBay, Etsy, BigCommerce.

Analytics Panel

• Portfolio totals, confidence distribution, top brands, top categories.

State Management

app.js keeps state in a simple object:

const state = {
  products: [],
  jobId: null,
  eventSource: null,
  sortKey: 'confidence',
  sortDir: 'desc',
  searchQuery: ''
};

Server-Sent Events

The frontend connects to /api/jobs/{job_id}/stream to receive live updates:

const es = new EventSource(`/api/jobs/${jobId}/stream`);
es.onmessage = (event) => {
  const update = JSON.parse(event.data);
  updateProgress(update);
  if (update.completed + update.failed === update.total) {
    es.close();
    loadProducts();
  }
};

Keyboard Shortcuts

Shortcut	Action
Ctrl/Cmd + Enter	Submit UPCs
/	Focus search
Esc	Close modals / lightbox

Accessibility Features

• Skip link to main content
• Semantic HTML (header, main, section, button)
• ARIA labels on icon buttons
• Focus-visible outlines
• Screen-reader announcements for job status
• prefers-reduced-motion respected
• prefers-contrast: more supported

Modifying the Theme

CSS custom properties are defined in :root at the top of styles.css:

:root {
  --bg: #0f172a;
  --surface: #1e293b;
  --primary: #38bdf8;
  --text: #f8fafc;
  --muted: #94a3b8;
}

Change these values to retheme the app.

Service Worker

sw.js caches static assets and API GET responses. It is installed automatically on first load.

To force an update:

navigator.serviceWorker.getRegistrations().then(rs => rs.forEach(r => r.unregister()));

Common Frontend Tasks

Add a New Export Format

1. Add a button in index.html.
2. Add a click handler in app.js calling POST /api/export with the new format.
3. Add the format implementation in backend/main.py.

Add a New Product Card Field

1. Ensure the backend includes the field in ConsolidatedProduct.
2. Update renderProductCard() in app.js.
3. Style the new element in styles.css.