Merge pull request #155 from beatz174-bit/codex/update-readme.md-and-add-missing-documentation
Add project documentation and contributor guidelines
This commit is contained in:
beatz174-bit
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
+20
@@ -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.
|
||||
Reference in New Issue
Block a user