Learn by Directing AI
All materials

CLAUDE.md

Himalaya Horizon Treks -- Containerised Booking System

Project

Containerise Pemba Sherpa's existing booking application using Docker. Pemba runs Himalaya Horizon Treks, a trekking outfitter in Kathmandu, Nepal. His booking system (React frontend, Express backend, PostgreSQL database) works but breaks whenever his developer pushes changes. Docker gives the system a reproducible environment so changes can be tested before going live and the system can recover quickly if something goes wrong.

Tech stack

  • Frontend: React (Vite), Tailwind CSS
  • Backend: Express.js, PostgreSQL (pg), Winston (structured logging)
  • Containerisation: Docker, Dockerfile
  • Deployment: Vercel (existing, for comparison)
  • Version control: Git, GitHub

File structure

materials/          -- provided project materials
  first-contact.md  -- Pemba's WhatsApp message
  docker-guide.md   -- Docker concepts and Dockerfile reference
  planning-template.md -- PRD update and ticket templates
  deployment-comparison.md -- Docker vs Vercel comparison guide
  starter-app/      -- Pemba's existing booking application
    backend/        -- Express API server
    frontend/       -- React frontend (Vite)
    database/       -- PostgreSQL schema and seed data

Tickets

  • T1: Explore and understand the booking application
  • T2: Write the backend Dockerfile (pinned base image, non-root user, npm ci, .dockerignore)
  • T3: Write the frontend Dockerfile
  • T4: Connect containers and verify full-stack operation
  • T5: Test recovery, compare deployment approaches, close project

Verification targets

  • Container runs as non-root user (check with docker exec)
  • Base image uses a pinned version tag (node:20-slim, not node:latest)
  • .dockerignore excludes .git, node_modules, .env
  • Structured logging works inside the container (request ID, route, method in every log entry)
  • Recovery time under 30 seconds (stop and restart container)
  • Full booking flow works end-to-end through containerised services

Commit convention

Conventional commits: feat:, fix:, docs:, chore:. Commit after completing each ticket.