69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# Claude Code — Session Instructions
|
|
|
|
This file is your starting point for every Claude Code session on this project.
|
|
Paste it (or reference it) at the start of each session to give Claude Code full context.
|
|
|
|
---
|
|
|
|
## Project Summary
|
|
We are building a local-first restaurant POS system. Full architecture and specs live in the `/pos-build-guide/` folder. Always read the relevant guide file before starting work on any component.
|
|
|
|
## Guide Files
|
|
- `00_PROJECT_OVERVIEW.md` — Architecture, stack, build order
|
|
- `01_LOCAL_BACKEND.md` — FastAPI backend (build this first)
|
|
- `02_WAITER_PWA.md` — Waiter-facing PWA (build second)
|
|
- `03_MANAGER_DASHBOARD.md` — Manager web app (build third)
|
|
- `04_CLOUD_BACKEND.md` — Cloud licensing backend (build fourth)
|
|
- `05_SYSADMIN_PANEL.md` — Sysadmin cloud panel (build last)
|
|
|
|
## Git Workflow
|
|
- The project uses git. **Commit after every meaningful milestone** (e.g. after scaffolding a phase, after a feature is working, after a bug fix).
|
|
- Always commit before starting a new phase or major refactor.
|
|
- Keep commit messages short and descriptive. No co-author lines needed.
|
|
- Never commit `.env`, `*.db`, or `license_state.json` — they are in `.gitignore`.
|
|
|
|
## Ground Rules for Claude Code
|
|
1. **Read the guide before writing code.** Each guide has schema, endpoints, and UX specs. Follow them.
|
|
2. **Local backend first.** Nothing else can be built or tested without it.
|
|
3. **Ask before deviating.** If something in the spec seems wrong or ambiguous, ask — don't invent.
|
|
4. **Keep business logic in the backend.** Frontends are display + interaction only.
|
|
5. **Never store sensitive data in frontend localStorage beyond token + username.**
|
|
6. **All prices are stored and calculated on the backend.** Frontend only displays them.
|
|
7. **The `unit_price` on `order_items` is a snapshot** — it must be copied from the product price at the time of ordering, not referenced dynamically.
|
|
8. **Printer failures must never block order saves.** Log and continue.
|
|
|
|
## Current Build Phase
|
|
> Update this line as you progress:
|
|
> Phase 1: Local Backend — [x] Complete. Smoke tested: health, auth, products, tables, orders, printer routing all working.
|
|
> Phase 2: Waiter PWA — [ ] Not Started
|
|
> Phase 3: Manager Dashboard — [ ] Not Started
|
|
> Phase 4: Cloud Backend — [ ] Not Started
|
|
> Phase 5: Sysadmin Panel — [ ] Not Started
|
|
|
|
## Environment Variables
|
|
|
|
### Local Backend (.env)
|
|
```
|
|
SITE_ID=
|
|
CLOUD_URL=https://your-vps.com
|
|
SECRET_KEY=generate-a-long-random-string
|
|
LICENSE_GRACE_HOURS=24
|
|
DATABASE_URL=sqlite:///./pos.db
|
|
```
|
|
|
|
### Waiter PWA (.env)
|
|
```
|
|
VITE_API_URL=http://192.168.1.10:8000
|
|
```
|
|
|
|
### Manager Dashboard (.env)
|
|
```
|
|
VITE_API_URL=http://192.168.1.10:8000
|
|
```
|
|
|
|
### Cloud Backend (.env)
|
|
```
|
|
SECRET_KEY=different-long-random-string
|
|
DATABASE_URL=postgresql://... (or sqlite for dev)
|
|
```
|