student-3

Imported from YourNightmareIsOver/TripGenie (student-3/AGENTS.md). Install upstream with npx skills add YourNightmareIsOver/TripGenie --skill student-3. Copyright stays with the author.

Student 3: Transport Management

This file supplements the repository-level AGENTS.md for student-3/.

Ownership and integration

• Student 3 owns transport options, comparison, and transport recommendations.
• frontend/ serves port 8093, backend/ exposes public /api routes on port 8003, and database/ exposes private /internal routes on port 8004.
• Port 8093 is intentional. Keep docker-compose.yml, the shared landing-page link, configuration examples, and smoke tests aligned if it changes.
• The backend uses Student 1 for trip selection and itinerary association. Transport browsing and comparison must continue when Student 1 or AI-Mode is unavailable unless the requested operation intrinsically needs that service.
• AI recommendations are advisory, use the packaged prompt asset, and may only recommend authoritative transport records. The model finds them itself through AI-Mode's MCP tool loop; a suggestion is accepted only if a successful Student 3 transport tool returned its id in the same run.
• Release 1 MCP lookups call the shared MCP server's read-only transport tools through allow-listed backend actions. Those tools read this backend back on 127.0.0.1:18003, so MCP route handlers must stay synchronous (def).
• Release 2 multi-agent planning runs on the shared host-run Multi-Agent Server with this feature's own prompt, schema and transport tools. The server never writes Student 3 data: after a human approves, the backend adds only grounded suggestions through the normal plan-entry rules.
• tests/endpoint holds the Release 2 post-commit endpoint tests. They run only in student-3-ci.yml against the live Compose slice, so testpaths leaves them out of ordinary pytest runs.
• Read the README in each layer before changing its behavior or contract.

Development and verification

Run from student-3/ after python -m pip install -e ".[dev]":

python -m compileall database/student3_database_service tests/database
python -m pytest tests/database
python -m compileall backend/student3_backend_service tests/backend
python -m pytest tests/backend
python -m compileall frontend/student3_frontend_service tests/frontend
python -m pytest tests/frontend

Run Ruff from the repository root for the affected package and tests. Validate images and the isolated Compose slice when integration settings change:

docker compose config --quiet
docker compose up -d --build --wait --no-deps student-3-database student-3-backend student-3-frontend

Clean up with docker compose down -v only when all local TripGenie Compose volume data may be removed. Test money and capacity rules without floats, downstream clients with injected transports, and full-page plus HTMX flows in frontend tests.