Add sandbox Docker compose stack, project structure, and user manual

README.md

@@ -0,0 +1,122 @@
+# Petmaster Dev Sandbox
+
+Docker-based development environment for the petmaster project.
+
+## Quick Start
+
+```bash
+# Start the dev stack
+bash start-sandbox.sh
+
+# Or manually:
+sudo -g docker docker compose up -d
+```
+
+## Architecture
+
+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 |
+
+## Configuration
+
+### Database Connection
+
+```
+PostgreSQL: postgresql://postgres:postgres@localhost:5432/petmaster_dev
+Redis:      redis://localhost:6379
+```
+
+### 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.
+
+## Managing the Sandbox
+
+### Start the stack
+```bash
+sudo -g docker docker compose up -d
+```
+
+### Stop the stack
+```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 Node dev container
+sudo -g docker docker exec -it petmaster-node-dev sh
+
+# Shell in PostgreSQL
+sudo -g docker docker exec -it petmaster-postgres psql -U postgres
+
+# Redis CLI
+sudo -g docker docker exec -it petmaster-redis redis-cli
+```
+
+### Frontend hot reload
+
+The override config maps `./frontend/src` into the React container.
+Files on the host are visible at `/app/src` inside the container.
+For full hot-reload, replace the placeholder container command with your actual dev server start command.
+
+## 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:
+- `petmaster_postgres-data` — PostgreSQL data
+- `petmaster_redis-data` — Redis data
+
+Node.js containers use ephemeral bind mounts (`./node-data`) 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, 6379, or 3000 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 -d
+```