flyer-crawler.projectium.com/CLAUDE.md

Claude Code Project Instructions

Platform Requirement: Linux Only

CRITICAL: This application is designed to run exclusively on Linux. See ADR-014 for full details.

Test Execution Rules

1. ALL tests MUST be executed on Linux - either in the Dev Container or on a Linux host
2. NEVER run tests directly on Windows - test results from Windows are unreliable
3. Always use the Dev Container for testing when developing on Windows

How to Run Tests Correctly

# If on Windows, first open VS Code and "Reopen in Container"
# Then run tests inside the container:
npm test           # Run all unit tests
npm run test:unit  # Run unit tests only
npm run test:integration  # Run integration tests (requires DB/Redis)

Why Linux Only?

• Path separators: Code uses POSIX-style paths (/) which may break on Windows
• Shell scripts in scripts/ directory are Linux-only
• External dependencies like pdftocairo assume Linux installation paths
• Unix-style file permissions are assumed throughout

Test Result Interpretation

• Tests that pass on Windows but fail on Linux = BROKEN tests (must be fixed)
• Tests that fail on Windows but pass on Linux = PASSING tests (acceptable)

Development Workflow

1. Open project in VS Code
2. Use "Reopen in Container" (Dev Containers extension required)
3. Wait for container initialization to complete
4. Run npm test to verify environment is working
5. Make changes and run tests inside the container

Quick Reference

Command	Description
npm test	Run all unit tests
npm run test:unit	Run unit tests only
npm run test:integration	Run integration tests
npm run dev:container	Start dev server (container)
npm run build	Build for production