# POS System — Master Project Overview

## What We're Building
A locally-operated Point of Sale system for restaurants. It digitizes order-taking and tracking — think pen-and-paper workflows, modernized. No legal/IRS integration. No payment processing. Pure order management and accountability.

## Core Philosophy
- **Local-first**: Everything runs on the restaurant's LAN. Internet outage = zero impact on operations.
- **Simple auth**: Username + PIN. Waiters use their own phones.
- **Fraud prevention**: Waiters cannot delete items or orders. Only managers can.
- **Zone printing**: Each printer receives only items relevant to its area.

---

## System Architecture

```
┌─────────────────────────────────────────────┐
│              CLOUD (Your VPS)               │
│         Cloud Backend (FastAPI)             │
│         Sysadmin Panel (React)              │
│  - License management                       │
│  - Remote lock/unlock per site              │
│  - Site registration                        │
└──────────────────┬──────────────────────────┘
                   │ Periodic check-in (24h grace)
                   │ HTTPS
┌──────────────────▼──────────────────────────┐
│           LOCAL (Restaurant LAN)            │
│         Local Backend (FastAPI)             │
│         SQLite Database                     │
│         Printer routing (python-escpos)     │
│  Static local IP (e.g. 192.168.1.10)        │
│  Runs on Linux (RPi or old PC)              │
└────────┬────────────────┬───────────────────┘
         │ LAN            │ LAN
┌────────▼──────┐  ┌──────▼────────────────────┐
│  Waiter PWA   │  │   Manager Dashboard       │
│  (phones)     │  │   (tablet / laptop)       │
│  React + SW   │  │   React                   │
└───────────────┘  └───────────────────────────┘
         │ LAN
┌────────▼──────────────┐
│   Thermal Printers    │
│   Zone A: Kitchen     │
│   Zone B: Bar         │
│   Zone C: etc.        │
└───────────────────────┘
```

---

## Three User Roles

| Role | Access | Frontend |
|------|--------|----------|
| Waiter | Their tables only. Open, add items, view total, mark paid, close. | PWA on phone |
| Manager | All tables + orders. Full menu/waiter/table management. Shift reports. | Web Dashboard |
| Sysadmin (you) | Everything above + system control, remote lock, multi-site management. | Cloud Panel |

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Local Backend | FastAPI (Python) |
| Database | SQLite (via SQLAlchemy) |
| Printer | python-escpos |
| Waiter App | React + Vite (PWA) |
| Manager Dashboard | React + Vite |
| Styling | TailwindCSS |
| Cloud Backend | FastAPI (Python) |
| Sysadmin Panel | React + Vite |

---

## Build Order

1. `01_LOCAL_BACKEND.md` — Database schema + all API endpoints
2. `02_WAITER_PWA.md` — Waiter-facing PWA
3. `03_MANAGER_DASHBOARD.md` — Manager-facing web app
4. `04_CLOUD_BACKEND.md` — Cloud licensing + remote control
5. `05_SYSADMIN_PANEL.md` — Sysadmin cloud frontend

Each guide is self-contained with full details for Claude Code to implement.