From 64b8a249202ccc2b5407a665fc751f3b2dd695f7 Mon Sep 17 00:00:00 2001 From: beatz174-bit Date: Tue, 2 Dec 2025 08:49:56 +1000 Subject: [PATCH] Add comprehensive documentation set --- CODE_OF_CONDUCT.md | 50 ++++++++++++++++++++ CONTRIBUTING.md | 56 ++++++++++++++++++++++ README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++- SECURITY.md | 20 ++++++++ 4 files changed, 237 insertions(+), 2 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..3e73867 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,50 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in the StockFill project a harassment-free experience for +everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and +expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual +identity and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Focusing on what is best for the community +- Showing empathy toward other community members + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and +fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces and also applies when an individual is officially representing the project +in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a private security advisory on the +repository or by contacting the maintainers. All complaints will be reviewed and investigated promptly and fairly. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions +as determined by other maintainers. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1. + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..60e4a50 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing + +Thank you for helping improve StockFill! This guide explains how to set up a local environment, follow the coding conventions, and +submit changes. + +## Ground rules + +- StockFill is an offline-first PWA. Avoid adding remote API calls or backend dependencies. +- Dexie is the source of truth for persisted data. Schema updates must be applied via Dexie migrations to avoid data loss. +- Use TypeScript with strict mode and prefer named exports for new modules. +- Keep components and hooks small and focused; avoid files exceeding a few hundred lines where possible. +- Follow the existing mobile-first UX patterns and preserve accessibility cues. + +## Prerequisites + +- Node.js 20+ and npm +- Optional: Docker for containerized builds and previews +- Optional: Playwright browsers for running `npm run test:e2e` (`npx playwright install`) + +## Setup + +1. Install dependencies: + ```bash + npm install + ``` +2. Start the dev server: + ```bash + npm run dev + ``` +3. Open the printed URL in your browser or mobile emulator. + +## Development workflow + +- Create small, focused branches for each feature or fix. +- Keep PWA assets up to date when changing files in `src/pwa/`; the build step copies them into `public/`. +- Ensure offline behavior remains intact by exercising flows without network connectivity when possible. + +## Testing and quality + +Run these commands before submitting a pull request: + +- Lint: `npm run lint` +- Unit/component tests: `npm test` +- Coverage (enforced at 80%+ for statements/branches/functions/lines): `npm run test:coverage` +- End-to-end tests (optional, requires browsers): `npm run test:e2e` + +## Commit and PR guidelines + +- Write clear commit messages that describe the change. +- Provide context in pull request descriptions: what changed, why, and how it was tested. +- Avoid introducing breaking schema changes without a migration plan. + +## Reporting bugs + +- Include reproduction steps, expected vs. actual behavior, and environment details (browser, OS, device type). +- Attach screenshots for UI regressions when possible. diff --git a/README.md b/README.md index 573a89e..4e87f7c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,120 @@ # 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: +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. +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. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..739f0ad --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,20 @@ +# Security Policy + +## Supported versions + +The project is currently in active development. Apply the latest changes from the `main` branch to receive fixes and updates. + +## Reporting a vulnerability + +1. Do **not** create a public issue for security findings. +2. Open a private security advisory via the repository's "Report a vulnerability" workflow, or contact the maintainers through a + private channel if one is provided. +3. Include a detailed description with reproduction steps, impact assessment, and any suggested remediation. +4. Maintainers will acknowledge reports within a reasonable timeframe and coordinate a fix and disclosure plan. + +## Security best practices for contributors + +- Avoid introducing remote API calls that could leak data; StockFill is designed to run fully offline using Dexie. +- Keep dependencies up to date and prefer well-maintained libraries. +- Validate and sanitize data imported from CSV or other local files before persisting. +- When modifying Dexie schemas, provide migrations to protect existing user data.