IBKRTrader/docs/ARCHITECTURE.md

IBKRTrader – Architektur & Implementierungsplan

Umbau von IBKRTrader auf das Polytrader-Grundprinzip: harter Core + beliebig viele unabhängige Module + ein Launcher, der die Fenster der einzelnen Module öffnet. Statt Polymarket wird über Interactive Brokers gehandelt.

Polytrader dient als konzeptionelle Vorlage (Python/FastAPI + tkinter-Launcher + Web-UI), nicht als Code-Vorlage. IBKRTrader ist ein C#/.NET-10-WinForms-Framework.

---

1. Zielarchitektur

Program.cs (DI-Bootstrap)
│
├── CORE  (harter Kern – kennt KEIN Modul)
│   ├── Settings          AppSettings + settings.json
│   ├── Logging           rtb + Logs/[Modul]/[Level]
│   ├── Database          MySQL/Dapper + Migrationen (core_)
│   ├── IBKR              Marktdaten [vorhanden] + Orders [neu]
│   ├── Portfolio         Positionen/Balance/P&L (core_)          [neu]
│   ├── Execution + Risk  Signal → Prüfung → Order → Buchung      [neu]
│   ├── Workers           WorkerEngine + Core-Worker
│   └── Modules           IModule-Vertrag + ModuleRegistry        [neu]
│
├── MODULES  (unabhängige Strategien – Abhängigkeit nur Modul → Core)
│   └── CongressTrading   Scraper + Repo + Worker [vorhanden]
│                         + Strategie + Fenster [neu]
│
└── UI
    ├── LauncherForm      Basis: Core-Status, Worker-Grid, Logs, Settings,
    │                     Modul-Liste mit „Fenster öffnen"-Buttons
    └── ModuleFormBase    Basisklasse für eigenständige Modul-Fenster

Kernregeln (siehe auch .agents/rules/grundregeln.md)

• Core kennt kein Modul. Module hängen sich über DI + IModule ein. Abhängigkeit nur Modul → Core.
• DB-Tabellen: {ModulKürzel}_name (Core = core_, CongressTrading = ct_).
• Jeder Worker ist unabhängig ein-/ausschaltbar, hat eigenen Zeitplan, ist manuell triggerbar.
• Strategie lebt im Modul, nicht im Core. Der Core stellt nur Primitive bereit (Orders, Portfolio, Risiko); das Modul liefert nur ein TradeSignal an den ExecutionService.

Festgelegte Entscheidungen

Thema	Festlegung
Modul-Fenster	Eigenständige Top-Level-Fenster; Launcher trackt Key → Form, fokussiert bei Re-Open
Demo-Betrieb	IBKR Paper-Account (Port 4002); Umschaltung Paper/Live via TradingSettings.Mode
Tests	IBKRTrader.Tests (xUnit + NSubstitute + FluentAssertions), nur Unit, alles Externe gemockt
DoD je Phase	dotnet test (Unit) grün und Build sauber

---

2. Abbildung Polytrader → IBKRTrader

Polytrader	Rolle	IBKRTrader
main.py + api/server.py lifespan	Entry-Point, Orchestrierung, Background-Loops	Program.cs (DI) + WorkerEngine
config.py	zentrale Config	SettingsService / AppSettings
database/	Buchführung	DatabaseService + Migrationen + Repos
polymarket_client.py	Plattform-Anbindung	IIbkrClient (Marktdaten + Orders)
trade_manager.py	Positionen/Balance/P&L	PortfolioService
trade_engine.py	Signal → Risiko → Order	ExecutionService + RiskService
trader_monitor.py	Datenquelle pollen → Signal	Modul-Worker (z. B. CT-ScrapeWorker)
demo_wallet.py	Handel ohne echtes Geld	IBKR Paper-Account
desktop_gui.py	Launcher-Fenster	LauncherForm
frontend/ (Sidebar → Pages)	Ansichten	Launcher-Panels + je Modul ein Fenster
telegram_notifier.py	Benachrichtigungen	NotificationService (später)
module_checker.py	Integritätscheck	Startup-Self-Check (später)

---

3. Teststrategie

