Planning the Container

Step 1: Read the Docker guide

Open materials/docker-guide.md.

This is your reference for the containerisation work. It covers the core concepts: what Docker is, how a Dockerfile works, the layer model, base images, build context, and the commands you'll use. Read through it now -- you'll come back to it while writing the Dockerfile.

The key idea to hold onto: every instruction in a Dockerfile creates a layer. Layers stack on top of each other. Docker caches layers -- if nothing changed, it reuses the cached version instead of rebuilding. This means the order of instructions matters. Put the things that change rarely (installing dependencies) before the things that change often (copying your code).

Step 2: Plan the decomposition

Before you write a single Dockerfile, plan the sequence of work.

Containerisation involves multiple concerns: the backend's Dockerfile, the frontend's Dockerfile, the database connection, the networking between containers. If you try to do everything at once, Claude will be tracking too many concerns simultaneously and the output quality will drop.

Think about dependencies. The frontend calls the backend API. The backend connects to the database. This means:

1. Backend container first -- because the frontend container needs to know the backend's address, and you need the backend running to test the frontend. The backend depends on the database, but the database runs on the host for now.
2. Frontend container second -- because it depends on the backend container being addressable. You need the backend working first to verify the frontend can reach it.
3. Integration and verification last -- both containers running, communicating, end-to-end flow verified.

Use plan mode in Claude Code. Tell Claude you want to containerise this application and ask it to propose a plan. Review what it suggests. Does the sequence account for the dependencies above? If Claude proposes building both containers at the same time, that's a sign it doesn't see the dependency chain. Adjust the plan.

Step 3: Curate context for the first session

You're about to write the backend Dockerfile. Think about what Claude needs to know for this specific task -- and what it doesn't.

Include: The backend's package.json (so Claude knows the dependencies), server.js (so Claude knows the entry point), the .env.example (so Claude knows what environment variables the app expects), and the Docker guide (so Claude has the Dockerfile reference).

Exclude: The frontend code -- it's irrelevant to the backend container. The database schema -- the backend connects to PostgreSQL via DATABASE_URL, and that's all the Dockerfile needs to know. The planning templates -- you're done planning.

This is the first time you're making a deliberate decision about what Claude sees. In previous projects, you loaded everything and let Claude sort it out. For infrastructure work with multiple concerns, choosing what to include gives Claude focus. Including the full database schema when you're writing a Dockerfile adds noise without adding value.

Step 4: Update the PRD and create tickets

Open materials/planning-template.md.

Update the PRD with the containerisation requirements. Use the template -- fill in the current state (Pemba's booking app, three components, breaks on deployment) and the proposed changes (Docker containers for each component, reproducible environment, quick recovery).

Create tickets for the work. Five tickets cover the project:

• T1: Explore and understand the booking application (done)
• T2: Write the backend Dockerfile
• T3: Write the frontend Dockerfile
• T4: Connect containers and verify full stack
• T5: Verify recovery, compare deployment approaches, close project

Cross-check your PRD update with a second model. You've been writing PRD updates since P3 -- the process is familiar. The new part is the infrastructure content. Have the second model check whether the PRD accurately describes the containerisation approach, not just whether the formatting is correct.