lta_datamall_api/AGENTS.md

AGENTS

Guidance for AI coding agents working in this repository.

Project Snapshot

• Purpose: FastAPI backend proxy for LTA DataMall Bus Transport APIs.
• Runtime: Python 3.12 with uv-managed environment.
• Container: Podman or Docker via compose.
• API docs source: docs/LTA_DataMall_API_User_Guide.pdf
• OpenAPI reference: openapi.json

First Commands To Run

• Install dependencies: make sync
• Compile check: make compile
• Run local dev server: make run
• Show available targets: make help

If Make targets are unavailable, use direct uv commands from README.md.

Build, Run, and Ops Commands

• Dependency sync: make sync
• Dev server with reload: make run
• Production server: make prod
• Compile check: make compile
• Compose up: make compose-up
• Compose down: make compose-down
• Compose logs: make compose-logs
• Compose services: make compose-ps

No test or lint targets are defined yet.

Required Environment

• Required env var: DATAMALL_API_KEY
• Local env file: .env
• Template: .env.example
• Ignore rule already set in .gitignore

The app fails to start if DATAMALL_API_KEY is missing.

Architecture Map

• App entrypoint and lifespan wiring: app/main.py
• Settings and env loading: app/core/config.py
• Upstream HTTP client wrapper: app/services/lta_client.py
• Bus API routes: app/api/routes/bus.py
• Health routes: app/api/routes/health.py
• Container build: Dockerfile
• Compose deployment: docker-compose.yml

Coding Conventions For This Repo

• Keep endpoint namespace under /api/v1.
• Preserve upstream query parameter names using aliases such as BusStopCode, ServiceNo, Date, and $skip.
• Route handlers return upstream JSON payloads directly unless feature work requires transformation.
• Centralize outbound DataMall logic in app/services/lta_client.py, not inside routes.
• Add new environment variables in app/core/config.py and document them in .env.example.

Change Safety Checklist

Before finishing edits:

• Run make compile
• If Docker or Podman is available, run make compose-up and verify health endpoint
• Ensure .env is not modified with secrets intended for commit
• Update README.md when commands, routes, or behavior changes

Known Gaps

• No automated tests yet
• No lint or format tooling configured
• app/schemas currently has no domain models

When adding major features, consider adding tests and response schemas.