Plattform-Architektur – Übersicht

Architekturprinzipien

Die Home Dev Platform folgt diesen Leitprinzipien:

Service-orientiert – jeder Service hat eine klar definierte Verantwortung und eigene API
Containerisiert – alle Komponenten laufen als Docker-Container (Docker Compose)
API-first / Headless – Backend-Services exponieren REST APIs, kein Server-Side-Rendering
Path-based Routing – ein einziger Einstiegspunkt (Traefik) routet über URL-Prefixes
Keine offenen Ports – Zugriff von außen ausschließlich über Cloudflare Tunnel
AI-assisted Development – Claude Code CLI direkt auf dem Pi als Entwicklungsumgebung

C4-Ebene 1: System Context

Diagramm: system_context.wsd

Akteur	Beschreibung
Nutzer	Greift über Browser (Desktop/Mobile) via Cloudflare auf die Plattform zu
Entwickler	Christoph – Entwicklung, Betrieb und Weiterentwicklung per SSH/Tailscale
Cloudflare	DNS + TLS-Terminierung + Tunnel (kein offener Port am Heimrouter)
GitHub	Remote Git Repository (`matu-pi/matus-toolbox`)
Tailscale	VPN für sicheren Remote-Zugriff des Entwicklers

Service-Landkarte

Die folgende Tabelle gibt einen vollständigen Überblick über alle dokumentierten Services – sowohl laufende als auch geplante.

Service	Docs	Status	Laufender Container	API-Prefix
Hello World	docs	✅ Laufend	`backend` :8000	`/api/notes`
Lunch Scraper	docs	✅ Laufend	`backend` :8000	`/api/lunch`
Push Alerts	docs	✅ Laufend	`backend` :8000	`/api/alerts`
Trading Journal	docs	✅ Laufend	`backend` :8000	`/api/trading`
Trading Data Layer	docs	✅ Laufend	`trading-data-layer` :8001	`/data-layer`
Trend Analysis	docs	✅ Laufend	`trend-analysis` :8002	`/trend-analysis/api/v1`
Trade Optimizer	docs	✅ Laufend	`trade-optimizer` :8004	`/trade-optimizer/api/v1`
Fundamental Analysis	docs	⚠️ In Trend Analysis	`trend-analysis` :8002	`/trend-analysis/api/v1/fundamental`
Market Interpretation	docs	⚠️ In Trend Analysis	`trend-analysis` :8002	`/trend-analysis/api/v1/interpretation`

Legende: - ✅ Laufend — implementiert und als Docker-Container aktiv - ⚠️ In anderem Service — implementiert, aber noch nicht als eigener Container ausgelagert

C4-Ebene 2: Container-Architektur

Diagramm: container_diagram.wsd

Laufende Container (Stand: 2026-06-26)

Container	Image / Port	Path-Prefix	Netzwerk	Beschreibung
Traefik	`traefik:v2.11` :80	—	web	Reverse Proxy, Routing-Einstiegspunkt
Frontend	React/Vite :80	`/`	web	Single Page App (PWA), alle UI-Tabs
Backend	FastAPI :8000	`/api`	web + internal	Hello World, Lunch Scraper, Push Alerts, Trading Journal, Auth, User-Mgmt, Logs
Trading Data Layer	FastAPI :8001	`/data-layer`	web + internal	Forex/Economic Datensammler (Scheduler)
Trend Analysis	FastAPI :8002	`/trend-analysis`	web + internal	Technische Indikatoren, Fundamentalanalyse, Marktinterpretation
Trade Optimizer	FastAPI :8004	`/trade-optimizer`	web + internal	Score-Aggregation, MTF, Mustererkennung
PostgreSQL	`postgres:15`	—	internal (nur)	Persistenz für alle Services

Docker-Netzwerke

Netzwerk	Teilnehmer	Zweck
`web`	Traefik + alle App-Services + Frontend	HTTP-Kommunikation über Traefik
`internal`	Alle App-Services + PostgreSQL	DB-Zugriff (PostgreSQL nicht von außen erreichbar)

Routing

Diagramm: routing.wsd

Traefik routet ausschließlich über PathPrefix-Regeln. Services mit priority=100 werden vor dem catch-all Prefix / (Frontend) bevorzugt.

