mirror of
https://github.com/furyhawk/lta_datamall_api.git
synced 2026-07-20 09:48:00 +00:00
furyhawk
f10ab4e7b3
- Add CacheClient for managing Valkey interactions - Integrate caching into bus API routes for improved performance - Update .env.example and config.py for Valkey settings - Modify Makefile and README for Valkey service management - Add Valkey service to docker-compose - Include Valkey dependency in pyproject.toml and uv.lock
2.9 KiB
2.9 KiB
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
- Valkey cache client wrapper: app/services/cache.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.
- Keep cache reads/writes inside route helper flow; do not duplicate cache key logic across handlers.
- 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.