petmaster/README.md

Petmaster CRM

A pet grooming/sitting/boarding/walking CRM built with NestJS + PostgreSQL + React.

Features

• Client Management: CRUD clients, pets, custom fields (JSONB)
• Service Catalog: Services with per-client pricing overrides
• Scheduling: CRUD bookings, recurring appointments, staff assignment
• 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

# Start the full app (API + Web + PostgreSQL)
docker compose up --build

Then visit:

• API (Swagger): http://localhost:3000
• Frontend: http://localhost:3001
• Frontend Self-Booking: http://localhost:3001/self-booking

Development Sandbox

For pure sandbox mode (PostgreSQL + Redis + dev containers without building the app):

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

sudo -g docker docker compose up --build

Stop the app

sudo -g docker docker compose down

Stop and clean volumes

sudo -g docker docker compose down -v

View logs

sudo -g docker docker compose logs -f

Run commands in containers

# 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:

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:

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 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:

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

sudo -g docker docker compose down -v --remove-orphans
sudo -g docker docker compose up --build

Prisma migration errors

sudo -g docker docker exec -it petmaster-api npx prisma migrate dev