---
owner: project-owner
status: active
last_reviewed: 2025-10-15
review_cycle: 90d
summary: Gesamtüberblick – Was ist vorhanden, wie funktioniert es, wie starte/deploye ich es.
---

# Meldestelle – System Overview (Kurz & vollständig)

## Was ist vorhanden (Bausteine)
- Clients
  - Web App (Port 4000)
  - optional Desktop/noVNC (Port 6080)
- Gateway & Services
  - API Gateway (Spring Cloud Gateway, Port 8081)
  - Microservices: Members (8083), Horses (8084), Events (8085), Masterdata (8086), Ping (8082)
- Infrastruktur
  - Postgres (5432), Redis (6379), Keycloak (8180), Consul (8500)
- Reverse Proxy (Produktion)
  - Nginx auf Proxmox-Host
  - vHosts: `meldestelle.yourdomain.com` (Web), `api.meldestelle.yourdomain.com` (API), `vnc.meldestelle.yourdomain.com` (VNC)

## Wie funktioniert es (Ablauf & Verantwortungen)
- Einstieg nur über das API-Gateway (Security, CORS, Rate-Limits, Observability, Routing)
- Authentifizierung via Keycloak (OIDC/JWT)
  - Web holt Token bei Keycloak → sendet Requests mit `Authorization: Bearer <JWT>`
  - Gateway validiert JWT (JWKs), injiziert Kontext, routet an Services
- Service Discovery über Consul (Gateway ↔ Services)
- Persistenz: Services schreiben/lesen in Postgres; Redis optional für Cache
- Produktion: Öffentliche Zugriffe laufen über Nginx-vHosts → Gateway/Web/noVNC in Docker

## Starten & Stoppen (lokal)
- Komplettes System: `make full-up`
- Nur Infrastruktur: `make infrastructure-up`
- Nur Backend (inkl. Gateway): `make services-up`
- Nur Clients (inkl. Web): `make clients-up`
- Stoppen: `make full-down` (bzw. `*-down`)
- Logs: `make full-logs` (bzw. `services-logs`, `infrastructure-logs`)

## Health, URLs & Ports
- Web: `http://localhost:4000` → Health: `/health`
- Gateway: `http://localhost:8081` → Health: `/actuator/health`
- Services (dev): Ping 8082, Members 8083, Horses 8084, Events 8085, Masterdata 8086
- Keycloak: `http://localhost:8180`
- Consul UI: `http://localhost:8500`
- Postgres: `localhost:5432`
- Redis: `localhost:6379`
- noVNC: `http://localhost:6080`

## Auth-Flow (kurz)
1. Web ruft geschützte Seite → Redirect zu Keycloak `/authorize`
2. Login → Code → Token-Tausch (ID/Access Token)
3. Web ruft Gateway mit `Bearer <JWT>` auf → Gateway prüft Token → leitet an Service

## Produktion (Proxmox/Nginx)
- Datei: `docs/proxmox-nginx/meldestelle.conf`
- vHosts:
  - `meldestelle.yourdomain.com` → Web (`localhost:4000`)
  - `api.meldestelle.yourdomain.com` → Gateway (`localhost:8081`)
  - `vnc.meldestelle.yourdomain.com` → noVNC (`localhost:6080`)
- Health-Checks:
  - `curl -i http://api.meldestelle.yourdomain.com/actuator/health`
  - `curl -i http://meldestelle.yourdomain.com/health`

## Konfiguration auf einen Blick (Defaults)
- Postgres: `POSTGRES_USER=meldestelle`, `POSTGRES_PASSWORD=meldestelle`, `POSTGRES_DB=meldestelle`
- Keycloak Admin: `KC_BOOTSTRAP_ADMIN_USERNAME=admin`, `KC_BOOTSTRAP_ADMIN_PASSWORD=admin`
- Gateway: Port 8081, Profil `dev` (per `SPRING_PROFILES_ACTIVE`)

## Troubleshooting (Top 5)
- 401/403 am Gateway: Token fehlt/abgelaufen? Keycloak auf `http://localhost:8180` erreichbar?
- 502/Bad Gateway: Zielservice down? Logs prüfen (`make services-logs`).
- CORS im Browser: API über `api.meldestelle.*` bzw. `localhost:8081` aufrufen.
- Consul leer: Services nicht registriert → Services neu starten.
- Port-Konflikt: Belegte Ports mit `lsof -i :<port>` prüfen, Prozesse beenden.

## Diagramme (PlantUML)
Siehe `docs/architecture/c4/` – Context & Container sowie Login‑Sequenz. In CI zu SVG rendern.