hnh-map/docs/architecture.md

Architecture of hnh-map

Overview

hnh-map is an automapper server for HnH: a Go backend with bbolt storage, sessions, and a Nuxt 3 SPA served at /. API, SSE, and tiles are served at /map/api/, /map/updates, /map/grids/. Grid and tile data is stored in the grids/ directory and in the database.

┌─────────────┐     HTTP/SSE      ┌──────────────────────────────────────┐
│   Browser    │ ◄────────────────► │  Go server (cmd/hnh-map)              │
│  (Nuxt SPA   │   /, /login,      │  • bbolt (users, sessions, grids,      │
│   at /)      │   /map/api,       │    markers, tiles, maps, config)        │
│              │   /map/updates,   │  • Frontend statics (frontend/)         │
│              │   /map/grids/     │  • internal/app — all logic             │
└─────────────┘                   └──────────────────────────────────────┘

Backend structure

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

• cmd/hnh-map/main.go — the single entry point (package main): parses flags (-grids, -port) and environment variables (HNHMAP_PORT), opens bbolt, runs migrations, creates App, wires services and handlers, registers routes, and starts the HTTP server. Paths to frontend/ and public/ are resolved relative to the working directory at startup.

• internal/app/ — package app with the App type and domain types:

  • app.go — App struct, domain types (Character, Session, Coord, Position, Marker, User, MapInfo, GridData, etc.), SPA serving (ServeSPARoot), character cleanup (CleanChars), constants.
  • router.go — route registration (Router), interface APIHandler.
  • topic.go — generic Topic[T] pub/sub for broadcasting tile and merge updates.
  • migrations.go — bbolt schema migrations; called from main via RunMigrations(db).

• internal/app/store/ — database access layer:

  • db.go — Store struct with bucket helpers and CRUD operations for users, sessions, tokens, config, maps, grids, tiles, markers, and OAuth states.
  • buckets.go — bucket name constants.

• internal/app/services/ — business logic layer:

  • auth.go — AuthService: authentication, sessions, password hashing, token validation, OAuth (Google) login flow.
  • map.go — MapService: map data retrieval, tile save/get, zoom level processing, SSE watch, character/marker access.
  • admin.go — AdminService: user management, settings, map management, wipe, tile operations.
  • client.go — ClientService: game client operations (grid update, grid upload, position updates, marker uploads).
  • export.go — ExportService: data export (ZIP) and merge (import).

• internal/app/handlers/ — HTTP handlers (thin layer over services):

  • handlers.go — Handlers struct (dependency container), HandleServiceError.
  • response.go — JSON response helpers.
  • api.go — top-level API router (APIRouter).
  • auth.go — login, logout, me, setup, OAuth, token, and password handlers.
  • map.go — config, characters, markers, and maps handlers.
  • client.go — game client HTTP handlers (grid update/upload, positions, markers).
  • admin.go — admin HTTP handlers (users, settings, maps, wipe, tile ops, export, merge).
  • tile.go — tile image serving and SSE endpoint.

• internal/app/apperr/ — domain error types mapped to HTTP status codes by handlers.

• internal/app/response/ — shared JSON response utilities.

Build from the repository root:

go build -o hnh-map ./cmd/hnh-map