Improve developer integration docs and Docker dev workflow.

Add TypeScript frontend integration documentation, repository agent guidance files, Go-served frontend routing, and an advanced Docker Compose setup with watch mode plus BuildKit cache configuration. Made-with: Cursor
2026-03-01 11:57:22 +00:00
parent 242acd7fa6
commit f51126419c
8 changed files with 265 additions and 8 deletions
@@ -0,0 +1,50 @@
+# 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:
+
+```bash
+go test ./...
+go run ./cmd/api
+docker compose up --build -d
+docker compose down
+```
+
+TypeScript client:
+
+```bash
+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.
+- If CI fails due runner/network infrastructure, keep logs explicit in workflow output.