backend/AGENTS.md

AGENTS.md

This file gives future coding agents a fast path map for this repository.

Repository map

• API entrypoint: cmd/api/main.go
• HTTP routes/handlers: internal/http/handlers.go
• Core domain logic: internal/app/service.go
• In-memory persistence: internal/store/
• Auth utilities: internal/auth/
• Frontend static app: web/
• TypeScript API client: libs/geo-api-client/
• CI workflow: .gitea/workflows/ci.yml
• Architecture/planning docs: docs/

Most common commands

From repo root:

go test ./...
go run ./cmd/api
docker compose up --build -d
docker compose down

TypeScript client:

cd libs/geo-api-client
bun install
bun test
bun run build

Path conventions

• Use repository-relative paths in docs and comments (never absolute machine paths).
• Keep API route changes in internal/http/handlers.go.
• Keep business rule changes in internal/app/service.go.
• Keep frontend integration docs under docs/.

Editing guidance for agents

• Prefer minimal changes and avoid unrelated refactors.
• Add tests when behavior changes.
• Verify Go tests after backend changes.
• Verify Bun tests after TS client changes.
• For DB-required tests, prefer embedded/ephemeral Postgres fixtures over relying on an externally managed database.
• If CI fails due runner/network infrastructure, keep logs explicit in workflow output.