rd13_tile_server/docs/MAINTAINER.md

# Maintainer-Handbuch – rd13_tile_server

> Zielgruppe: **Entwickler & Maintainer** – Menschen, die den Code verstehen, erweitern oder reviewen.
> Voraussetzung: Entwicklungserfahrung mit Docker, MapLibre GL Styles, OSM-Daten.

---

## Architektur – Martin + tileserver-gl Stack

```
Internet (HTTPS)
    ↓
NPM Reverse Proxy (tiles.rd13server.de, Rate Limiting)
    ├─ /osm/{z}/{x}/{y}.pbf → Martin (Vektor-Tiles)
    └─ /osm-intl/{z}/{x}/{y}.png → tileserver-gl (Raster-PNG)
         ↓
    tileserver-gl renders Martin Vektor → PNG
         ↓
    Martin reads osm.mbtiles (Vector Tiles)
         ↓
    /data/osm.mbtiles (OpenFreeMap snapshot)
```

**Stack-Komponenten:**

| Komponente | Input | Output | Verantwortung |
|---|---|---|---|
| **Martin** | `osm.mbtiles` | `/{layer}/{z}/{x}/{y}.pbf` | Vektor-API, Tile-Distribution |
| **tileserver-gl** | Martin PBF + `osm-intl.json` | `/{style}/{z}/{x}/{y}.png` | Rendering, PNG-Tile-Cache |
| **NPM** | HTTP Client Requests | HTTPS Responses | Proxy, SSL, Rate-Limit |

**Verwandte ADRs:**
- [ADR-001: Tile Rendering Stack – Martin + tileserver-gl](docs/adr/001-martin-tileserver-gl-stack.md)

---

## Projektstruktur

```
rd13_tile_server/
├── config/
│   └── martin.yaml                    ← Martin Server-Konfiguration
├── data/
│   ├── osm.mbtiles                    ← OpenFreeMap Vector-Snapshot (~94 GB)
│   ├── styles/
│   │   └── osm-intl.json              ← MapLibre GL Style für Raster-Rendering
│   ├── fonts/
│   │   ├── Metropolis Black/
│   │   ├── Open Sans Regular/
│   │   └── … (47 weitere Font-Varianten)
│   └── sprites/                       ← Marker/Icons (derzeit leer)
├── docs/
│   ├── adr/
│   │   ├── 000-template.md
│   │   └── 001-martin-tileserver-gl-stack.md
│   ├── history/
│   ├── requirements/
│   │   └── REQUIREMENTS.md
│   ├── USER.md, ADMIN.md, MAINTAINER.md
│   └── … (API-Endpoints, Integration-Guides)
├── docker-compose.yml                 ← Martin + tileserver-gl
└── scripts/
    ├── download-data.sh               ← OSM-MBTiles fetcher
    └── download-satellite.py          ← Satellit-MBTiles fetcher (optional)
```

---

## Style-Customization (osm-intl.json)

Die Kartographer-Karten werden von `data/styles/osm-intl.json` definiert. Das ist eine Standard **MapLibre GL Style** (v8-kompatibel).

### Tipps zum Ändern

**1. Farben anpassen** (einfach)

```json
"layers": [
  {
    "id": "water-area",
    "paint": {
      "fill-color": "#b0d4fc"  ← Ändere zu z.B. "#0066cc"
    }
  }
]
```

**2. Layer-Sichtbarkeit nach Zoom-Level** (mittelschwer)

```json
{
  "id": "poi-icon",
  "minzoom": 14,        ← POI-Icons nur ab Zoom 14 sichtbar
  "maxzoom": 20        ← Max Zoom-Level
}
```

**3. Label-Schriftart** (mittelschwer)

```json
"text-font": ["Open Sans Bold"]  ← Verfügbare Fonts in data/fonts/
```

**Verfügbare Fonts** (aus `/data/fonts/`):
- Metropolis (Black, Bold, Light, Regular, Thin + Italic-Varianten)
- Open Sans (Bold, Regular, Semibold + Italic-Varianten)
- PT Sans (Bold, Caption, Regular, Narrow + Varianten)
- Roboto (Black, Bold, Light, Medium, Regular, Thin + Italic-Varianten)
- Noto Sans (Bold, Italic, Regular)

**4. Linien-Dicke nach Zoom-Level** (fortgeschritten)

```json
"line-width": [
  "interpolate",     ← Interpolations-Funktion
  ["linear"],        ← Linear interpolieren
  ["zoom"],          ← Input: aktueller Zoom-Level
  6, 0.5,            ← Bei Zoom 6: 0.5px
  20, 6              ← Bei Zoom 20: 6px
]
```

### Style testen (lokal)

```bash
# Nach Änderungen an osm-intl.json:
docker compose restart tileserver

# PNG-Tile abrufen
curl -s "http://localhost:9983/osm-intl/10/544/335.png" -o /tmp/test.png
file /tmp/test.png

# In MediaWiki-Kartographer URL testen:
# https://tiles.rd13server.de/osm-intl/{z}/{x}/{y}.png
```

---

## Martin Vector-Source verstehen

Martin liest Vektor-Daten aus `osm.mbtiles` und serviert sie als PBF (Protocol Buffers).

**Available Layers in osm.mbtiles** (abhängig von OpenFreeMap-Schema):

Beispiel: `http://localhost:9982/catalog` zeigt alle Source-Layer.

Typisch enthalten:
- `water` – Seen, Flüsse
- `landuse` – Wald, Park, Gras, Acker
- `building` – Gebäude-Polygone
- `road` – Straßen (Motorway, Trunk, Primary, Secondary, etc.)
- `railway` – Eisenbahn-Linien
- `place` – Orte (City, Town, Village)
- `poi` – Points of Interest

