hotel_pi/QUICK_REFERENCE.md

# Hotel Pi - Quick Reference

## Quick Start (Copy & Paste)

### On Your Computer (First Time)

```bash
# Clone repository
git clone https://github.com/youruser/hotel-pi.git
cd hotel-pi

# Create environment file
cp .env.example .env

# Edit if needed
nano .env

# Start all services (requires Docker)
docker-compose up -d

# Wait ~30 seconds for services to start

# Access services
# Frontend: http://localhost:5173
# Directus CMS: http://localhost:8055
# Control: ws://localhost:3001
```

### On Raspberry Pi (First Time)

```bash
# SSH into Pi
ssh pi@raspberrypi.local

# Clone and navigate
cd /home/pi
git clone https://github.com/youruser/hotel-pi.git
cd hotel-pi

# Run initialization (installs everything)
chmod +x scripts/init-system.sh
./scripts/init-system.sh

# Copy configuration
cp .env.example .env
nano .env
# Edit:
# VITE_API_URL=http://hotel-pi.local:8055
# VITE_WS_URL=ws://hotel-pi.local:3001
# WELCOME_NAME=Room 101 (or whatever)

# Start services
docker-compose up -d

# Wait 30 seconds

# Launch kiosk
./scripts/launch-kiosk.sh
```

## Common Commands

### Start/Stop Services

```bash
# Start all
docker-compose up -d

# Stop all
docker-compose down

# Restart specific service
docker-compose restart frontend

# View status
docker-compose ps

# View logs (all services)
./scripts/logs.sh all

# View logs (specific)
./scripts/logs.sh frontend
./scripts/logs.sh control
```

### Frontend Development

```bash
cd frontend
npm install
npm run dev
# Runs on http://localhost:5173 with hot reload
```

### Control Service Development

```bash
cd control-service
npm install
npm run dev
# Runs WebSocket server on port 3001
```

### CMS Administration

1. Open http://localhost:8055
2. Create admin account (first time)
3. Go to Collections
4. Create "restaurants" and "attractions" collections
5. Add content
6. Enable public access (Settings → Roles & Permissions)

### Rebuild Everything

```bash
./scripts/rebuild.sh
```

## File Structure at a Glance

```
Hotel_Pi/
├── frontend/           ← Kiosk UI (Svelte)
├── control-service/    ← Remote control (Node.js)
├── directus/          ← CMS configuration
├── scripts/           ← Automation scripts
├── docker-compose.yml ← Service orchestration
├── .env.example       ← Configuration template
├── README.md          ← Overview
├── GETTING_STARTED.md ← Setup guide
├── DEPLOYMENT.md      ← Production guide
├── API.md             ← API reference
└── ARCHITECTURE.md    ← Technical details
```

## Configuration Quick Reference

### .env Variables

```bash
# Frontend
VITE_API_URL=http://localhost:8055
VITE_WS_URL=ws://localhost:3001
WELCOME_NAME=Guest
IDLE_TIMEOUT_MINUTES=5

# Database (change these in production!)
POSTGRES_PASSWORD=directus123
DB_PASSWORD=directus123
SECRET=change-me
AUTH_SECRET=change-me
```

## Keyboard/Remote Controls

### In Kiosk

| Action | Keyboard | Remote |
|--------|----------|--------|
| Navigate | Arrow keys | Arrow buttons |
| Select | Enter | OK/Select |
| Back | Escape, Backspace | Back/Exit |
| Wake idle | Any key | Any button |

## Troubleshooting Cheat Sheet

| Problem | Solution |
|---------|----------|
| Services won't start | `docker-compose logs` → check errors |
| Frontend not loading | Verify `VITE_API_URL` in `.env` |
| Images not showing | Check Directus images are uploaded |
| Control service not responding | `curl http://localhost:3001/health` |
| Remote not working | Check TV CEC is enabled + `cec-client` installed |

## Health Checks