Eingehender Pfad	Ziel-Service	Strip-Prefix	Effektiver Pfad im Service
`/`	Frontend :80	—	`/`
`/api/...`	Backend :8000	`/api`	`/...`
`/data-layer/...`	Trading Data Layer :8001	`/data-layer`	`/...`
`/trend-analysis/...`	Trend Analysis :8002	`/trend-analysis`	`/...`
`/trade-optimizer/...`	Trade Optimizer :8004	`/trade-optimizer`	`/...`

Service-Kommunikation

Diagramm: api.wsd

Frontend → Services (via Traefik)

Das Frontend kommuniziert direkt mit den Services über die öffentlichen Pfade:

Frontend → /trend-analysis/api/v1/interpretation?pair=EUR/USD&timeframe=1h
Frontend → /trend-analysis/api/v1/fundamental/score?pair=EUR/USD
Frontend → /trade-optimizer/api/v1/trade-optimizer/analyze?pair=EUR/USD
Frontend → /trade-optimizer/api/v1/trade-optimizer/library

Trade Optimizer → Trend Analysis (intern, parallel)

Der Trade Optimizer ruft beim /analyze-Request fünf Trend-Analysis-Endpoints parallel auf (asyncio.gather + httpx):

to → http://trend-analysis:8002/api/v1/interpretation?pair=...&timeframe=1h   (Trend Score)
to → http://trend-analysis:8002/api/v1/fundamental/score?pair=...              (Fundamental Score)
to → http://trend-analysis:8002/api/v1/interpretation?pair=...&timeframe=15min (MTF)
to → http://trend-analysis:8002/api/v1/interpretation?pair=...&timeframe=4h   (MTF)
to → http://trend-analysis:8002/api/v1/interpretation?pair=...&timeframe=daily (MTF)

Trading Data Layer (Hintergrund-Scheduler)

Der Trading Data Layer sammelt Daten ohne User-Trigger: - Forex OHLCV (5min-Kerzen, 4 Währungspaare) → market_data.forex_ohlcv - Economic Events (Wirtschaftskalender) → market_data.economic_events - Economic Indicators (Makrodaten) → market_data.economic_indicators

Datenarchitektur

Schema `public` (Hello World Backend)

Tabelle	Beschreibung
`notes`	Einfache Notizen (id, title, content, created_at)

Schema `market_data` (Trading Services)

Tabelle	Beschreibung	Schreiber	Leser
`forex_ohlcv`	OHLCV-Kerzen je Währungspaar und Timestamp	Trading Data Layer	Trend Analysis, Trade Optimizer
`economic_events`	Wirtschaftskalender-Ereignisse	Trading Data Layer	Trend Analysis
`economic_indicators`	Makroökonomische Indikatoren (CPI, Zinsen etc.)	Trading Data Layer	Trend Analysis
`correlation_data`	Rohstoff-/Korrelationsdaten	Trading Data Layer	Trend Analysis

C4-Ebene 3: Komponentenbeschreibung

Diagramm: architecture.wsd

Traefik

Verantwortung: Einziger nach außen exponierter Einstiegspunkt (Port 80).
Routing per PathPrefix, Strip-Prefix-Middleware, Docker-Label-Discovery.
Konfiguration: traefik/traefik.yml (kein Dashboard, kein HTTPS intern – TLS liegt bei Cloudflare).

Frontend (React/Vite PWA)

Verantwortung: Single Page Application mit allen UI-Tabs.
Tabs: Trendanalyse · Fundamentalanalyse · Trade Optimizer · Dokumentation
Routing: clientseitig (React). API-Calls direkt gegen Traefik-Pfade.

Backend

Verantwortung: Zentraler App-Service, der mehrere fachliche Domänen als Router-Module bündelt.

Router	Prefix	Beschreibung
`auth`	`/auth`	Login, JWT-Token, `/me`
`users`	`/users`	User-CRUD, Rollenverwaltung
`notes`	`/notes`	Hello-World CRUD (Referenzimplementierung)
`lunch`	`/lunch`	Lunch-Scraper: Accounts, Scrape-Trigger, Bestellübersicht
`trading`	`/trading`	Trading Journal: Trade-CRUD, Statistiken
`alerts`	`/alerts`	Push Alerts: VAPID, Subscriptions, Trigger-Regeln, Reminder
`logs`	`/logs`	Log-Viewer
`system`	`/system`	System-Übersicht

Trend Analysis (inkl. Fundamentalanalyse und Marktinterpretation)