**Layer in osm-intl.json updaten:**

```json
"source": "osm",           ← Vector-Tile-Source (Martin)
"source-layer": "water",   ← Welcher OSM-Layer? (prüfe /catalog)
```

Falls Layer fehlt → `http://localhost:9982/catalog` prüfen, oder mit `layer` in osm-intl.json experimential einen neuen hinzufügen.

---

## Rendering-Performance tunen

**tileserver-gl Cache:**

- **Disk-Cache:** `/tmp/pmtiles-cache` (wächst mit Nutzung; max ~50 GB bei voller Coverage)
- **Memory:** ~500 MB standard, skaliert mit Anfrage-Load
- **Warm-up:** Erste Anfrage zu neuem Tile-Bereich ist langsam (~100–200ms), danach <20ms

**Bottleneck identifizieren:**

```bash
# Logs verfolgen (live)
docker compose logs -f tileserver | grep "render"

# Performance der Martin-API
curl -w "Time: %{time_total}s\n" -s http://localhost:9982/osm/0/0/0 | head
```

**Falls zu langsam:**
1. Martin-Worker-Prozesse erhöhen: `config/martin.yaml` → `worker_processes`
2. tileserver-gl Memory erhöhen: docker-compose.yml → `deploy.resources.limits.memory`

---

## Tests & Validierung

### Tile-Integrität checken

```bash
# Vektor-Tile (PBF) abrufen und inspizieren
curl -s "http://localhost:9982/osm/0/0/0.pbf" | file -
# Should: PBF (Tile protocol buffer)

# Raster-Tile (PNG) abrufen und prüfen
curl -s "http://localhost:8080/osm-intl/0/0/0.png" -o /tmp/t.png
file /tmp/t.png
# Should: image/png

# MediaWiki-Test URL
# https://tiles.rd13server.de/osm-intl/0/0/0.png
```

### Smoke-Test nach Update

```bash
# Nach Tile-Daten-Update (osm.mbtiles):
for zoom in 0 5 10 14; do
  curl -s "http://localhost:9983/osm-intl/$zoom/0/0.png" \
    -o /tmp/test_z$zoom.png && echo "✓ Zoom $zoom" || echo "✗ Zoom $zoom"
done
```

---

## Deployment & Release

### Checklist vor Push

- [ ] `docker compose logs` prüfen – keine Errors
- [ ] Test-Tiles (Zoom 0, 5, 10, 14) erfolgreich
- [ ] REQUIREMENTS.md aktualisiert (falls Anforderung geändert)
- [ ] ADR erstellt (falls architektur-relevant)
- [ ] ADMIN.md / MAINTAINER.md aktualisiert
- [ ] CHANGELOG.md aktualisiert (falls vorhanden)
- [ ] Git commit + push

### Version & Releases

Derzeit: `rolling release` (jeder Commit ist live).

Falls später strikte Versionierung nötig:
- Versioning: Semantic Versioning (MAJOR.MINOR.PATCH)
- Releases: Tag in Git + Changelog
- Example: `v1.0.0` (Martin 0.9.0 + tileserver-gl 4.7.0)

---

## Bekannte Limitations & Future TODOs

**Jetzt (ADR-001):**
- ✅ Martin + tileserver-gl für statische 2–4×/Year Updates
- ✅ Styles anpassbar (osm-intl.json)
- ✅ Fonts + Sprites nutzbar

**Zukünftig (Falls nötig):**
- [ ] **ADR-002:** Live OSM-Update-Pipeline (OpenMapTiles Server)
- [ ] Sprites/Icons erweitern (derzeit leer)
- [ ] Mehrere Styles pro Kartographie-Kontext (dark mode, print-optimized)
- [ ] Horizontal scaling (Kubernetes / Load Balancer)

---

## Ressourcen

- [Martin Tile Server Documentation](https://maplibre.org/martin/)
- [tileserver-gl Documentation](https://tileserver.readthedocs.io/)
- [MapLibre GL Style Specification v8](https://maplibre.org/maplibre-gl-js-docs/style-spec/)
- [OpenMapTiles Schema](https://openmaptiles.org/schema/)
- [OSM Wiki: Map Tiles](https://wiki.openstreetmap.org/wiki/Tiles)
cd <repo>
# Dependencies installieren
# Dev-Server starten
```

---

## Architekturentscheidungen (ADRs)

ADR-Dateien liegen unter `docs/adr/`. Format: `NNN-titel.md`.

| Nr. | Titel | Status | Datum |
|---|---|---|---|
| 000 | Template | accepted | … |

---

## Coding-Konventionen

<!-- TODO: Projektspezifische Konventionen -->

- **Branches:** `feat/<ticket>-beschreibung`, `fix/<ticket>-beschreibung`
- **Commits:** Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
- **Tests:** `tests/` spiegelt Source-Struktur, ≥ 80% Coverage
- **Linting:** …

---

## Agent-Kontext & History

Der Agent liest beim Start immer `history/summary/PROJECT_CONTEXT.md`.
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.

- Vollständige Konversationen: `history/prompts/` (committed – History bleibt vollständig erhalten)
- Komprimierter Kontext: `history/summary/PROJECT_CONTEXT.md` (committed)

---

## Neues Feature hinzufügen

1. `history/summary/PROJECT_CONTEXT.md` lesen – aktuellen Stand verstehen
2. Issue / Ticket anlegen
3. Branch: `git checkout -b feat/<ticket>-beschreibung`
4. Implementieren + Tests schreiben
5. Dokumentation in `docs/USER.md` oder `docs/ADMIN.md` aktualisieren
6. `git commit` – Quality Gate läuft automatisch (pre-commit hook)
7. PR erstellen + Review

---

## Designentscheidungen

| Entscheidung | Begründung |
|---|---|
| … | … |