infra

When to Use

• Building the infra/ folder (Dockerfiles, compose, env templates)
• Updating how frontend ↔ backend communicate in containerized environments
• Adding scripts for local Docker workflows or CI pipelines tied to infra
• Auditing existing Docker settings to keep them aligned with docs/architecture.md

Critical Patterns

Folder Layout

infra/
├── docker-compose.yml
├── frontend.Dockerfile
├── backend.Dockerfile
└── README.md (explain ports, env, volume usage)

• Keep infra-specific assets isolated from app packages
• Compose file must live under infra/ and reference Dockerfiles via relative paths (e.g., build: { context: .., dockerfile: infra/frontend.Dockerfile })

Service Contracts

• No database or queue services for this challenge. Reject attempts to introduce them.
• Use Docker network defaults so frontend can reach http://backend:4000 internally; do not expose backend publicly unless required.

Dockerfile Expectations

Frontend:

1. Multi-stage build (builder, runner)
2. Base image: node:20-alpine (matches engines)
3. Copy monorepo files, install pnpm globally via corepack (or pnpm fetch), then pnpm --filter frontend...
4. Output: .next/, node_modules for production only (use next build && next start)
5. Set PORT=3000, HOST=0.0.0.0

Backend:

1. Multi-stage (builder compiles TypeScript, runner copies dist/)
2. Use pnpm fetch + pnpm install --offline to leverage the lockfile
3. Expose PORT=4000
4. Entrypoint: node dist/app.js

Shared package should be built in the builder stage via pnpm --filter shared build before frontend/backend builds.

Compose Guardrails

• Always mount .env.example → .env with explicit env_file: entries; never rely on host envs implicitly
• Use depends_on so backend is ready before frontend tries to proxy API calls
• Provide a volumes: override only for dev (e.g., .:/app + pnpm install), but default compose stack should run the built artifacts
• Document commands inside infra/README.md

Networking & Rewrites

• Next.js should continue to proxy /api to backend:4000; do not open CORS on backend unless Compose rewrites prove impossible
• For local Docker usage, prefer hitting http://localhost:3000 and let rewrites map to backend automatically

ALWAYS

• Build shared artifacts in dependency order (shared → backend/frontend) inside Dockerfiles
• Copy only necessary files into runtime layers (no .git, no local dev config)
• Keep Compose deterministic: no latest tags, always build from the local source
• Mirror the same Node/pnpm versions defined in package.json engines

NEVER

• Add databases, queues, or extra services unless the spec explicitly changes
• Run pnpm install twice (use pnpm fetch + pnpm install --offline once per stage)
• Use root user in production layers; switch to node user when possible
• Bake secrets or .env values directly into images—pass through env vars at runtime

Commands

# Build & run the stack locally (from repo root)

# Tear down containers and remove orphaned services

# Rebuild a single service
docker compose -f infra/docker-compose.yml build backend

# Follow logs

# Clean dangling images created during local iterations