```bash
# Frontend running?
curl http://localhost:5173

# Directus running?
curl http://localhost:8055/server/health | jq .

# Control service running?
curl http://localhost:3001/health | jq .

# Database connected?
docker-compose exec postgres pg_isready -U directus

# All services?
docker-compose ps
```

## Useful Scripts

```bash
./scripts/launch-kiosk.sh        # Start kiosk fullscreen
./scripts/rebuild.sh              # Clean rebuild
./scripts/logs.sh all             # View all logs
./scripts/logs.sh frontend        # View frontend logs
./scripts/logs.sh control         # View control logs
./scripts/stop.sh                 # Stop all services
./scripts/control.sh health       # Check service health
```

## Development Tips

### Hot Reload Frontend
```bash
cd frontend
npm run dev
# Changes auto-reload, keep window open
```

### Hot Reload Control Service
```bash
cd control-service
npm run dev
# Service restarts on file changes
```

### Test WebSocket
```bash
npm install -g wscat
wscat -c ws://localhost:3001

# Type: {"type":"ping","payload":{}}
# Response: {"type":"pong",...}
```

### Add New Restaurant
1. Open http://localhost:8055
2. Collections → Restaurants
3. "+ Create Item"
4. Fill details, upload image
5. Publish
6. Changes appear in kiosk immediately

## Production Checklist

- [ ] Change database passwords in `.env`
- [ ] Set strong `SECRET` and `AUTH_SECRET`
- [ ] Configure `CORS_ORIGIN` properly
- [ ] Test all navigation paths
- [ ] Test remote control input
- [ ] Backup Directus data
- [ ] Set up auto-backups
- [ ] Configure firewall rules
- [ ] Change SSH password
- [ ] Test power cycle recovery

## Performance Tuning (Raspberry Pi)

```bash
# Monitor resources
htop

# Check CPU temp
vcgencmd measure_temp

# Reduce UI animations (if slow)
# Edit frontend CSS, reduce animation durations

# Reduce database load
# Implement caching in control service
```

## Backup & Restore

### Quick Backup
```bash
docker-compose exec postgres pg_dump -U directus directus > backup.sql
tar -czf hotel-pi-backup.tar.gz .env backup.sql
```

### Quick Restore
```bash
tar -xzf hotel-pi-backup.tar.gz
docker-compose exec -T postgres psql -U directus directus < backup.sql
```

## Emergency Procedures

### Kiosk Frozen?
```bash
# SSH in from another machine
ssh pi@hotel-pi.local

# Kill Chromium
pkill -f chromium

# Restart kiosk
./scripts/launch-kiosk.sh
```

### Database Corrupt?
```bash
# Stop services
docker-compose down

# Restore from backup
docker-compose exec -T postgres psql -U directus directus < backup.sql

# Restart
docker-compose up -d
```

### Complete Reset
```bash
# WARNING: Deletes all data
docker-compose down
docker volume rm hotel_pi_postgres_data
docker-compose up -d
# Requires Directus setup again
```

## Useful Links

- **Frontend Guide:** [frontend/README.md](frontend/README.md)
- **Control Service:** [control-service/README.md](control-service/README.md)
- **CMS Setup:** [directus/README.md](directus/README.md)
- **Full Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md)
- **Deployment:** [DEPLOYMENT.md](DEPLOYMENT.md)
- **API Reference:** [API.md](API.md)

## Getting Help

1. Check service logs: `./scripts/logs.sh all`
2. Review documentation in README files
3. Check .env configuration
4. Verify all services are running: `docker-compose ps`
5. Test connectivity: `curl http://localhost:5173`

## Key Concepts

| Term | Meaning |
|------|---------|
| **Kiosk** | Fullscreen app, no UI chrome |
| **CMS** | Content Management System (Directus) |
| **REST API** | HTTP-based data endpoint |
| **WebSocket** | Real-time bidirectional communication |
| **CEC** | Consumer Electronics Control (remote via HDMI) |
| **Docker** | Containerization platform |
| **Svelte** | Frontend framework |
| **Node.js** | JavaScript runtime |

---

**Version:** 1.0.0 | **Last Updated:** March 2024 | **Status:** Production Ready