Verantwortung: Alle marktanalytischen Berechnungen – technisch, fundamental und interpretativ.
Enthält aktuell die Funktionalität dreier dokumentierter Services: Trend Analysis, Fundamental Analysis und Market Interpretation.

Endpoint-Gruppe	Logischer Service	Beschreibung
`/api/v1/ohlcv`, `/heikin-ashi`	Trend Analysis	Rohdaten aus DB
`/api/v1/indicators/*`	Trend Analysis	EMA, RSI, MACD, Bollinger Bands, SuperTrend, Squeeze, Force Index
`/api/v1/interpretation`	Market Interpretation	Gesamtinterpretation (Score, Kategorie, Indikatoren) je Zeitrahmen
`/api/v1/trade-setup`	Trend Analysis	Entry/SL/TP-Level basierend auf Indikatoren
`/api/v1/fundamental/*`	Fundamental Analysis	Makro-Score, Sentiment, Treiber
`/api/v1/calendar/today`	Fundamental Analysis	Wirtschaftskalender für heute

Trading Data Layer

Verantwortung: Datenbeschaffung und -persistierung (Hintergrundprozess).
Sammelt Forex OHLCV (5min), Economic Events und Indikatoren via externen APIs.
Betrieben mit internem Scheduler (kein Cron auf Host-Ebene nötig).

Trade Optimizer

Verantwortung: Ableitung von Trade-Setups und Mustererkennung.

Endpoint	Beschreibung
`/api/v1/trade-optimizer/analyze`	Kombinierter Haupt-Endpoint (trend + fundamental + MTF + setup + patterns)
`/api/v1/trade-optimizer/library`	Statische Musterbibliothek (14 Muster mit SVG + Erklärungen)
`/api/v1/trade-optimizer/setup`	Nur Setup-Ableitung
`/api/v1/trade-optimizer/patterns`	Nur Mustererkennung
`/health`	Datenbankstatus

PostgreSQL

Verantwortung: Einzige persistente Datenhaltung.
Nur im internal-Netzwerk erreichbar. Healthcheck via pg_isready vor Service-Start.

Sicherheitsarchitektur

Mechanismus	Beschreibung
Cloudflare Tunnel	Kein offener Port am Heimrouter; TLS-Terminierung bei Cloudflare
Netzwerk-Isolation	PostgreSQL nur im `internal`-Netzwerk, nicht von außen erreichbar
Kein direkter Zugriff	Alle externen Requests gehen über Traefik
Secret Management	Credentials als Umgebungsvariablen (`.env`), nicht im Code
HTTPS	TLS vollständig bei Cloudflare, intern HTTP

Remote Development Setup

Diagramm: remote_dev_arch.wsd

Komponente	Details
Laptop → Pi	VS Code Remote SSH via Tailscale
Versionierung	Git auf dem Pi, Remote: GitHub (`git pull` manuell nach Push)
KI-Unterstützung	Claude Code CLI (`claude-sonnet-4-6`) direkt auf dem Pi
Container-Entwicklung	`docker compose up --build -d <service>` nach Code-Änderung

Wichtig: docker compose restart übernimmt keine Code-Änderungen (reused Image).
Immer docker compose up --build -d <service> verwenden.

Deployment-Workflow

Diagramm: deployment_flow.wsd

# 1. Änderungen pushen
git push origin master

# 2. Auf Pi: aktuellen Stand holen
git stash && git pull --rebase && git stash pop && git push

# 3. Service neu bauen und starten
docker compose up --build -d <service>

# 4. Logs prüfen
docker compose logs -f <service>

Technologiestack

Schicht	Technologie
Host	Raspberry Pi (ARM64)
Runtime	Docker + Docker Compose
Reverse Proxy	Traefik v2.11
Backend-Services	Python 3.11 + FastAPI + SQLAlchemy (async)
Frontend	React 18 + Vite + Custom CSS
Datenbank	PostgreSQL 15 (Alpine)
Externer Zugriff	Cloudflare Tunnel
Remote Development	Tailscale VPN + VS Code Remote SSH + Claude Code CLI
Versionierung	Git → GitHub

Changelog

Version	Datum	Änderungen
1.0	2026-06-26	Initiale Version – konsolidiert und ersetzt phase2.md; beschreibt implementierten Ist-Stand mit allen laufenden Services; vollständige Service-Landkarte inkl. geplanter und zusammengelegter Services