docs: massive restructuring of documentation, development guides and agent playbooks

docs/04_Operations/Infrastructure/Reference/ports-and-urls.md

@@ -0,0 +1,48 @@
+---
+type: Reference
+owner: DevOps Engineer
+status: ACTIVE
+review_cycle: 180d
+last_reviewed: 2025-10-31
+summary: "Übersicht der wichtigsten lokalen URLs und Ports. Quelle: docker-compose.yaml + config/env"
+last_update: 2026-03-15
+---
+
+# Referenz: Wichtige URLs und Ports (lokal)
+
+Quelle der Wahrheit für Ports/URLs (Repo-aktuell):
+
+* `docker-compose.yaml`
+* `config/env/.env` (und optional `config/env/.env.local`)
+
+## Infrastruktur
+
+- API Gateway: http://localhost:8081
+- Keycloak (Auth): http://localhost:8180
+- Consul (Service Discovery): http://localhost:8500
+- PostgreSQL: localhost:5432
+- Redis: localhost:6379
+
+## Services
+
+- Ping Service: http://localhost:8082
+- Members Service: http://localhost:8083
+- Horses Service: http://localhost:8084
+- Events Service: http://localhost:8085
+- Masterdata Service: http://localhost:8086
+
+## Monitoring
+
+- Prometheus: http://localhost:9090
+- Grafana: http://localhost:3000
+
+## Clients
+
+- Web App: http://localhost:4000
+- Desktop App (VNC): localhost:5901
+- Desktop App (noVNC): http://localhost:6080
+
+## Hinweise
+
+- Die oben genannten Ports sind aus dem aktuellen Compose-/Env-Setup abgeleitet.
+- Bei Port-Konflikten passe die Werte in `config/env/.env` an (oder nutze lokale Overrides in `config/env/.env.local`).

docs/04_Operations/Infrastructure/Reference/zipkin.md

@@ -0,0 +1,42 @@
+---
+type: Reference
+status: ACTIVE
+owner: DevOps Engineer
+last_update: 2026-03-15
+---
+# Zipkin Tracing
+
+## Übersicht
+Zipkin ist ein verteiltes Tracing-System, das hilft, Latenzprobleme in Microservice-Architekturen zu analysieren. Es sammelt Timing-Daten, die benötigt werden, um Latenzprobleme in Service-Architekturen zu beheben.
+
+## Konfiguration in Docker Compose
+Der Zipkin-Service ist in der `docker-compose.yaml` definiert:
+
+```yaml
+  zipkin:
+    image: "${ZIPKIN_IMAGE:-openzipkin/zipkin:3}"
+    container_name: "${PROJECT_NAME:-meldestelle}-zipkin"
+    restart: no
+    ports:
+      - "${ZIPKIN_PORT:-9411:9411}"
+    profiles: [ "ops", "all" ]
+    networks:
+      meldestelle-network:
+        aliases:
+          - "zipkin"
+```
+
+## Integration in Services
+Die Services (`api-gateway`, `ping-service`, etc.) sind so konfiguriert, dass sie Tracing-Daten an Zipkin senden. Dies geschieht über Umgebungsvariablen in der `docker-compose.yaml`:
+
+```yaml
+      MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}"
+      MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}"
+```
+
+## Zugriff
+Die Zipkin UI ist unter `http://localhost:9411` erreichbar.
+
+## Troubleshooting
+- **Keine Traces sichtbar:** Stelle sicher, dass die Services korrekt gestartet sind und die Umgebungsvariablen für Zipkin gesetzt sind. Prüfe die Logs der Services auf Verbindungsfehler zu Zipkin.
+- **Zipkin nicht erreichbar:** Prüfe, ob der Container läuft (`docker ps`) und ob der Port 9411 nicht blockiert ist.