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

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

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

3.8 KiB Raw Blame History