Updated Documentation

README.md

@@ -1,109 +1,37 @@
 # Wayfinder
-Welcome to the Wayfinder Project!
 
-## How to run locally
+Kiosk + mobile wayfinding app for Lockwood Library.
+- Frontend: `frontend/` (React/Vite)
+- Backend: `backend/` (Express/TypeScript)
+- DB: PostgreSQL for librarian search
+- Production: Nginx + Ngrok on Raspberry Pi
+Read `docs/HANDOFF.md` first, then `docs/OPERATIONS.md`.
 
-### Step 1 - Clone the Repository
-
-First, clone the repository to your local machine using Git:
-
-```bash
-git clone https://github.com/Munchken105/Wayfinder.git
-```
-
-You may or may not need to ```cd``` into your repo where you cloned it.
-
-### Step 2 - From the root directory, run the commands:
+## Local Setup
 
 ```bash
-cd backend
+git clone <CANONICAL_REPO_URL>
+cd WayfinderMain/backend
 npm install
 ```
-
-This will install the backend dependencies.
-
-### Step 3 - Start the database
-
-Ensure you have PostgreSQL installed on your local machine. To check, simply run this command on a terminal:
-
-```bash
-postgres --version
-```
-
-It should display something like: 
-
-```postgres (PostgreSQL) 17.6```
-
-where the number is the version of your installed PostgreSQL. This means that PostgreSQL is properly installed on your local machine.
-
-If an error occurs, you do not have PostgreSQL installed. Download it at this [link](https://www.postgresql.org/download/) before going to the next step. Ensure you remember the password you set.
-
-Afterward when it is properly installed, run:
-
+Create `backend/.env` with `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `PORT`.
 ```bash
 npm run db:init
-```
-
-You may be prompted to type in your password. Enter in your password so the database can be hosted.
-
-### Step 4 - Define environment variables
-
-Make a .env file in the /backend directory with the following:
-
-```
-DB_USER=postgres
-DB_PASSWORD=your_password
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=wayfinder
-
-PORT=5000
-```
-
-Replace "your_password" with your own password that connects to the user "postgres" so that the database can run.
-
-### Step 5 - Start the backend
-
-```bash
 npm run dev
-```
-
-This will start the development server for the backend.
-
-### Step 6 - On a separate terminal and from the root directory, run the commands:
-
-```bash
-cd frontend
+cd ../frontend
 npm install
-```
-
-This will install the frontend dependencies.
-
-### Step 7 - Start the frontend
-
-```bash
 npm run dev
 ```
+Open `http://localhost:5173`.
 
-This will start the development server for the frontend.
-
-### Step 8 - Open a browser and visit [http://localhost:5173](http://localhost:5173) to open the frontend
-
-This should connect to the backend automatically.
+## Notes
 
-## Tailscale SSH
+- Vite proxies `/api/*` to `http://localhost:5000`.
+- QR links use `/floors?q=<room>&mode=stairs|elevator`.
+- Health check is `http://localhost:5000/health` (not `/api/health`).
 
-### Step 1 - Go to tailscale.com Login using the Wayfinder Gmail Account (Found on our private Doc)
+## API
 
-### Step 2 Connect to tailnet
+`GET /api/search`, `GET /api/nodes`, `GET /api/rooms`, `GET /api/navigation/from/:start/to/:end`, `GET /api/floor/:floorNumber/routes`, `GET /api/config`, `GET /health`
 
-Open Terminal
-```bash
-tailscale up
-```
-
-### Step 3 - ssh
-```bash
-ssh wayfinder@2ndFloor
-```
-you are now sshed into the our 2ndFloor rasbery pi as more pi's come along ill update each pi with its own ssh instructions
+See `docs/PI_DEPLOYMENT.md` for Pi architecture.

docs/HANDOFF.md

@@ -0,0 +1,30 @@
+# Wayfinder Handoff
+
+Read in order: `../README.md` -> `PI_DEPLOYMENT.md` -> `OPERATIONS.md`.
+
+## System Snapshot
+
+- Kiosk selects room, backend computes route, QR opens phone deep link.
+- Frontend routes: `/`, `/floors`, `/mobile` (`/floors` is current QR target).
+- Backend API runs on `:5000`.
+- Navigation graph lives in `backend/src/server.ts`.
+- Search data lives in PostgreSQL via `backend/src/db/init.sql`.
+
+## Source of Truth
+
+`nginx-default`, `wayfinder-backend.service`, `scripts/deploy-pi.sh`, `scripts/redeploy-from-local.sh`, `backend/src/db/init.sql`
+
+## Critical Risks
+
+- `/api/navigation/from/:start/to/:end` ignores `:start`.
+- Nginx proxies `/api` only; `/health` is backend-root.
+- `db:init` is destructive reset.
+- Rollback is manual.
+- Kiosk OS/browser autostart config is not in this repo.
+
+## Ownership to Confirm
+
+- Canonical repo URL and branch policy.
+- Pi, Ngrok, and Tailscale owners.
+- Secret manager + credential rotation owner.
+- Backup location + retention policy.

docs/OPERATIONS.md

@@ -0,0 +1,61 @@
+# Operations Runbook
+## Local Dev
+```bash
+git clone <CANONICAL_REPO_URL>
+cd WayfinderMain/backend
+npm install
+```
+Create `backend/.env` with `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `PORT`.
+```bash
+npm run db:init
+npm run dev
+cd ../frontend
+npm install
+npm run dev
+```
+Smoke test:
+```bash
+curl -s http://localhost:5000/health
+curl -s "http://localhost:5000/api/search?q=computer"
+curl -s http://localhost:5000/api/rooms | head
+```
+## Deploy / Verify / Rollback
+```bash
+cd /home/wayfinder/WayfinderMain
+git fetch origin main
+git checkout main
+git reset --hard origin/main
+WAYFINDER_REBOOT=0 bash scripts/deploy-pi.sh
+systemctl is-active nginx wayfinder-backend ngrok
+curl -s http://127.0.0.1:5000/health
+curl -s -H "ngrok-skip-browser-warning: true" http://127.0.0.1/api/rooms | head
+git rev-parse --short HEAD
+```
+Remote deploy from laptop:
+```bash
+WAYFINDER_REBOOT=0 ./scripts/redeploy-from-local.sh
+```
+Rollback:
+```bash
+cd /home/wayfinder/WayfinderMain
+git log --oneline -n 20
+git reset --hard <KNOWN_GOOD_SHA>
+WAYFINDER_REBOOT=0 bash scripts/deploy-pi.sh
+```
+## Troubleshooting + DB Ops
+```bash
+systemctl status wayfinder-backend nginx ngrok --no-pager
+systemctl list-unit-files | rg -i ngrok || pgrep -af ngrok
+journalctl -u wayfinder-backend -n 200 --no-pager
+sudo tail -n 200 /var/log/wayfinder/backend.log
+sudo nginx -t
+curl -s http://127.0.0.1:4040/api/tunnels
+sudo -u postgres pg_dump -Fc wayfinder > /home/wayfinder/backups/wayfinder_$(date +%F_%H%M).dump
+sudo -u postgres pg_restore -d wayfinder --clean --if-exists /home/wayfinder/backups/<backup_file>.dump
+```
+Notes:
+- `/health` is backend-root (`:5000`), not proxied under `/api`.
+- Ngrok setup was completed on Pi using Wayfinder shared Google sign-in + ngrok guided setup.
+- On current Pi, ngrok and nginx auto-start on boot.
+- Keep secrets only in `backend/.env` and secret manager.
+- If SSH host key changed after reimage: `ssh-keygen -R 2ndFloor`.

docs/PI_DEPLOYMENT.md

@@ -0,0 +1,48 @@
+# Raspberry Pi Deployment
+
+## Architecture
+Traffic path:
+1. Ngrok (public HTTPS)
+2. Nginx on `:80` (serves `/var/www`)
+3. `/api/*` proxied to backend on `http://localhost:5000`
+4. Express backend handles navigation/search
+5. PostgreSQL stores librarian search data
+Important: navigation graph is in `backend/src/server.ts`, not PostgreSQL.
+
+## Canonical Paths
+- Repo: `/home/wayfinder/WayfinderMain`
+- Nginx config: `/etc/nginx/sites-available/default` (from repo `nginx-default`)
+- Backend unit: `/etc/systemd/system/wayfinder-backend.service` (from repo template)
+- Ngrok auth/setup: done on Pi via Wayfinder shared Google sign-in + ngrok quickstart flow
+- Frontend deploy dir: `/var/www`
+- Logs: `/var/log/wayfinder/backend.log`, `/var/log/nginx/error.log`, `/var/log/nginx/access.log`
+
+## Deploy
+
+```bash
+cd /home/wayfinder/WayfinderMain
+git fetch origin main
+git checkout main
+git reset --hard origin/main
+WAYFINDER_REBOOT=0 bash scripts/deploy-pi.sh
+```
+`scripts/deploy-pi.sh` builds backend/frontend, copies frontend to `/var/www`, restarts backend, and reboots unless `WAYFINDER_REBOOT=0`.
+
+## Verify
+
+```bash
+systemctl is-active nginx
+systemctl is-active wayfinder-backend
+systemctl is-active ngrok
+curl -s http://127.0.0.1:5000/health
+curl -s -H "ngrok-skip-browser-warning: true" http://127.0.0.1/api/rooms | head
+curl -s -H "ngrok-skip-browser-warning: true" http://127.0.0.1:5000/api/config
+```
+Expected: services `active`, health JSON, rooms JSON, ngrok `publicUrl` when tunnel is up.
+
+## Known Caveats
+
+- Nginx template proxies `/api` only; `/health` is backend-root on `:5000`.
+- QR handoff uses `/floors?q=<room>&mode=stairs|elevator`.
+- Ngrok and Nginx both auto-start on boot on current Pi; verify startup manager if re-imaging (`systemd` is likely but not guaranteed).
+- Keep secrets only in `backend/.env` and secret manager; never in docs.