Files

Nikolay Tatarinov 6529d7370e Add configuration files and update project documentation

- Introduced .editorconfig for consistent coding styles across the project.
- Added .golangci.yml for Go linting configuration.
- Updated AGENTS.md to clarify project structure and components.
- Enhanced CONTRIBUTING.md with Makefile usage for common tasks.
- Updated Dockerfiles to use Go 1.24 and improved build instructions.
- Refined README.md and deployment documentation for clarity.
- Added testing documentation in testing.md for backend and frontend tests.
- Introduced Makefile for streamlined development commands and tasks.

2026-03-01 01:51:47 +03:00

2.2 KiB

Raw Blame History

Contributing to hnh-map

Getting started

Clone the repository and run the project locally (see Development):

Option A: Docker Compose for development: docker compose -f docker-compose.dev.yml up (or make dev). Frontend on 3000, backend on 3080.
Option B: Run Go backend from the repo root (go run ./cmd/hnh-map -grids=./grids -port=8080) and Nuxt separately (cd frontend-nuxt && npm run dev). Ensure the frontend can reach the backend (proxy or same host).

Code layout

The backend follows a layered architecture: Store → Services → Handlers.

Backend: Entry point is cmd/hnh-map/main.go. Application logic lives in internal/app/:
- app.go — App struct, domain types, SPA serving, constants.
- router.go — route registration.
- topic.go — pub/sub for real-time updates.
- migrations.go — database migrations.
- store/ — bbolt database access layer (db.go, buckets.go).
- services/ — business logic (auth.go, map.go, admin.go, client.go, export.go).
- handlers/ — HTTP handlers (api.go, auth.go, map.go, client.go, admin.go, tile.go, handlers.go, response.go).
- apperr/ — domain error types.
- response/ — shared JSON response helpers.
Frontend: Nuxt 3 app in frontend-nuxt/ (pages, components, composables, layouts, plugins, public/gfx). It is served by the Go backend at root / with baseURL /.

Formatting, linting, and tests

Use Makefile targets for common tasks:

make fmt      # Format all code (Go + frontend)
make lint     # Run Go linter (golangci-lint) and frontend ESLint
make test     # Run Go tests

Or run manually:

Go: go fmt ./... and golangci-lint run
Frontend: npm --prefix frontend-nuxt run lint and npm --prefix frontend-nuxt run format
Tests: go test ./...

Always format and lint before committing. Add or update tests if you change behaviour.

Submitting changes

Open a pull request with a clear description of the change.
Mention compatibility with hnh-auto-mapper-server if relevant (e.g. client protocol or API).