stockfill/README.md

StockFill

Offline-first Progressive Web App (PWA) that helps service station teams build and maintain pick lists for restocking store areas without a backend. All data lives locally in IndexedDB via Dexie so the experience works even when connectivity is unreliable.

Table of contents

• Features
• Tech stack
• Getting started
• Available scripts
• Development workflow
• Testing and coverage
• Data model
• Offline and PWA behavior
• Directory layout
• Seed data
• Build and deploy

Features

• Mobile-first UX for creating and updating pick lists quickly.
• Dexie-backed IndexedDB storage with no remote API dependencies.
• PWA manifest and service worker for offline usage and installability.
• Barcode scanning support via ZXing.
• CSV export/import utilities for product data.

Tech stack

• React + Vite (TypeScript, strict mode)
• Dexie for data storage
• React Router for navigation
• Material UI for UI components
• Vitest and React Testing Library for tests
• Playwright for optional end-to-end testing

Getting started

1. Install dependencies (Node 20+ recommended):

   npm install
   

2. Run the dev server:

   npm run dev
   

   Vite prints a local URL; open it in your browser or mobile emulator.

Available scripts

• npm run dev – start the Vite development server.
• npm run build – type-check, copy PWA assets, and build the production bundle.
• npm run preview – preview a production build locally.
• npm run lint – run ESLint across the project.
• npm test – run the unit and component test suite.
• npm run test:coverage – execute tests with coverage thresholds enforced.
• npm run test:e2e – run Playwright tests (requires browsers installed via npx playwright install).

Development workflow

• Keep the app offline-ready: avoid adding remote API calls and ensure Dexie-backed flows continue to function.
• Run npm run lint and npm test before opening a pull request to catch style and regression issues early.
• Use TypeScript and prefer named exports for new modules.
• Maintain small, focused components and hooks to preserve readability.

Testing and coverage

The test suite uses Vitest with React Testing Library. Coverage thresholds are enforced via the Vite test configuration to keep statements, branches, functions, and lines at or above 80%. Run tests locally with:

npm run test:coverage

The suite includes unit coverage for product management flows, pick list utilities, numeric steppers, autocompletion, and dialog behaviors to ensure core UX remains stable.

See TESTING.md for additional testing utilities.

Data model

Dexie tables are defined with the following shape:

• Products: id, name, category, unit_type, bulk_name?, units_per_bulk?, barcode?, archived, created_at, updated_at
• Areas: id, name, created_at, updated_at
• PickLists: id, area_id, created_at, completed_at?, notes?
• PickItems: id, pick_list_id, product_id, quantity, is_carton, status, created_at, updated_at

Schema changes must go through Dexie migrations to keep existing installations functional.

Offline and PWA behavior

• src/pwa/manifest.json and src/pwa/service-worker.js are copied into public/ during npm run build.
• The service worker precaches static assets and keeps the app shell available offline.
• Avoid breaking Dexie caching by keeping IndexedDB interactions on the main thread and preserving object store names.

Directory layout

Key folders in src/:

• components/ – Reusable UI components.
• screens/ – Route-level screens wired to the router.
• context/ – Providers such as the Dexie DB provider.
• db/ – Dexie configuration, migrations, and seed helpers.
• hooks/ – Custom hooks that encapsulate business logic.
• models/ – TypeScript interfaces for domain entities.
• pwa/ – Manifest and service worker sources.
• utils/ – Small utilities (e.g., barcode parsing, gesture helpers).

Seed data

Use the CSV template in docs/seed to preload products. The template describes each column and the expected data types for generating Dexie seed records.

Build and deploy

• Production build: npm run build (writes output to dist/).
• Docker: build the multi-stage image defined in Dockerfile and serve via docker-compose.yml (exposes port 8080).
• Ensure public/manifest.json and public/service-worker.js are present before deploying so the PWA installs correctly.