# Repository Guidelines

## Project Structure & Module Organization
- `cmd/server/main.go` is the Fiber entrypoint that wires config, routes, and startup logging.
- `internal/geo` owns GeoLite2 lookups, IP validation, and response shaping.
- `docker-compose.yml` defines the container entry; `Dockerfile` builds a static binary. `GeoLite2-City.mmdb` sits at the repo root and is mounted to `/initial_data/GeoLite2-City.mmdb`.
- Keep `cmd/server` thin; place new logic in `internal/<domain>` with clear boundaries.

## Build, Test, and Development Commands
- `SERVICE_PORT=8080 GEOIP_DB_PATH=./GeoLite2-City.mmdb go run ./cmd/server` runs the API locally without Docker.
- `docker compose up --build` builds and starts the containerized service (mounts the local database).
- `curl "http://localhost:8080/lookup?ip=1.1.1.1"` exercises the lookup endpoint; omit `ip` to use the caller’s address.
- `go build ./...` validates compilation before pushing changes.

## Coding Style & Naming Conventions
- Go 1.22; always format with `gofmt -w`.
- Favor small packages and dependency injection for services (e.g., pass resolvers, do not use globals).
- Package names are lowercase; exported identifiers use CamelCase; environment variables use UPPER_SNAKE.
- Keep JSON response shapes stable; prefer explicit structs over maps for API outputs.

## Testing Guidelines
- Use Go’s standard testing with `*_test.go` files and run `go test ./...`.
- Prefer table-driven tests for lookup edges (IPv4/IPv6, invalid IP, missing city/region data).
- For integration tests, allow overriding `GEOIP_DB_PATH` with a fixture `.mmdb` to avoid mutating the bundled dataset.

## Commit & Pull Request Guidelines
- Commit titles should be concise, imperative English with an optional scope (`geo`, `server`, `build`).
- Add a short body describing intent and behavioral impact when relevant.
- PR descriptions should list linked issues, test commands executed, and a sample request/response payload when API output changes.
- Keep images lean; avoid adding unused assets or oversized binaries to the image layers.

## Security & Configuration Tips
- GeoLite2 carries licensing; refresh by replacing `GeoLite2-City.mmdb` with the latest download rather than mirroring it elsewhere.
- Validate IP inputs and avoid logging full client IPs with stack traces in sensitive environments.
- Behind proxies, configure trusted proxy headers so `X-Forwarded-For` is respected (Fiber `app.Config.ProxyHeader` can be set if needed).