adamp
b0e4e977c1
Girl Scout Cookie tracking app with Express/SQLite API and React/Vite client. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# Girl Scout Cookie Tracker
|
|
|
|
A self-hosted web app for tracking cookie inventory and customers for a single troop. Works on desktop and mobile.
|
|
|
|
## Features
|
|
|
|
- **Inventory**: Add cookie products (name, price, quantity, low-stock threshold). Adjust stock (restock or deduct). Low-stock highlighting.
|
|
- **Customers**: Store name, phone, email, address, notes. Search by name, email, or phone.
|
|
- **Orders**: Create orders with customer (or walk-in), line items (product + quantity), status (pending, paid, delivered). Inventory is deducted automatically. Edit or delete orders (stock is restored on delete).
|
|
- **Dashboard**: Summary counts, low-stock list, recent orders.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 18+
|
|
- npm
|
|
|
|
## Setup
|
|
|
|
1. Clone or download this repo.
|
|
2. Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
cd client && npm install && cd ..
|
|
```
|
|
|
|
3. Optional: copy `.env.example` to `.env` and set:
|
|
|
|
- `PORT` — API port (default 3002)
|
|
- `DATABASE_PATH` — path to SQLite file (default `./data/cookies.db`)
|
|
- **Authentication (optional):** Set `APP_PASSWORD` to require a password to log in. Set `APP_SECRET` to a long random string (used to sign session cookies). If `APP_PASSWORD` is not set, the app runs without login; if set, users must enter the password to access the app. Use "Log out" in the nav to sign out.
|
|
|
|
## Development
|
|
|
|
Run the API server and the Vite dev server together:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
- API: http://localhost:3002
|
|
- Frontend: http://localhost:5173 (proxies `/api` to the server)
|
|
|
|
Use the frontend URL in your browser. The database file is created automatically on first request.
|
|
|
|
## Production build and run
|
|
|
|
1. Build the client:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
2. Run the server in production mode (serves the built client and API):
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Or set `NODE_ENV=production` and run `node server/index.js`. The app will serve static files from `client/dist` and handle the SPA fallback.
|
|
|
|
3. Open http://localhost:3002 (or your `PORT`).
|
|
|
|
## Deployment (self-hosted)
|
|
|
|
- Run the app behind a reverse proxy (e.g. nginx) if you want HTTPS or a different port.
|
|
- Set `DATABASE_PATH` to a persistent volume path so the SQLite file survives restarts.
|
|
- Set `APP_PASSWORD` and `APP_SECRET` in production so only people with the password can access the app. Session cookies are httpOnly and (in production) Secure when served over HTTPS.
|
|
- Back up the SQLite file regularly (e.g. cron job copying `data/cookies.db`).
|
|
|
|
## Project structure
|
|
|
|
- `server/` — Express API and SQLite (products, customers, orders, dashboard).
|
|
- `client/` — Vite + React SPA (Dashboard, Inventory, Customers, Orders, New order, Order detail).
|
|
- `data/` — Created at runtime; contains `cookies.db` by default.
|