adamp/cookie-tracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update CLAUDE.md with current architecture and documentation policy

Browse Source 
- Add documentation requirement: all changes must be meticulously
  documented in commits and relevant docs updated
- Update architecture docs to reflect new files (utils.js, reports
  route, Reports/Restock pages)
- Document validation patterns (parseId, date validation, 409 on
  delete with references)
- Document schema migration approach (schema_version table)
- Update schema section (6 tables, payment fields, stock_adjustments)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
adamp 2026-02-09 21:37:05 -06:00
parent 7068ea354e
commit c00bb90cc0
1 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
CLAUDE.md
View File

@ -34,19 +34,28 @@ Full-stack monorepo: Express.js API + React 18 SPA (Vite + React Router v7).
- `index.js` — Express entry point. Mounts all route groups under `/api`, applies auth middleware to non-auth routes. In production, serves the built client as static files with SPA fallback.
- `db.js` — SQLite via `better-sqlite3` (synchronous). Auto-creates the `data/` directory and tables on first run. Foreign keys are enabled.
- `middleware/auth.js` — Optional HMAC-SHA256 session cookie auth. If `APP_PASSWORD` is not set in `.env`, authentication is disabled entirely (middleware passes through).
- `routes/` — CRUD for products, customers, orders, plus a dashboard summary endpoint.
- `utils.js` — Shared helpers (`parseId`, `isValidDate`, `parseLimit`) used across routes.
- `routes/` — CRUD for products, customers, orders, plus dashboard summary and reports endpoints.
**Client** (`client/`):
- `src/App.jsx` — Top-level `AuthGate` checks `/api/auth/me` on mount; renders `<Login>` or the authenticated `<Layout>` with routes.
- `src/api.js` — Thin fetch wrapper that prefixes `/api`, includes credentials, and handles JSON serialization.
- `src/pages/` — One component per route: Dashboard, Inventory, Customers, Orders, OrderNew, OrderDetail, Login.
- `src/pages/` — One component per route: Dashboard, Inventory, Customers, Orders, OrderNew, OrderDetail, Reports, Restock, Login.
- Vite dev server proxies `/api` requests to the Express backend (configured in `vite.config.js`).
**Key data flow**: Orders deduct product stock on creation, restore stock on deletion, and recalculate stock differences on update. This logic lives in `server/routes/orders.js` with helper functions `deductStockForOrder()` and `applyOrderItems()`.
**Key data flow**: Orders deduct product stock on creation, restore stock on deletion, and recalculate stock differences on update. All stock changes are logged to `stock_adjustments`. This logic lives in `server/routes/orders.js` with helper functions `atomicDeductStock()` and `applyOrderItems()`. The product PUT endpoint does not allow `quantity_on_hand` changes — all stock modifications must go through PATCH `/products/:id/stock`.
**Validation**: All `:id` route params are validated via `parseId()` (positive integer). Report dates validated as YYYY-MM-DD. Product/customer deletes check for references and return 409 instead of FK errors.
**Schema migrations**: `server/db.js` uses a `schema_version` table. New migrations are added to `runMigrations()` gated by version number.
## Database Schema
Four tables: `products`, `customers`, `orders`, `order_items`. Orders reference customers (nullable for walk-ins). Order items have a `UNIQUE(order_id, product_id)` constraint and `ON DELETE CASCADE` from orders. Prices are snapshot at time of sale (`price_at_sale`).
Six tables: `products`, `customers`, `orders`, `order_items`, `stock_adjustments`, `schema_version`. Orders reference customers (nullable for walk-ins). Order items have a `UNIQUE(order_id, product_id)` constraint and `ON DELETE CASCADE` from orders. Prices are snapshot at time of sale (`price_at_sale`). Orders track `payment_method` and `amount_paid`. Stock adjustments log every inventory change with reason and optional reference_id.
## Change Documentation
Every change must be meticulously documented. When making commits, each change should be clearly described in the commit message with enough detail to understand what was changed and why. Update CLAUDE.md and README.md when changes affect architecture, schema, deployment, or available features.
## Environment