---
name: backend-fast-path
description: 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`.

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

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

If Docker-related changes are made:

```bash
docker compose config
```