galaxium-travels: Instructions file for Codex

Galaxium Travels

A demo interplanetary flight-booking app that mimics a real enterprise system. Its purpose is to showcase challenges agents face in a multi-service codebase — not to run in production.

When you are asked to create a plan while in agent mode, do other things you need to do, like gathering data from a CLI and then explicitly switch to plan mode.

When creating planning documents, put them on the root level in all caps.

Before you start building anything look for information about tests and verification

For any exploration task, use subagents. E.g. when you are asked to create an onboarding document

Footguns

• MCP server MUST be created before FastAPI app — server.py line 22 instantiates FastMCP before FastAPI. Swapping the order breaks lifespan composition.
• MCP tools bypass FastAPI DI — they call SessionLocal() and db.close() directly; they do NOT use Depends(get_db).
• Service functions return Union types, not exceptions — booking.py returns BookingOut | ErrorResponse. Callers check isinstance(result, ErrorResponse).
• book_flight() validates both user_id AND name — intentional non-standard security pattern; name mismatch rejects the booking.
• SQLite is the production database — DATABASE_URL is intentionally unset on ECS; db.py defaults to ./booking.db. Data is ephemeral per container task.
• SEED_DEMO_DATA=true re-seeds on every start — set to false if you need data to survive a restart locally.
• Tests must patch SessionLocal in two places — conftest.py lines 49–50 patches both db.SessionLocal and server.SessionLocal. Patching only one leaves the MCP tools hitting the real DB.
• Java hold service requires Java 17 or 21 — Lombok does not support Java 22+. The start script auto-detects sdkman candidates; set JAVA_HOME manually if needed.
• docker-compose.yml Java service is behind a profile — it uses profiles: [hold-service]. Run docker compose --profile hold-service up to include it, or use e2e/docker-compose.e2e.yml which enables it unconditionally.
• Python proxy swallows Java 404s — proxy endpoints in server.py catch httpx.HTTPError and return {"error": "..."} with HTTP 200. Callers must check the response body, not just the status code (see test_holds.py line 82).
• holds.db and booking.db are committed artefacts — do not delete; they seed local dev. They are regenerated on startup via spring.jpa.hibernate.ddl-auto=update and SEED_DEMO_DATA=true.
• Some of the rules above are enforced by lifecycle hooks, not just documented — see .bob/settings.json. Deleting a .db file and committing while the backend suite is red are both blocked outright. If a tool call is reported as blocked, read .bob/hooks/state/.last-block for the reason — the hook writes the full explanation there.