# 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](#features)
- [Tech stack](#tech-stack)
- [Getting started](#getting-started)
- [Available scripts](#available-scripts)
- [Development workflow](#development-workflow)
- [Testing and coverage](#testing-and-coverage)
- [Data model](#data-model)
- [Offline and PWA behavior](#offline-and-pwa-behavior)
- [Directory layout](#directory-layout)
- [Seed data](#seed-data)
- [Build and deploy](#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):
   ```bash
   npm install
   ```
2. Run the dev server:
   ```bash
   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](./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`](./docs/seed/README.md) 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.