backend/SKILL.md

name, description

name	description
backend-fast-path	Quick orientation and execution paths for agents working in this repository.

Skill: Backend Fast Path

Use this skill when implementing or debugging backend, frontend integration, TypeScript client, or CI behavior in this repository.

Key paths

• API bootstrap: cmd/api/main.go
• HTTP layer: internal/http/handlers.go
• Service logic: internal/app/service.go
• Tests (Go): internal/http/api_test.go
• Frontend app (served by Go): web/index.html, web/app.js, web/api.js
• TS client source: libs/geo-api-client/src/
• TS client tests: libs/geo-api-client/test/
• CI pipeline: .gitea/workflows/ci.yml
• Dev docs: README.md, docs/typescript-frontend-integration.md, docs/geo-auth-backend-plan.md

Task routing rules

1. API behavior changes

   • Update internal/app/service.go first.
   • Then wire request/response changes in internal/http/handlers.go.
   • Add/update tests in internal/http/api_test.go.
   • If persistence behavior is under test, use embedded/ephemeral Postgres fixtures (no external DB dependency for standard test runs).

2. Frontend integration changes

   • Update TS client first in libs/geo-api-client/src/.
   • Then update web/ integration usage if needed.
   • Document usage changes in docs/typescript-frontend-integration.md.

3. CI failures

   • Inspect .gitea/workflows/ci.yml.
   • Keep logs actionable.
   • Preserve explicit warnings when infrastructure prevents source checkout/tests.

Verification checklist

go test ./...
cd libs/geo-api-client && bun test && bun run build

If Docker-related changes are made:

docker compose config