• Eigenes Projekt IBKRTrader.Tests (net10.0-windows), im .slnx.
• Nur Unit-Tests, deterministisch, schnell, laufen bei jedem Build/Commit.
• Externe Abhängigkeiten hinter Interfaces (IIbkrClient, IOrderService, IPortfolioService, IRiskService, ICongressRepository …) → in Tests via NSubstitute gemockt.
• Echtes MySQL/IBKR-Paper/Scraping wird manuell je Meilenstein geprüft (nicht automatisiert).

Komponente	Beispiel-Testfall
RiskService	Sizing bei 5 % Budget; Ablehnung bei Slippage; globaler Pause-Schalter blockt
ExecutionService	Signal → gemockte Risk/Order/Portfolio; Buchung & Ablehnungsgründe
CapitolTradesScraper	Parser gegen Fixture ct_raw.html (deterministisch, kein Netz)
ModuleRegistry / IModule	Registrierung, Worker-Sammlung, CreateWindow liefert Fenster
WorkerBase	Interval-Loop, Trigger, Fehler → Status=Error, Cancellation
AppSettings / SettingsService	Laden/Serialisieren, Paper/Live-Port-Auswahl (4002/4001)
WindowManager	Fenster-Tracking, Re-Open fokussiert bestehendes Fenster

WinForms selbst wird nicht unit-getestet – Logik in Services/Manager halten, Forms dünn.

---

4. Phasenplan (Checkliste)

Phase 0 – Fundament & Doku ✅

• grundregeln.md auf .NET 10 + Launcher-Modell aktualisiert (+ DB-Passwort entfernt)
• docs/ARCHITECTURE.md angelegt
• IBKRTrader.Tests (xUnit + NSubstitute + FluentAssertions) angelegt, im .slnx
• Repo-lokale NuGet.config (Test-Pakete in Allowlist ergänzt)
• Erster Smoke-Test grün (dotnet test → 2/2 bestanden)

Phase 1 – Modul-System formalisieren (Refactoring, kein Verhaltensänderung) ✅

• Core/Modules/IModule.cs (Key, DisplayName, Description, Version, RegisterServices, InitializeAsync, GetWorkers, CreateWindow)
• Core/Modules/ModuleRegistry.cs
• CongressTradingModule → IModule (instanzbasiert, + Platzhalter-CreateWindow)
• Program.cs iteriert über IModule[] + ModuleRegistry; Form1 initialisiert Module über die Registry
• Testbarkeits-Seams: WorkerBase.BeginRunLogAsync/EndRunLogAsync, CapitolTradesScraper.ParseTradesFromHtml
• Tests: ModuleRegistry, CongressTradingModule, WorkerBase, CapitolTradesScraper (gegen ct_raw.html) → 15/15 grün

Phase 2 – Launcher-UI + Modul-Fenster

• Form1 → LauncherForm; Kern-Panels behalten (Workers, Logs, Settings, Core-Status)
• Modul-Panel: Liste aus ModuleRegistry, je Modul „Fenster öffnen"
• UI/ModuleFormBase.cs + UI/WindowManager.cs (Fenster-Tracking)
• Modules/CongressTrading/UI/CongressTradingForm.cs (erstes Modul-Fenster)
• Tests: WindowManager

Phase 3 – Trading-Kern (Core)

• Core/Trading/IIbkrClient.cs (+ Adapter auf IBKRGatewayService)
• Core/Trading/IOrderService.cs + Implementierung (Market/Limit, Paper+Live)
• Core/Trading/PortfolioService.cs + Migrationen core_position, core_trade, core_account_snapshot
• Core/Trading/RiskService.cs (Sizing, Limits, Slippage, Profit-Target, globaler Pause-Schalter)
• Core/Trading/ExecutionService.cs (TradeSignal → Risiko → Order → Buchung)
• TradingSettings in AppSettings (Mode Paper/Live, Risikoparameter)
• Tests: RiskService, ExecutionService (voll gemockt)

Phase 4 – CongressTrading als vollständige Strategie

• CongressTradingStrategy: neue Scrape-Trades → TradeSignal an ExecutionService
• Modul-Fenster: offene/geschlossene Positionen, P&L, Strategie-Ein/Aus, Parameter
• Tests: Signal-Erzeugung

Phase 5 – Feinschliff (optional)

• NotificationService (Telegram o. Ä.) + periodische Reports
• Startup-Self-Check (analog module_checker)
• Dashboard-Panel im Launcher (Gesamt-Balance/P&L über alle Module)