bonamin/simple-pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
97d72a5868d17257f2b5cbb752265c192a8f94ef
simple-pos-system/PLANS AND STRATEGIES/PROJECT_REFERENCE.md

442 lines
21 KiB
Markdown
Raw Blame History

# POS System — Master Project Reference
> Read this file at the start of any new Claude Code session to get a complete picture of the system.
> For session-specific instructions and known issues, also read `CLAUDE_CODE_INSTRUCTIONS.md`.
---
## What We're Building
A **local-first restaurant Point of Sale system**. Waiters use their phones to take orders at tables. Orders are tracked in real time, routed to thermal printers in the kitchen and bar, and managed by a supervisor via a web dashboard. The system runs entirely on the restaurant's local network — internet outages have zero impact on operations.
A lightweight **cloud backend** handles licensing only: it verifies that each restaurant installation has a valid license and can remotely lock a site if needed. It does not touch orders, menus, or users.
**What it is NOT:**
- Not a payment processor (no card terminals, no fiscal integration)
- Not an IRS/tax reporting system
- Not a kitchen display system (KDS) — printing only
- Not SaaS — each restaurant runs its own local instance
---
## System Architecture
```
┌──────────────────────────────────────────────────┐
│ YOUR VPS (Cloud) │
│ │
│ cloud_backend (FastAPI, port 8001) │
│ sysadmin_panel (React/Vite, port 5175) │
│ │
│ Responsibilities: │
│ - Site registration (generates site_id + key) │
│ - License management (expiry dates) │
│ - Remote lock/unlock per site │
│ - Receives periodic heartbeats from local sites │
└─────────────────┬────────────────────────────────┘
│ HTTPS — heartbeat every 6h
│ 24h grace period if unreachable
┌─────────────────▼────────────────────────────────┐
│ RESTAURANT LOCAL NETWORK │
│ │
│ backend (FastAPI, port 8000) │
│ SQLite DB (pos.db) │
│ Runs on: Raspberry Pi 4 or any Linux box │
│ Static LAN IP (e.g. 192.168.1.10) │
│ │
│ Responsibilities: │
│ - All business logic (orders, tables, users) │
│ - Printer routing (ESC/POS over TCP) │
│ - Auth (JWT, username+PIN) │
│ - License enforcement (from cloud heartbeat) │
└───────────┬──────────────────┬───────────────────┘
│ LAN │ LAN
┌───────────▼──────┐ ┌────────▼──────────────────┐
│ waiter_pwa │ │ manager_dashboard │
│ React PWA │ │ React web app │
│ Port 5173 │ │ Port 5174 │
│ Waiters' phones │ │ Supervisor tablet/laptop │
└───────────┬──────┘ └───────────────────────────┘
│ LAN (TCP/9100)
┌───────────▼───────────────────────────────────────┐
│ Thermal Printers (Jolimark TP850UE) │
│ Zone A: Kitchen printer (e.g. 10.98.20.25:9100) │
│ Zone B: Bar printer (e.g. 10.98.20.26:9100) │
└───────────────────────────────────────────────────┘
```
---
## User Roles
| Role | Auth | Frontend | Can Do |
|------|------|----------|--------|
| Waiter | Username + PIN | Waiter PWA (phone) | Open orders, add items, mark paid, close. Own tables only (or assistant tables). |
| Manager | Username + PIN | Manager Dashboard | Everything waiters can + manage menu, waiters, tables, view reports. |
| Sysadmin (you) | Username + Password | Sysadmin Panel (cloud) | Register sites, manage licenses, lock/unlock sites. |
---
## Tech Stack
| Component | Technology | Notes |
|---|---|---|
| Local Backend | FastAPI (Python 3.13) | SQLAlchemy ORM, Pydantic v2, JWT auth |
| Local Database | SQLite | File: `pos.db`. Auto-migrated on startup. |
| Printer Protocol | python-escpos | ESC/POS over TCP. CP737 (n=29) for Greek. |
| Waiter PWA | React 18 + Vite | TailwindCSS, Zustand, Axios. Service worker for PWA. |
| Manager Dashboard | React 18 + Vite | TailwindCSS, React Query, Zustand, react-hot-toast. |
| Cloud Backend | FastAPI (Python) | SQLite (dev) / PostgreSQL (prod). JWT auth. |
| Sysadmin Panel | React 18 + Vite | TailwindCSS, Zustand, Axios. Dark theme, cyan accent. |
| Containerization | Docker + Docker Compose | All services in docker-compose.yml |
---
## Directory Structure
```
simple-pos-system/
├── docker-compose.yml # All 5 services defined here
├── local_backend/
│ ├── main.py # FastAPI app, lifespan, middleware
│ ├── config.py # Settings from .env (SITE_ID, SITE_KEY, CLOUD_URL, etc.)
│ ├── database.py # SQLAlchemy engine + SessionLocal
│ ├── models/ # SQLAlchemy ORM models
│ │ ├── user.py # User, AssistantAssignment
│ │ ├── table.py # Table, TableGroup
│ │ ├── product.py # Product, Category, Option, Ingredient, PreferenceSet
│ │ ├── order.py # Order, OrderItem, OrderWaiter, PrintLog
│ │ └── printer.py # Printer
│ ├── schemas/ # Pydantic request/response schemas
│ ├── routers/
│ │ ├── auth.py # POST /api/auth/login, /refresh, /me
│ │ ├── tables.py # CRUD tables + table groups
│ │ ├── products.py # CRUD products + categories + image upload
│ │ ├── orders.py # Order lifecycle + item management
│ │ ├── waiters.py # Waiter management
│ │ ├── reports.py # Shift reports, order history
│ │ └── system.py # Health, printer test, lock/unlock
│ ├── services/
│ │ ├── printer_service.py # ESC/POS print routing logic
│ │ └── cloud_sync.py # Background heartbeat task
│ ├── middleware/
│ │ └── license_check.py # Blocks all requests if locked/expired
│ ├── seed.py # Dev data seeder
│ ├── pos.db # SQLite DB (not in git)
│ └── license_state.json # Persisted license state (not in git)
│
├── cloud_backend/
│ ├── main.py # FastAPI app, seeds default admin on startup
│ ├── config.py # Settings from .env (SECRET_KEY, ADMIN_USERNAME, etc.)
│ ├── database.py
│ ├── auth_utils.py # JWT creation + verification, password hashing
│ ├── models/
│ │ ├── admin.py # Admin table (sysadmin accounts)
│ │ └── site.py # Site table (registered restaurants)
│ ├── schemas/
│ │ ├── admin.py # LoginRequest, TokenOut
│ │ └── site.py # SiteCreate, SiteOut, SiteCreatedOut, LockRequest, HeartbeatRequest/Response
│ └── routers/
│ ├── auth.py # POST /api/auth/login
│ ├── sites.py # Full CRUD + lock/unlock for sites
│ └── heartbeat.py # POST /api/heartbeat/ (called by local backends)
│
├── waiter_pwa/
│ └── src/
│ ├── api/client.js # Axios, points to VITE_API_URL
│ ├── store/authStore.js # Zustand: token + user
│ └── pages/
│ ├── LoginPage.jsx
│ ├── TablesPage.jsx
│ └── OrderPage.jsx
│
├── manager_dashboard/
│ └── src/
│ ├── api/client.js # Axios, points to VITE_API_URL
│ ├── store/authStore.js
│ └── pages/
│ ├── LoginPage.jsx # PIN pad (manager/sysadmin only)
│ ├── DashboardPage.jsx # Live table grid, 30s polling
│ ├── OrderDetailPage.jsx
│ ├── ProductsPage.jsx
│ ├── WaitersPage.jsx
│ ├── TablesPage.jsx
│ ├── ReportsPage.jsx
│ └── SettingsPage.jsx
│
├── sysadmin_panel/
│ └── src/
│ ├── api/client.js # Axios, points to VITE_CLOUD_URL
│ ├── store/authStore.js # Token stored as 'sysadmin_token'
│ └── pages/
│ ├── LoginPage.jsx # Username + password (NOT PIN)
│ ├── SitesPage.jsx # Card grid, status colors, 30s polling
│ ├── SiteDetailPage.jsx # Lock/unlock/extend/delete
│ └── RegisterSitePage.jsx # One-time secret key display
│
└── PLANS AND STRATEGIES/
├── CLAUDE_CODE_INSTRUCTIONS.md # Session start instructions + known issues log
├── PROJECT_REFERENCE.md # This file
├── TESTING_CHECKLIST.md # Step-by-step end-to-end testing guide
├── 00_PROJECT_OVERVIEW.md
├── 01_LOCAL_BACKEND.md
├── 02_WAITER_PWA.md
├── 03_MANAGER_DASHBOARD.md
├── 04_CLOUD_BACKEND.md
└── 05_SYSADMIN_PANEL.md
```
---
## Docker Compose Services
All services defined in `docker-compose.yml` at project root.
| Service | Image | Port | Depends On | Env File |
|---|---|---|---|---|
| `cloud_backend` | Custom (Dockerfile) | 8001 | — | `cloud_backend/.env` |
| `backend` | Custom (Dockerfile) | 8000 | — | `local_backend/.env` |
| `waiter_pwa` | node:20-alpine | 5173 | `backend` | `waiter_pwa/.env` |
| `manager_dashboard` | node:20-alpine | 5174 | `backend` | `manager_dashboard/.env` |
| `sysadmin_panel` | node:20-alpine | 5175 | `cloud_backend` | `sysadmin_panel/.env` |
**Volumes:**
- `./data/cloud:/app/data` — cloud DB
- `./local_backend/pos.db:/app/pos.db` — local DB
- `./local_backend/license_state.json:/app/license_state.json` — persisted license state
- `./data/product_images:/app/data/product_images` — uploaded product photos
- `./logo.png:/app/logo.png:ro` — restaurant logo for receipts
---
## Key Wiring: How Everything Connects
### 1. Waiter/Manager → Local Backend
- All REST API calls go to `VITE_API_URL` (e.g. `http://192.168.1.10:8000`)
- JWT Bearer token in `Authorization` header (stored in localStorage)
- On 401 response: token cleared, redirect to `/login`
### 2. Local Backend → Cloud Backend (Heartbeat)
- Background task in `cloud_sync.py`, fires on startup then every 6 hours
- `POST {CLOUD_URL}/api/heartbeat/`
- Headers: `X-Site-ID: <site_id>`, `X-Site-Key: <secret_key>`
- Body: `{ version, uptime_seconds }`
- Response: `{ licensed, locked, lock_reason, expires_at }`
- Result stored in memory (`license_state` dict) and persisted to `license_state.json`
- If cloud unreachable: uses last known state + 24h grace period
### 3. License Enforcement (Local Backend)
- `LicenseCheckMiddleware` runs on every request
- Reads `license_state` dict (in memory, updated by cloud sync)
- If `locked = True` → HTTP 423 on all endpoints
- If `licensed = False` → HTTP 402 on all endpoints
- Exempt: `GET /api/system/health` always passes through
### 4. Sysadmin Panel → Cloud Backend
- All API calls go to `VITE_CLOUD_URL` (e.g. `http://localhost:8001`)
- JWT Bearer token in `Authorization` header (stored as `sysadmin_token`)
- On 401: redirect to `/login`
### 5. Printer Routing (Local Backend)
- Triggered automatically on `POST /api/orders/{id}/items`
- `printer_service.py` groups items by `product.printer_zone_id`
- For each printer zone: formats ESC/POS receipt, connects via TCP to `printer.ip_address:printer.port`
- Greek text encoded as CP737 (n=29) bytes — raw `p._raw()` only, never `p.text()`
- Print failure is logged but does NOT fail the order save (orders always save)
- Items with no `printer_zone_id` are silently skipped
### 6. Site Registration Flow
1. Sysadmin opens Sysadmin Panel → Register New Site
2. Form submitted → `POST /api/sites/` on cloud backend
3. Cloud generates `site_id` (UUID) and `secret_key` (urlsafe random), stores hashed key
4. Response includes plaintext `secret_key` — **shown once only**
5. Sysadmin copies `SITE_ID` and `SITE_KEY` into `local_backend/.env`
6. Local backend restarts → next heartbeat authenticates successfully
7. Sysadmin Panel shows site as "Active" once heartbeat is received
---
## Database Schema Summary
### Local Backend (SQLite: pos.db)
| Table | Key Fields |
|---|---|
| `users` | id, username, pin_hash, role (waiter/manager/sysadmin), is_active |
| `tables` | id, number, label, is_active, group_id |
| `table_groups` | id, name |
| `categories` | id, name, color, sort_order |
| `products` | id, name, category_id, base_price, is_available, printer_zone_id, image_url |
| `product_options` | id, product_id, name, extra_cost |
| `product_ingredients` | id, product_id, name, extra_cost |
| `product_preference_sets` | id, product_id, name (exclusive-choice groups) |
| `product_preference_choices` | id, preference_set_id, name, price_delta |
| `printers` | id, name, ip_address, port, is_active |
| `orders` | id, table_id, opened_by, status, opened_at, closed_at, closed_by |
| `order_waiters` | order_id, waiter_id (many-to-many) |
| `order_items` | id, order_id, product_id, quantity, unit_price (snapshot!), selected_options (JSON), removed_ingredients (JSON), status, printed |
| `print_log` | id, order_id, printer_id, printed_at, item_ids (JSON), success, error_message |
### Cloud Backend (SQLite: cloud.db in dev, PostgreSQL in prod)
| Table | Key Fields |
|---|---|
| `admins` | id, username, password_hash, role |
| `sites` | id, site_id (UUID), name, owner_name, contact_email, secret_key_hash, is_active, is_locked, lock_reason, license_expires_at, last_seen_at, last_seen_ip |
---
## API Surface Summary
### Local Backend (`http://<ip>:8000`)
| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | `/api/auth/login` | None | Body: `{username, pin}` → JWT |
| GET | `/api/auth/me` | JWT | Returns current user |
| GET | `/api/tables/` | JWT | All tables + active order status |
| POST | `/api/tables/` | Manager | Create table |
| POST | `/api/tables/batch` | Manager | Bulk create with prefix+count |
| GET/POST/PUT/DELETE | `/api/tables/groups` | Manager | Table group management |
| GET | `/api/products/` | JWT | `?all=true` includes unavailable (manager) |
| POST | `/api/products/{id}/image` | Manager | Upload product image |
| GET/POST/PUT/DELETE | `/api/products/categories` | Manager | Category management |
| GET | `/api/orders/` | Manager | All orders, filterable |
| GET | `/api/orders/my` | Waiter | Own active orders |
| POST | `/api/orders/` | Waiter | Open new order `{table_id}` |
| POST | `/api/orders/{id}/items` | Waiter | Add items, triggers printing |
| POST | `/api/orders/{id}/pay` | Waiter | Mark items paid `{item_ids}` |
| POST | `/api/orders/{id}/close` | Waiter/Manager | Close order |
| DELETE | `/api/orders/{id}/items/{item_id}` | Manager | Cancel item |
| GET | `/api/waiters/` | Manager | All waiters |
| POST/PUT/DELETE | `/api/waiters/` | Manager | Waiter management |
| GET | `/api/reports/shift` | Manager | Shift summary |
| GET | `/api/system/health` | None | Liveness (exempt from license check) |
### Cloud Backend (`http://<vps>:8001`)
| Method | Path | Auth | Notes |
|---|---|---|---|
| POST | `/api/auth/login` | None | Body: `{username, password}` → JWT |
| GET | `/api/sites/` | Sysadmin JWT | List all sites |
| POST | `/api/sites/` | Sysadmin JWT | Register site → returns secret_key once |
| GET | `/api/sites/{site_id}` | Sysadmin JWT | Site detail |
| PUT | `/api/sites/{site_id}` | Sysadmin JWT | Update info / extend license |
| POST | `/api/sites/{site_id}/lock` | Sysadmin JWT | Lock with reason |
| POST | `/api/sites/{site_id}/unlock` | Sysadmin JWT | Unlock |
| DELETE | `/api/sites/{site_id}` | Sysadmin JWT | Deregister |
| POST | `/api/heartbeat/` | Site headers | Called by local backends |
| GET | `/health` | None | Liveness |
---
## Environment Variables
### `local_backend/.env`
```
SITE_ID=<UUID from site registration>
SITE_KEY=<secret key shown once at registration>
CLOUD_URL=http://cloud_backend:8001 # Use service name in Docker, or VPS URL in prod
SECRET_KEY=<long random string for JWT>
LICENSE_GRACE_HOURS=24
```
### `cloud_backend/.env`
```
SECRET_KEY=<different long random string>
DATABASE_URL=sqlite:////app/data/cloud.db # Or postgresql://... in prod
ACCESS_TOKEN_EXPIRE_MINUTES=60
ADMIN_USERNAME=sysadmin
ADMIN_PASSWORD=<your password>
```
### `waiter_pwa/.env`
```
VITE_API_URL=http://<local-backend-ip>:8000
```
### `manager_dashboard/.env`
```
VITE_API_URL=http://<local-backend-ip>:8000
```
### `sysadmin_panel/.env`
```
VITE_CLOUD_URL=http://localhost:8001 # Or https://your-vps.com in prod
```
---
## Printer Configuration
**Hardware:** Jolimark TP850UE, USB + Ethernet, static IP via NetFinder software.
**Protocol:** ESC/POS over raw TCP, port 9100.
**Paper:** 80mm = 48 characters wide at standard font.
**Critical Greek text rules:**
- Code page: `n=29` (CP737). Set immediately after connecting: `p._raw(b'\x1b\x74\x1d')`
- ALL text sent as raw CP737 bytes: `text.encode('cp737', errors='replace')`
- Never use `p.text()` for Greek — it does not handle CP737 correctly
- `p._raw(b'\x1b\x40')` to reset printer before each job
Printers are configured in the local DB (`printers` table) via Manager Dashboard → Settings. Each product gets assigned a `printer_zone_id` via Manager Dashboard → Products. Items with no zone assigned are silently skipped at print time.
---
## Auth Flow Details
### Waiter / Manager
1. `POST /api/auth/login` with `{username, pin}`
2. Backend verifies PIN with bcrypt, issues JWT (8h expiry)
3. Token stored in `localStorage`
4. All requests send `Authorization: Bearer <token>`
5. On 401: token cleared, redirect to `/login`
6. Manager Dashboard rehydrates user from `GET /api/auth/me` on app load
### Sysadmin (Cloud)
1. `POST /api/auth/login` on cloud backend with `{username, password}`
2. JWT stored as `sysadmin_token` in localStorage
3. All cloud API requests send the token
4. On 401: redirect to `/login`
---
## Order Lifecycle
```
Table available
↓
POST /api/orders/ → status: "open"
↓
POST /api/orders/{id}/items → items added, printer triggered
↓
POST /api/orders/{id}/pay (partial) → status: "partially_paid"
↓
POST /api/orders/{id}/pay (all items) → status: "paid"
↓
POST /api/orders/{id}/close → status: "closed", table becomes available
```
Manager can also `DELETE` the order (status: "cancelled") or cancel individual items.
---
## Known Issues & Limitations (as of Phase 5 completion)
1. **Product image upload** only works on existing products — no upload at creation time.
2. **First heartbeat** happens on local backend startup, not on a fixed schedule. If the cloud is down at startup, the first successful heartbeat may be up to 6h later.
3. **Some Manager Dashboard rough edges** remain (noted during Phase 3 smoke test) — not blockers.
4. **SITE_KEY** must be copied immediately at registration — the cloud never stores or shows the plaintext key again. If lost, deregister and re-register the site.
5. **Cloud sync on Docker networking**: `CLOUD_URL=http://cloud_backend:8001` works within Docker Compose (same network). For production VPS deployment, use the public HTTPS URL.
6. **SQLite for cloud backend** is fine for a small number of sites (< 50). For scale, switch `DATABASE_URL` to PostgreSQL.
---
## Production Deployment Notes
- **Local backend**: Docker Compose on a Raspberry Pi 4 or any Linux box. Static LAN IP via DHCP reservation at the router.
- **Cloud backend**: VPS with nginx reverse proxy + SSL (Let's Encrypt). Run `cloud_backend` container or as systemd service.
- **Sysadmin panel**: Build with `vite build`, serve static files via nginx. Optionally protect with nginx basic auth.
- **Waiter PWA**: Accessible from any phone on the LAN. For PWA install, serve over HTTPS (or use localhost on dev).
- **Printers**: Static IPs assigned via NetFinder (Jolimark utility). Docker host must be on the same VLAN as printers, or routing must be configured.
Reference in New Issue View Git Blame Copy Permalink