# Agent guide — hnh-map

Automapper server for HnH, (mostly) compatible with [hnh-auto-mapper-server](https://github.com/APXEOLOG/hnh-auto-mapper-server). This repo is a monorepo: Go backend + Nuxt 3 frontend.

## Structure

| Path | Purpose |
|------|--------|
| `cmd/hnh-map/` | Go entry point (`main.go`) |
| `internal/app/` | App struct, domain types, router, topic pub/sub, migrations |
| `internal/app/store/` | bbolt database access layer (`db.go`, `buckets.go`) |
| `internal/app/services/` | Business logic (`auth.go`, `map.go`, `admin.go`, `client.go`, `export.go`) |
| `internal/app/handlers/` | HTTP handlers (`api.go`, `auth.go`, `map.go`, `client.go`, `admin.go`, `tile.go`) |
| `internal/app/apperr/` | Domain error types |
| `internal/app/response/` | Shared JSON response utilities |
| `frontend-nuxt/` | Nuxt 3 app source (pages, components, composables, layouts, `public/gfx`) |
| `frontend/` | **Build output** — static assets served in production; generated from `frontend-nuxt/` (do not edit here) |
| `docs/` | Architecture, API, configuration, development, deployment, testing |
| `grids/` | Runtime data (in `.gitignore`) |

## Where to look

- **API:** [docs/api.md](docs/api.md) and handlers in `internal/app/handlers/` (e.g. `api.go`, `auth.go`, `admin.go`, `map.go`, `client.go`, `tile.go`).
- **Business logic:** `internal/app/services/` (e.g. `auth.go`, `map.go`, `admin.go`, `client.go`, `export.go`).
- **Database:** `internal/app/store/db.go` and `internal/app/store/buckets.go`.
- **Configuration:** [.env.example](.env.example) and [docs/configuration.md](docs/configuration.md).
- **Local run / build:** [docs/development.md](docs/development.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
- **Testing:** [docs/testing.md](docs/testing.md).

## Conventions

- **Backend:** Go; use `make fmt` / `make lint`; tests with `make test` or `go test ./...`.
- **Frontend:** Nuxt 3 in `frontend-nuxt/`; public API access via composables (e.g. `useMapApi`, `useAuth`, `useAdminApi`).
- **Ports:** Dev — frontend 3000, backend 3080 (docker-compose.dev); prod — single server 8080 serving backend + static from `frontend/`.
- **Architecture:** Layered: Store → Services → Handlers. Domain errors in `apperr/` are mapped to HTTP status codes by handlers.

See [.cursor/rules/](.cursor/rules/) for project-specific Cursor rules.