Add Mermaid diagrams to architecture doc (implementation status, risk quadrant, production readiness)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Christoph K.
2026-04-06 10:24:34 +02:00
parent 9775a22473
commit d1436abca8

View File

@@ -539,16 +539,94 @@ Schema wird beim API-Start automatisch initialisiert (keine separate Migration n
## 11. Risiken und offene Punkte
| Risiko | Schwere | Status |
|--------|---------|--------|
| Android Upload Auth: Session Cookie suboptimal für Mobile | Mittel | **TBD** — API-Key oder JWT (T050) |
| `timestamp`-Format: epochMillis vs RFC3339 | Niedrig | **Offen** |
| Payload: JSON vs Protobuf | Niedrig | **Offen** |
| Batch-Limits (max Items, max Bytes) | Niedrig | **Offen** |
| Kein Rate-Limiting auf Ingest-Endpoints | Mittel | Backlog (T029) |
| Stop Detection nicht implementiert | Mittel | Backlog (T061) |
| Geocoding Adapter + Cache nicht implementiert | Mittel | Backlog (T063) |
| Kein HTTPS/TLS im nginx (nur HTTP intern) | Hoch | Für Produktion: TLS-Termination via Reverse Proxy nötig |
| Retention Policy (wie lange Trackpoints gespeichert) | Niedrig | **Offen** |
| Stop Detection Parameter (Mindestdauer, Radius) | Niedrig | **Offen** |
| Geocoding Provider: Nominatim public vs self-hosted | Niedrig | **Offen** |
### Implementierungsstatus
```mermaid
flowchart TD
subgraph Impl[Implementiert]
A[REST API Ingest\nPOST /v1/trackpoints]
B[Session Auth\nArgon2id + Cookie]
C[Tagesabfragen\nGET /v1/days etc.]
D[Web UI\nGo Templates SSR]
E[SPA Webapp\nMapLibre + WebComponents]
F[Schema Init\ngo:embed + IF NOT EXISTS]
G[Device-Registrierung\nEnsureDevice]
end
subgraph Backlog[Backlog / TBD]
H[Stop Detection\nT061]
I[Geocoding Adapter\nT063]
J[Suggestions Engine\nT062]
K[Android Auth\nAPI-Key / JWT T050]
L[OpenAPI Spec\nT070]
M[Hashtag-Support\nT073-T087]
end
subgraph Risiko[Sicherheit / Production]
N[CSRF-Schutz\nkritisch]
O[TLS / HTTPS\nhoch]
P[Rate-Limiting\nmittel]
Q[Secrets via .env\nkritisch]
R[Pagination\nhoch]
S[Security-Header\nnginx mittel]
end
style Impl fill:#d4edda,stroke:#28a745
style Backlog fill:#fff3cd,stroke:#ffc107
style Risiko fill:#f8d7da,stroke:#dc3545
```
### Security-Risiken (Architekt-Review)
```mermaid
quadrantChart
title Risiken — Schwere vs. Aufwand
x-axis Geringer Aufwand --> Hoher Aufwand
y-axis Geringes Risiko --> Hohes Risiko
quadrant-1 Sofort beheben
quadrant-2 Planen
quadrant-3 Beobachten
quadrant-4 Nice to have
CSRF-Schutz: [0.2, 0.9]
Secrets via .env: [0.1, 0.85]
TLS/HTTPS: [0.5, 0.8]
Rate-Limiting Login: [0.3, 0.75]
Pagination: [0.4, 0.6]
Android Auth: [0.7, 0.65]
Security-Header nginx: [0.15, 0.5]
Error-Disclosure: [0.2, 0.5]
EnsureDevice N+1: [0.35, 0.35]
DB Pool Config: [0.2, 0.4]
Stop Detection: [0.75, 0.5]
Geocoding: [0.8, 0.4]
OpenAPI Spec: [0.5, 0.2]
Hashtags: [0.65, 0.3]
```
### Produktionsreife
```mermaid
flowchart LR
DEV[Development\n✓ Lauffähig]
MVP[MVP\nFehlend: CSRF, TLS\nSecrets, Rate-Limit]
PROD[Production Ready\n+ Stop Detection\n+ Geocoding\n+ Monitoring\n+ Backup]
DEV -->|Kritische Security-Fixes| MVP
MVP -->|Business-Logik\n+ Observability| PROD
style DEV fill:#d4edda,stroke:#28a745
style MVP fill:#fff3cd,stroke:#ffc107
style PROD fill:#cce5ff,stroke:#004085
```
### Offene Entscheidungen
| Thema | Optionen | Auswirkung |
|-------|----------|-----------|
| `timestamp`-Format | epochMillis vs RFC3339 | Android + API Kompatibilität |
| Android Upload Auth | Session Cookie / API-Key / JWT | Security-Architektur |
| Payload | JSON vs Protobuf | Bandbreite auf Mobile |
| Batch-Limits | max Items / max Bytes | Denial-of-Service Schutz |
| Retention Policy | Löschen nach X Tagen | Storage-Kosten |
| Stop-Parameter | Mindestdauer, Radius | Qualität der Vorschläge |
| Geocoding Provider | Nominatim public / self-hosted | Datenschutz, Verfügbarkeit |