From a7820e30cfb08b573c6c76d88000955dd28e75ca Mon Sep 17 00:00:00 2001 From: Rain Ocampo Date: Thu, 20 Aug 2026 02:59:17 +0000 Subject: [PATCH] Dokumentation Trading-System: README, Modul-03, Ports, Infrastruktur (Rain Ocampo, 20.08.2026) --- README.md | 62 +++++++++++++++++++- infrastructure-handbook.md | 51 ++++++++++++++++ modul-03-market-data.md | 116 +++++++++++++++++++++++++++++++++++++ ports-reference.md | 47 +++++++++++++++ 4 files changed, 274 insertions(+), 2 deletions(-) create mode 100644 infrastructure-handbook.md create mode 100644 modul-03-market-data.md create mode 100644 ports-reference.md diff --git a/README.md b/README.md index bb05469..a0b96b8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,61 @@ -# trading-system-docs +# Trading-System — Modulare Architektur -Dokumentation des modularen Trading-Systems (17 Module, Modul-01..17) \ No newline at end of file +Zentrales, modulares automatisiertes Trading-System, betrieben auf einem Hostinger-VPS (`187.124.31.123`). + +**Repository-Inhalt:** Live-Dokumentation der Infrastruktur, der Module und des aktuellen Betriebszustands. +Jede Änderung folgt dem **Notation-Format**: Autor (`Alice` / `Rain Ocampo`) + Zeitstempel (`DD.MM.YYYY HH:MM`) + Grund. + +--- + +## Architektur-Überblick + +- **17 Module** (`Modul-01-PostgreSQL` … `Modul-17-Hermes-Agent`), orchestriert über `docker-compose.yml` unter `/opt/trading-modules/`. +- **Netzwerk:** `trading-modules` (bridge). Kommunikation ausschließlich über **Docker-interne Service-Hostnamen** (keine festen IPs). +- **Feste Host-Ports:** Modul-01=`55432`, Modul-02=`55672`+`15672`, Modul-03–17=`55003`–`55017`. +- **Zugangsdaten:** nur über Environment Variables / Docker-Secrets (Defaults in Compose mit `${VAR:-default}`). +- **Kernprinzip:** bestehende Container/Volumes/Daten nie löschen, keine unnötigen öffentlichen Ports öffnen, Ist-Zustand vor Änderung prüfen. + +### Multi-Agent-Setup (Resident-Evil-Theme) +| Agent | Rolle | Port | +|-------|-------|------| +| **Alice** (OpenClaw) | Primary | 55163 | +| **Matt Addison** (OpenClaw) | Backup | 54524 | +| **Rain Ocampo** (Hermes) | Technischer Support | 32776 (UI) | + +--- + +## Module + +| Modul | Name | Status | Port | +|-------|------|--------|------| +| 01 | PostgreSQL | ✅ healthy (postgres:16-alpine) | 55432 | +| 02 | RabbitMQ | ✅ healthy (rabbitmq:3-management) | 55672 / 15672 | +| 03 | Market-Data | ✅ healthy (market-data:0.1.0) | 55003 (intern) | +| 04 | Market-Regime | ⬜ Platzhalter (alpine) | 55004 | +| 05–17 | … | ⬜ Platzhalter (alpine) | 55005–55017 | + +Details: siehe `modul-03-market-data.md` (vollständig implementiert), weitere Module folgen. + +--- + +## Notation / Audit-Trail + +Jede Änderung wird mit folgender Zeile dokumentiert: + +``` +Geändert von: [Alice | Rain Ocampo] +Datum: DD.MM.YYYY HH:MM +Grund: +``` + +- **Alice** = Änderungen durch OpenClaw +- **Rain Ocampo** = Änderungen durch Hermes + +--- + +## Geändert +``` +Geändert von: Rain Ocampo +Datum: 20.08.2026 +Grund: Initiale Repository-Struktur und Modul-03-Dokumentation angelegt. +``` diff --git a/infrastructure-handbook.md b/infrastructure-handbook.md new file mode 100644 index 0000000..1c8a6ab --- /dev/null +++ b/infrastructure-handbook.md @@ -0,0 +1,51 @@ +# Infrastruktur & Betriebs-Handbuch — Trading-System VPS + +> Stand: 20.08.2026 · VPS: `187.124.31.123` + +## Multi-Agent-Architektur (Resident-Evil-Theme) +| Agent | Plattform | Rolle | Port | +|-------|-----------|-------|------| +| **Alice** | OpenClaw (primary) | Hauptagent, Protagonistin | 55163 | +| **Matt Addison** | OpenClaw (backup) | Backup/Support | 54524 | +| **Rain Ocampo** | Hermes (support) | Technischer Support | 32776 (UI) | + +Notation in Notion/Forgejo bei JEDER Änderung: +``` +Geändert von: [Alice | Rain Ocampo] +Datum: DD.MM.YYYY HH:MM +Grund: … +``` + +## Container-Verwaltung (via SSH) +```bash +ssh root@187.124.31.123 +docker compose -f /opt/trading-modules/docker-compose.yml ps +docker compose -f /opt/trading-modules/docker-compose.yml up -d +docker compose -f /opt/trading-modules/docker-compose.yml build +docker compose -f /opt/trading-modules/docker-compose.yml down # nur bei explizitem Wunsch +``` + +## Trading-Module (17 Container) +- Compose: `/opt/trading-modules/docker-compose.yml` +- Container-Namen exakt: `Modul-01-PostgreSQL` … `Modul-17-Hermes-Agent` +- Netzwerk: `trading-modules` +- Modul-01 = PostgreSQL 16-alpine (Host 55432) +- Modul-02 = RabbitMQ 3-management (Host 55672/15672, vhost `trading`) +- Modul-03 = Market-Data (FastAPI, Port 55003 intern, **nicht öffentlich**) +- Modul-04–17 = alpine-Platzhalter (bis ausgebaut) + +## Wichtige Hinweise +- **Coolify überschreibt Container-Configs bei Neustart.** Config-Änderungen an OpenClaw ausschließlich über Config-Dateien (nicht UI). +- **Hot-Reload** OpenClaw: `kill -HUP 1` im Container. +- **Ollama** braucht `OLLAMA_API_KEY`; interner Hostname `ollama-nb6d-ollama-1:11434`. +- VPS-Authentifizierung: **nur Public-Key-Auth**. + +## Deleted Resources (VPS-Aufräumung 20.08.2026) +Folgendes wurde entfernt (~25 GB freigegeben): Chronos/Kronos (kronos-api, chronos-service, chronos-tradelog), trading-bridge, llm-trade-manager, deepseek-bot, MetaTrader-5, t212-pilot, mehrere redundante Hermes-Container/Volumes/Netzwerke. **Bleibt:** n8n, forgejo, paperclip, Tolaria, PostgreSQL, RabbitMQ, Ollama, Traefik, Coolify-Suite. + +--- +``` +Geändert von: Rain Ocampo +Datum: 20.08.2026 +Grund: Infrastruktur-Handbuch für das Trading-System dokumentiert. +``` diff --git a/modul-03-market-data.md b/modul-03-market-data.md new file mode 100644 index 0000000..0449ecb --- /dev/null +++ b/modul-03-market-data.md @@ -0,0 +1,116 @@ +# Modul-03-Market-Data — Betriebsdokumentation + +> Erstellt: 20.08.2026 (Rain Ocampo) · Status: ✅ In Betrieb (healthy) + +## Zweck +Zentrale Marktdatenquelle des Trading-Systems. Pipeline: +`Marktdaten → Validierung → Normalisierung → PostgreSQL → RabbitMQ-Event` +Keine Strategie, keine Orders, keine KI — nur zuverlässige Marktdaten. + +## Container +| Attribut | Wert | +|----------|------| +| Name | `Modul-03-Market-Data` | +| Image | `market-data:0.1.0` (lokal gebaut) | +| Port | **55003** — **NUR intern** (`expose`, nicht öffentlich) | +| Netzwerk | `trading-modules` (bridge) | +| Build-Context | `/opt/trading-modules/modul03-market-data/` | +| Restart | `unless-stopped` | +| Healthcheck | ✅ `healthy` | + +## Deployment +```bash +cd /opt/trading-modules +docker compose build modul-03-market-data +docker compose up -d modul-03-market-data +``` + +## Environment Variables (Compose) +| Variable | Wert (Default) | Zweck | +|----------|---------------|-------| +| `PG_HOST` | `Modul-01-PostgreSQL` | Docker-interner Servicename | +| `PG_PORT` | `5432` | intern (Host: 55432) | +| `PG_USER/PASSWORD/DB` | `trading` | aus `.env`-Defaults | +| `RABBITMQ_HOST` | `Modul-02-RabbitMQ` | Docker-interner Servicename | +| `RABBITMQ_PORT` | `5672` | intern (Host: 55672) | +| `RABBITMQ_USER/PASSWORD/VHOST` | `trading` | **vhost `trading`** | +| `DATA_PROVIDER` | `noop` | `noop` / `demo` / später Broker | +| `LOG_LEVEL` | `INFO` | Strukturiertes Logging | + +Keine festen IPs — nur Docker-interne Hostnamen. Creds via Compose env + `${VAR:-default}`. + +## Datenbank (Modul-01-PostgreSQL) +Tabelle `public.ohlcv`: +```sql +symbol TEXT, asset_class TEXT, provider TEXT, timeframe TEXT, +ts TIMESTAMPTZ, open/high/low/close DOUBLE PRECISION, volume DOUBLE PRECISION, +created_at TIMESTAMPTZ DEFAULT now(), id BIGSERIAL PRIMARY KEY +``` + +### Finale Constraints & Indizes (Stand 20.08.2026) +| Index | Typ | +|-------|-----| +| `uq_ohlcv_provider_symbol_tf_ts` | **UNIQUE** `(provider, symbol, timeframe, ts)` | +| `ohlcv_pkey` | UNIQUE `(id)` | +| `idx_ohlcv_symbol_tf` | `(symbol, timeframe)` | +| `idx_ohlcv_symbol_tf_ts` | `(symbol, timeframe, ts DESC)` | +| `idx_ohlcv_provider_symbol_tf_ts` | `(provider, symbol, timeframe, ts DESC)` | + +Der Unique-Index inkludiert den **Provider** — langfristig werden mehrere Provider/Broker unterstützt +(gleiche Symbol+Timeframe+Timestamp können von verschiedenen Quellen kommen). + +**Migrationen:** `/app/migrations/001_ohlcv.sql` + `002_unique_provider.sql` +(idempotent, löschen nichts; automatisch via `ensure_schema()`/glob angewendet). + +## RabbitMQ (Modul-02) +- **Exchange:** `market.data` (topic, durable) +- **vhost:** `trading` (wichtig!) +- **Routing-Keys:** + +| Routing-Key | Event-Typ | Wann | +|-------------|-----------|------| +| `market.data.ready` | `MARKET_DATA_READY` | **Batch/Import** — EIN Event pro Batch, `candle_count` + `batch:true` | +| `market.data.candle.closed` | `MARKET_CANDLE_CLOSED` | **Live** — pro abgeschlossener Kerze EIN Event, OHLCV im payload | + +- Eventschema v1.0: `event_id, event_type, event_version, timestamp, symbol, asset_class, timeframe, provider` + payload. + +## Interne API +| Endpoint | Zweck | +|----------|-------| +| `GET /health` | Liveness (200 immer) + Komponentenstatus im Body | +| `GET /health/ready` | Readiness (503 wenn PG/RabbitMQ down) | +| `POST /ingest` | Kerzen einspeisen (JSON: `{"candles":[...]}`) | +| `GET /prices/{symbol}` | Letzte Kurse | +| `GET /history/{symbol}?timeframe=` | Historische OHLCV | + +## Provider-Adapter +`app/providers/providers.py`: +- `DataProvider` (ABC) — abstrakte Schnittstelle `fetch_ohlcv()`, `health()` +- `NoopProvider` — keine Datenquelle konfiguriert (Default) +- `DemoProvider` — synthetische OHLCV-Daten für Tests +- Neue Broker = neue Klasse, umschalten via `DATA_PROVIDER` env → keine harte Anbieter-Kopplung + +## Validierung (`app/validation/validator.py`) +- Timestamp gültig (UTC, nicht Zukunft, nicht zu alt/stale) +- OHLC-Werte > 0 +- High ≥ Low, High ≥ Open/Close, Low ≤ Open/Close +- Duplikat-Erkennung (Storage + DB-Unique-Index) + +## End-to-End-Test (20.08.2026, nach Provider-Constraint-Upgrade) ✅ +- **Batch-Pfad:** 4 GOOG-Kerzen → saved:4, **GENAU EIN** `MARKET_DATA_READY` (routing `market.data.ready`, candle_count:4). 3 NVDA → saved:3, EIN Event. +- **Live-Pfad:** 1 AMZN-Candle → `MARKET_CANDLE_CLOSED` (routing `market.data.candle.closed`, OHLCV im payload). +- **Provider-Duplikat:** identische NVDA-Kerze erneut → `duplicate`, kein Insert, kein Event. +- **Port-Sicherheit:** 55003 von außen (`http://187.124.31.123:55003/health`) → **nicht erreichbar** ✅ +- Datenbestand final: AAPL 5, GOOG 4, NVDA 3, EURUSD 3, TSLA 4, MSFT 1, AMZN 1. + +## Offene Punkte +- Echter Broker-/Datenprovider-Adapter (Interface bereit, noop/demo Defaults) +- Zusätzliche Daten (Bid/Ask/Spread, Ticks, Fundamentaldaten) — vorbereitet +- Consumer für `market.data.ready` / `market.data.candle.closed` (Modul-04 ff.) + +--- +``` +Geändert von: Rain Ocampo +Datum: 20.08.2026 +Grund: Modul-03-Dokumentation angelegt (Provider-Constraint, Event-Trennung, Port-Nicht-Exposition). +``` diff --git a/ports-reference.md b/ports-reference.md new file mode 100644 index 0000000..c872787 --- /dev/null +++ b/ports-reference.md @@ -0,0 +1,47 @@ +# Ports & Service-Referenz — Trading-System VPS + +> Stand: 20.08.2026 · VPS: `187.124.31.123` · SSH: Public-Key-Auth (nur) + +## Netzwerk & Core-Infrastruktur +- **Netzwerk:** `trading-modules` (bridge) — Kommunikation über Docker-interne Service-Hostnamen, keine festen IPs. +- **Host:** Hostinger-VPS, 300 GB Disk, ~31 GiB RAM. + +## Feste Port-Zuordnung (Schema `55NNN` nach Modulnummer) +| Modul | Container | Service | Host-Port | Öffentlich? | +|-------|-----------|---------|-----------|-------------| +| 01 | Modul-01-PostgreSQL | PostgreSQL | **55432** | ja (Admin/Debug) | +| 02 | Modul-02-RabbitMQ | RabbitMQ AMQP | 55672 | ja | +| 02 | Modul-02-RabbitMQ | RabbitMQ Management | 15672 | ja | +| 03 | Modul-03-Market-Data | FastAPI | 55003 | **nein** (nur intern) | +| 04 | Modul-04-Market-Regime | — | 55004 | (Platzhalter) | +| 05 | Modul-05-Strategy-Engine | — | 55005 | (Platzhalter) | +| 06–17 | … | — | 55006–55017 | (Platzhalter) | + +## Weitere Dienste (Host) +| Dienst | Container | Port | +|--------|-----------|------| +| Forgejo | forgejo-c4u8yyi1eaz1gepn3pqmr5fb | 3000 (HTTP) / 22222 (SSH) | +| Tolaria (Second Brain) | tolaria | 5173 | +| OpenClaw Alice | openclaw-suqw-openclaw-1 | 55163 | +| OpenClaw Matt | openclaw-3sgu-openclaw-1 | 54524 | +| Hermes Rain | hermes-workspace-e6un… | 32776 (UI) | +| Ollama | ollama-nb6d-ollama-1 | 11434 (intern) | +| n8n | n8n | (Coolify-managed) | +| Traefik | traefik | 80/443 | + +## Docker-interne Hostnamen (wichtig für Container-Kommunikation) +- PostgreSQL: `Modul-01-PostgreSQL:5432` +- RabbitMQ: `Modul-02-RabbitMQ:5672` (vhost `trading`) +- Ollama: `ollama-nb6d-ollama-1:11434` + +## Sicherheits-Notizen +- **Port 55003 (Modul-03) ist NICHT öffentlich** — nur im Docker-Netzwerk erreichbar (via `expose`, nicht `ports`). Verifiziert: `curl http://187.124.31.123:55003/health` schlägt fehl. +- Zugangsdaten ausschließlich als Env-Variablen/Secrets, nie im Code. +- Öffentliche Ports nur, wo nötig (Admin/Debug/UI). + +--- +``` +Geändert von: Rain Ocampo +Datum: 20.08.2026 +Grund: Port- und Service-Referenz für das Trading-System dokumentiert. +```