368 lines
7.5 KiB
Markdown
368 lines
7.5 KiB
Markdown
# AGENTS.md --- StockFill
|
|
|
|
## Purpose
|
|
|
|
StockFill is an offline-first Progressive Web App (PWA) designed to help
|
|
service station staff create pick lists used to restock various store
|
|
areas (drinks fridge, chips, chocolate, dairy, deli, etc.).\
|
|
It uses **IndexedDB (Dexie)** for local storage, has **no backend**, and
|
|
runs fully offline.
|
|
|
|
All code generated must follow the architecture, conventions, and rules
|
|
below.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 1. Core Architecture
|
|
|
|
StockFill is:
|
|
|
|
- React + Vite\
|
|
- PWA (service worker + manifest)\
|
|
- Dexie.js for local DB (IndexedDB)\
|
|
- React Router\
|
|
- Context + Hooks\
|
|
- Mobile-first UI\
|
|
- Hosted via Docker using Nginx
|
|
|
|
There is **no remote API**.\
|
|
All data stays local to the device.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 2. Directory Structure
|
|
|
|
Codex must always generate files within this structure:
|
|
|
|
/app
|
|
/src
|
|
/components
|
|
/screens
|
|
/hooks
|
|
/db
|
|
index.ts
|
|
migrations.ts
|
|
seed.ts
|
|
/models
|
|
Product.ts
|
|
Area.ts
|
|
PickList.ts
|
|
PickItem.ts
|
|
/context
|
|
DBProvider.tsx
|
|
/utils
|
|
barcode.ts
|
|
longPress.ts
|
|
swipe.ts
|
|
/pwa
|
|
service-worker.js
|
|
manifest.json
|
|
App.tsx
|
|
main.tsx
|
|
Dockerfile
|
|
docker-compose.yml
|
|
vite.config.ts
|
|
AGENTS.md
|
|
/.vscode (workspace-level editor settings and launch/task config)
|
|
|
|
Codex must not introduce alternative or conflicting structures.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 3. Data Model Specification
|
|
|
|
Dexie tables must be implemented exactly as follows:
|
|
|
|
### Products
|
|
|
|
id: string (UUID)
|
|
name: string
|
|
category: string
|
|
unit_type: string
|
|
bulk_name?: string
|
|
units_per_bulk?: number
|
|
barcode?: string
|
|
archived: boolean
|
|
created_at: number
|
|
updated_at: number
|
|
|
|
### Areas
|
|
|
|
id: string
|
|
name: string
|
|
created_at: number
|
|
updated_at: number
|
|
|
|
### PickLists
|
|
|
|
id: string
|
|
area_id: string
|
|
created_at: number
|
|
completed_at?: number
|
|
notes?: string
|
|
|
|
### PickItems
|
|
|
|
id: string
|
|
pick_list_id: string
|
|
product_id: string
|
|
quantity_units: number
|
|
quantity_bulk: number
|
|
status: "pending" | "picked" | "skipped"
|
|
created_at: number
|
|
updated_at: number
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 4. UI & UX Rules
|
|
|
|
- Mobile-first screens\
|
|
- Large touch targets\
|
|
- Clean, minimal UI\
|
|
- Use MUI components\
|
|
- Follow workflow conventions\
|
|
- Avoid excessive modal dialogs\
|
|
- Ensure barcode scanning is fast\
|
|
- Ensure gesture operations are smooth
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 5. Core Screens
|
|
|
|
### HomeScreen
|
|
|
|
- Start New Pick List\
|
|
- View Pick Lists\
|
|
- Manage Products\
|
|
- Manage Areas\
|
|
- Scan Barcode (quick add)
|
|
|
|
### StartPickListScreen
|
|
|
|
- Choose Area\
|
|
- Start button
|
|
|
|
### ActivePickListScreen
|
|
|
|
- List of PickItems\
|
|
- Tap = +1 unit\
|
|
- Long-press = +1 bulk\
|
|
- Swipe left = mark picked\
|
|
- Swipe right = delete\
|
|
- Add Item button\
|
|
- Complete List button
|
|
|
|
### AddItemScreen
|
|
|
|
- Search\
|
|
- Category filter\
|
|
- Scan barcode\
|
|
- Increment units & bulk\
|
|
- Add to pick list
|
|
|
|
### ManageProductsScreen
|
|
|
|
- List\
|
|
- Search\
|
|
- Filters\
|
|
- Edit product\
|
|
- Add product
|
|
|
|
### ManageAreasScreen
|
|
|
|
- Add\
|
|
- Edit\
|
|
- Delete
|
|
|
|
### BarcodeScannerScreen
|
|
|
|
- Live camera preview\
|
|
- On detection → resolve product or prompt creation
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 6. Gestures & Interaction Rules
|
|
|
|
### Tap
|
|
|
|
Increase `quantity_units` by **1**.
|
|
|
|
### Long Press
|
|
|
|
Increase `quantity_bulk` by **1** using a shared `useLongPress()` hook.
|
|
|
|
### Swipe Left
|
|
|
|
Mark item as `"picked"`.
|
|
|
|
### Swipe Right
|
|
|
|
Delete item.
|
|
|
|
### Barcode Scanning
|
|
|
|
- Use `@zxing/browser`\
|
|
- Fallback to native `BarcodeDetector`
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 7. Hooks Requirements
|
|
|
|
### Database Hooks
|
|
|
|
- `useProducts()`\
|
|
- `useProduct(id)`\
|
|
- `usePickList(id)`\
|
|
- `usePickLists()`\
|
|
- `usePickItems(pickListId)`\
|
|
- `useAreas()`
|
|
|
|
### Interaction Hooks
|
|
|
|
- `useLongPress()`\
|
|
- `useSwipe()`\
|
|
- `useBarcodeScanner()`
|
|
|
|
### PWA Hooks
|
|
|
|
- `useServiceWorker()`
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 8. Component Requirements
|
|
|
|
- ProductRow\
|
|
- PickItemRow\
|
|
- NumericStepper\
|
|
- BarcodeScannerView\
|
|
- LongPressButton
|
|
|
|
All components must use TypeScript and be reusable.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 9. State Management Rules
|
|
|
|
- Use Context for DB provider\
|
|
- No Redux\
|
|
- Long-lived data must come from Dexie\
|
|
- No external APIs\
|
|
- Full offline functionality
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 10. PWA Requirements
|
|
|
|
### manifest.json
|
|
|
|
- name\
|
|
- short_name\
|
|
- icons\
|
|
- display: standalone\
|
|
- background_color\
|
|
- theme_color
|
|
|
|
### service-worker.js
|
|
|
|
- Precache static assets\
|
|
- Cache index.html\
|
|
- Cache route requests\
|
|
- Provide offline fallback
|
|
|
|
Must NOT break Dexie.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 11. Docker Requirements
|
|
|
|
### Dockerfile
|
|
|
|
- Node build stage\
|
|
- Nginx serve stage\
|
|
- Copy build to `/var/www/html`\
|
|
- Must include service worker + PWA files
|
|
|
|
### docker-compose.yml
|
|
|
|
Expose port 8080:
|
|
|
|
ports:
|
|
- "8080:80"
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 12. Code Style Rules
|
|
|
|
- TypeScript only\
|
|
- Strict mode\
|
|
- Prettier formatting\
|
|
- Named exports unless default is clearer\
|
|
- No files larger than 300--400 lines\
|
|
- Keep architecture consistent
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 13. UX Workflow Requirements
|
|
|
|
- Minimise taps\
|
|
- Prioritise mobile experience\
|
|
- Search must be instant\
|
|
- Barcode scanning must be quick\
|
|
- Product creation must be minimal friction\
|
|
- Auto-save pick lists\
|
|
- Smooth animations on long press
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 14. Testing and Validation
|
|
|
|
Codex must generate:
|
|
|
|
- Unit tests for hooks\
|
|
- Component tests with React Testing Library\
|
|
- e2e tests only if explicitly requested
|
|
|
|
Must support offline mode.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 15. Things Codex Must NOT Do
|
|
|
|
Codex must **never**:
|
|
|
|
- Create a backend\
|
|
- Use remote APIs\
|
|
- Break PWA functionality\
|
|
- Change Dexie schema without migrations\
|
|
- Introduce Redux\
|
|
- Modify directory structure\
|
|
- Remove offline support\
|
|
- Add multi-user logic
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 16. Output Rules for Codex
|
|
|
|
- Include file paths at top of each snippet\
|
|
- No placeholder TODOs\
|
|
- Code must be runnable\
|
|
- Must follow existing patterns\
|
|
- Must ensure offline correctness
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 17. Project Evolution Rules
|
|
|
|
- New features must follow these patterns\
|
|
- DB changes must use migrations\
|
|
- Schema must remain forward-compatible
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
## 18. Summary
|
|
|
|
This document defines how Codex must generate, modify, and maintain the
|
|
StockFill codebase.\
|
|
Codex must follow this specification **exactly**, ensuring consistency
|
|
and maintainability across all future changes.
|