Merge: Resolve conflicts — combine app stack + sandbox docs

README.md

@@ -10,21 +10,147 @@ A pet grooming/sitting/boarding/walking CRM built with NestJS + PostgreSQL + Rea
 - **Invoicing**: Generate invoices from bookings, Stripe integration
 - **Message Center**: Client-staff messaging via WebSocket
 - **Self-Booking Portal**: Clients submit service requests
+- **Tech Stack**: NestJS, Prisma ORM, PostgreSQL, React + TypeScript, TailwindCSS
+- **Payments**: Stripe
+- **Real-time**: WebSocket (NestJS Gateway)
+- **Deployment**: Docker / Docker Compose
 
 ## Quick Start
 
 ```bash
+# Start the full app (API + Web + PostgreSQL)
 docker compose up --build
 ```
 
 Then visit:
-- API: http://localhost:3000
+- API (Swagger): http://localhost:3000
 - Frontend: http://localhost:3001
+- Frontend Self-Booking: http://localhost:3001/self-booking
 
-## Tech Stack
+## Development Sandbox
 
-- **Backend**: NestJS, Prisma ORM, PostgreSQL
-- **Frontend**: React + TypeScript, TailwindCSS, React Router
-- **Payments**: Stripe
-- **Real-time**: WebSocket (NestJS Gateway)
-- **Deployment**: Docker / Docker Compose
+For pure sandbox mode (PostgreSQL + Redis + dev containers without building the app):
+
+```bash
+bash start-sandbox.sh
+# Or manually:
+sudo -g docker docker compose up -d
+```
+
+The sandbox provides four services:
+| Service | Image | Port | Purpose |
+|---------|-------|------|---------|
+| **PostgreSQL 16** | `postgres:16-alpine` | 5432 | Development database |
+| **Redis 7** | `redis:7-alpine` | 6379 | Caching / session store |
+| **Node.js 22 (Dev)** | `node:22-alpine` | 9229 | Backend dev environment |
+| **Node.js 22 (React)** | `node:22-alpine` | 3000 | Frontend dev server |
+
+## Managing the App Stack
+
+### Start the app
+```bash
+sudo -g docker docker compose up --build
+```
+
+### Stop the app
+```bash
+sudo -g docker docker compose down
+```
+
+### Stop and clean volumes
+```bash
+sudo -g docker docker compose down -v
+```
+
+### View logs
+```bash
+sudo -g docker docker compose logs -f
+```
+
+### Run commands in containers
+```bash
+# Shell in the API container
+sudo -g docker docker exec -it petmaster-api sh
+
+# Shell in PostgreSQL
+sudo -g docker docker exec -it petmaster-postgres psql -U petmaster -d petmaster
+
+# Redis CLI
+sudo -g docker docker exec -it petmaster-redis redis-cli
+```
+
+## Configuration
+
+### Database Connection
+
+```
+PostgreSQL: postgresql://petmaster:petmaster_secret@localhost:5432/petmaster
+Redis:      redis://localhost:6379
+```
+
+### Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+```bash
+cp .env.example .env
+```
+
+Required:
+- `DATABASE_URL` — PostgreSQL connection string
+- `JWT_SECRET` — Sign/verify JWT tokens
+- `STRIPE_SECRET_KEY` — Stripe API key (test mode)
+- `STRIPE_WEBHOOK_SECRET` — Stripe webhook signature secret
+
+### Docker Auth
+
+Because our container doesn't own `/run/docker.sock`, all Docker commands must run with:
+
+```bash
+sudo -g docker docker <command>
+```
+
+The `start-sandbox.sh` script wraps this for convenience.
+
+## Health Checks
+
+Run the included healthcheck script to validate everything:
+
+```bash
+bash healthcheck.sh
+```
+
+This checks:
+- Container status (all running)
+- PostgreSQL connectivity and query execution
+- Redis PING/PONG
+- Port reachability for all services
+
+## Volume Data
+
+Persistent data is stored in Docker volumes:
+- `pgdata` — PostgreSQL data
+- `redisdata` — Redis data
+
+Node.js containers use ephemeral bind mounts for temporary files.
+
+## Troubleshooting
+
+### Permission denied on docker.sock
+Ensure you're using `sudo -g docker` prefix:
+```bash
+sudo -g docker docker ps
+```
+
+### Port conflicts
+If ports 5432, 3000, 3001, or 6379 are already in use, modify the port mappings in `docker-compose.yml`.
+
+### Stale containers
+```bash
+sudo -g docker docker compose down -v --remove-orphans
+sudo -g docker docker compose up --build
+```
+
+### Prisma migration errors
+```bash
+sudo -g docker docker exec -it petmaster-api npx prisma migrate dev
+```