# CLAUDE.md — Pamietnik Backend (Go Server)

## Stack

Language:   Go
DB:         PostgreSQL
API-Doc:    OpenAPI 3.1 (openapi.yaml)
Auth:       Session Cookie (Web UI); API-Key oder JWT (Android Upload, TBD)
Hashing:    Argon2id (Passwörter)
Geocoding:  Nominatim (OSM) mit Cache + Rate-Limit; Provider austauschbar
Maps:       OpenStreetMap Tiles (konfigurierbar, serverseitig)
Dev:        docker-compose (API + PostgreSQL)

---

## Kern-Features (Backend)

1. REST API Ingest: Single + Batch Trackpoints (Idempotenz via event_id)
2. Idempotenz/Dedupe: Unique Key (device_id, event_id); Duplikate = 200 OK
3. Stop Detection: Aufenthalte erkennen (minDuration + radiusMeters konfigurierbar)
4. Suggestions: Aus Stops Vorschläge ableiten + speichern
5. Reverse-Geocoding: Nominatim gecached, Provider austauschbar via Config
6. Web UI: Login (Session Cookie), Tagesübersicht, Tagesdetail, Karte
7. Auth: Argon2id Passwort-Hashing, Session-Store in PostgreSQL

---

## API Endpoints

Ingest:
  POST   /v1/trackpoints            <- Single Trackpoint
  POST   /v1/trackpoints:batch      <- Batch Trackpoints
  GET    /healthz
  GET    /readyz

Query (Auth required):
  GET    /v1/days?from=YYYY-MM-DD&to=YYYY-MM-DD
  GET    /v1/trackpoints?date=YYYY-MM-DD
  GET    /v1/stops?date=YYYY-MM-DD
  GET    /v1/suggestions?date=YYYY-MM-DD

Web UI (Session Cookie, serverseitig gerendert):
  GET    /login
  POST   /login
  POST   /logout
  GET    /days
  GET    /days/{yyyy-mm-dd}

---

## Datenmodell (Kern)

Trackpoint:
  event_id    string (UUID, client-generated)
  device_id   string
  trip_id     string
  timestamp   RFC3339 oder epochMillis (TBD)
  lat, lon    float64
  source      "gps" | "manual"
  note        string (optional)

Stop:
  stop_id     string
  device_id, trip_id
  start_ts, end_ts
  center_lat, center_lon
  duration_s  int
  place_label string (optional, Nominatim)

Suggestion:
  suggestion_id
  stop_id
  type        "highlight" | "name_place" | "add_note"
  title/text  string
  created_at, dismissed_at

---

## Architektur-Prinzipien

- Idempotenz zuerst: Kein Duplicate Insert, immer event_id prüfen
- Geocoding nur ereignisbasiert (pro Stop), niemals periodisch/bulk
- Geocoding-Provider über Config austauschbar (kein Hardcode)
- Sessions serverseitig in PostgreSQL (invalidierbar bei Logout)
- Stop Detection Parameter (minDuration, radiusMeters) konfigurierbar
- OpenAPI immer aktuell halten; Änderungen nur via PR + CI Validation

---

## Offene Entscheidungen (TBD)

- timestamp Format: epochMillis vs RFC3339
- Android Upload Auth: X-API-Key vs JWT
- Payload: JSON vs Protobuf
- Batch limits (max items, max bytes)
- Retention Policy (Trackpoints löschen nach X Tagen)
- Stop-Detection Parameter (Mindestdauer, Radius)
- Geocoding Provider: Nominatim public vs self-hosted vs Alternative

---

## Nächste Tasks (Reihenfolge)

- [ ] T024  REST API finalisieren (Endpoints, Fehlerformat, Limits)
- [ ] T027  PostgreSQL Schema + Migrationen + Indizes
- [ ] T028  Idempotenz implementieren (unique event_id pro device)
- [ ] T029  Observability (Logs/Metrics), Health/Ready
- [ ] T030  docker-compose lokal (API + PostgreSQL) + Minimal-Client
- [ ] T050  Auth-Konzept festlegen