IBKRTrader/docs/ARCHITECTURE.md

IBKRTrader – Architektur & Implementierungsplan

KORRIGIERT (2026-07-27): Vorbild ist PolytraderSharp (J:\Softwareprojekte\PolytraderSharp), die C#-Neuentwicklung – nicht die veraltete Python-Version. Die frühere Fassung dieses Plans basierte auf der Python-Vorlage und war konzeptionell falsch. Ziel ist eine 1:1-Neu-Fundamentierung nach PolytraderSharp, im bestehenden IBKRTrader-Repo.

Ziel: modulares C#-Trading-Framework für Interactive-Brokers-Aktien, strukturell wie PolytraderSharp, nur dass statt Polymarket über IBKR gehandelt wird.

---

1. Ziel-Architektur (nach PolytraderSharp)

IBKRTrader.App            (WinExe, Root) – Generic Host + Shell (Launcher) + Core-Views
│   Program.cs: Host.CreateDefaultBuilder, IConfiguration, Module laden, ShellUiHost, Application.Run
│   Ui/: LauncherForm, ShellUiHost, Views/ (Dashboard, Terminal, Settings, Jobs)
│
├── src/IBKRTrader.Core            (classlib, net10.0-windows, UseWindowsForms)
│   ├── Modularity/       IModule (Name, DbPrefix, RegisterServices, RegisterUi, Start/Stop, ActivationBlocker)
│   │                     ModuleView, IModuleUiHost, WindowMenu   ← UI-Contract liegt im Core
│   ├── Configuration/    DatabaseOptions, ServerVersion-Pinning
│   ├── DependencyInjection/  AddCorePersistence(...)
│   ├── Persistence/Ef/   CoreDbContext + Entities + EF-Repositories (hinter Interfaces)
│   ├── Trading/          Broker-Seam, Risk, Execution, Portfolio, Domänentypen
│   ├── Services/         TerminalLogger, JobManager, Hosted Services (Market-Sync etc.)
│   ├── Security/         SecretProtection (Master-Key, AES-256-GCM at-rest)
│   └── Hosting/          StartupHydrationService (IHostedService, hydriert State zuerst)
│
├── src/IBKRTrader.Modules.CongressTrading   (classlib, referenziert NUR Core)
│   ├── CongressTradingModule : IModule
│   ├── Persistence/Ef/   eigener DbContext (ct_) + Repos
│   ├── Services/         Scraper + Jobs (IHostedService)
│   └── Ui/               CongressTradingMainForm (Tabs) via RegisterUi
│
└── tests/IBKRTrader.Tests   (xUnit, referenziert Core + Module)

Leitprinzipien (aus PolytraderSharp übernommen)

• Multi-Projekt: Core = eigenes Assembly; jedes Modul = eigenes Projekt, referenziert nur Core. Module können einander physisch nicht referenzieren.
• Generic Host: Host.CreateDefaultBuilder, IHostedService für alle Hintergrund-Jobs, IOptions/IConfiguration.
• Config: appsettings.json + appsettings.Local.json (gitignored, hält Connection-String/Secrets).
• Modul-Vertrag IModule: Name, DbPrefix, RegisterServices(services, config), RegisterUi(host, sp), StartAsync/StopAsync, GetActivationBlocker(config).
• UI = Shell + Views: Core und Module registrieren ModuleViews beim IModuleUiHost. Der Launcher öffnet je View ein Fenster (Einzelinstanz, Re-Open fokussiert). Gemeinsames „Fenster"-Menü (WindowMenu) auf jedem Form. Views sind designbare Forms mit Initialize(sp).
• Persistenz: EF Core (Pomelo/MySQL), AddDbContextFactory, Repositories hinter Interfaces.
• Sicherheit: Master-Key + AES-256-GCM-Verschlüsselung von Credentials at-rest; TLS-Warnung.
• Headless-Test: --smoke-ui konstruiert jede View + Launcher ohne Message-Loop.
• Module an/aus über ServerSettings.DisabledModules.

---

2. Was aus dem bisherigen Stand übernommen wird

Bestand (Phase 0–3, Python-basiert)	Schicksal
Testprojekt (xUnit)	bleibt, wandert nach tests/
RiskService, ExecutionService, Domänentypen	Logik bleibt → Core/Trading (Feinschliff)
CongressTrading Scraper/Repo	Inhalt bleibt → eigenes Modul-Projekt (auf EF/IHostedService umgestellt)
IModule/ModuleRegistry/WindowManager	ersetzt durch PolytraderSharp-Contract (IModule neu, ModuleView, IModuleUiHost, WindowMenu)
Manuelles ServiceCollection in Program.cs	ersetzt durch Generic Host
settings.json/SettingsService	ersetzt durch IConfiguration + appsettings.Local.json
Dapper + manuelle Migrationen	ersetzt durch EF Core
WorkerEngine/IWorker	ersetzt durch IHostedService

---

3. Re-Fundamentierungs-Phasen (Checkliste)

R1 – Solution-Skelett (Multi-Projekt, reiner Strukturumbau, Verhalten unverändert) ✅

• src/IBKRTrader.Core (classlib, UseWindowsForms) – Core/ + UI-Contract (Ui/ModuleFormBase, Ui/WindowManager)
• src/IBKRTrader.Modules.CongressTrading (classlib, referenziert nur Core)
• Root-Projekt → IBKRTrader.App (WinExe), referenziert Core + Modul; Program/LauncherForm/UI-Shell bleiben
• tests/IBKRTrader.Tests – Referenzen auf Core + Modul; Fixture-Pfad angepasst
• Neue .slnx; ungenutztes HtmlAgilityPack entfernt; Build + 38/38 Tests grün; App startet

R2 – Core-Contracts + Generic Host + Shell-UI ✅

• IModule (PolytraderSharp-Stil) + ModuleView + IModuleUiHost + WindowMenu in Core
• Program.cs → Host.CreateDefaultBuilder; IConfiguration (appsettings.json + appsettings.Local.json, gitignored)
• ShellUiHost + LauncherForm (View-Buttons + gemeinsames Fenster-Menü); Core-Views (Workers/Logs/Settings) als eigene Fenster
• CongressTrading auf neuen IModule-Vertrag; Modul-Worker als IWorker registriert
• --smoke-ui Headless-Test (alle Views + Launcher konstruieren) → grün
• Offen (R4/R5): Worker von WorkerEngine/IWorker auf IHostedService umstellen (aktuell noch WorkerEngine)

R3 – Persistenz auf EF Core

Festgelegt: EF-Migrationen extern (wie PolytraderSharp) – Schema per dotnet ef database update, App legt keine Tabellen zur Laufzeit an. Server: MariaDB 11.8.6 (via --db-version bestätigt) → Pin new MariaDbServerVersion(new Version(11, 8, 6)). Verbindung aus appsettings.Local.json.

• --db-version-Diagnose (Serverversion für den EF-Pin)
• Configuration/DatabaseOptions (aus appsettings.Local.json) + DatabaseServerVersion-Pin
• AddCorePersistence + CoreDbContext + Entities + EF-Repos (core_position, core_trade_history, core_budget, core_worker_log, core_settings)
• Consumer umstellen: PortfolioService, BudgetService, TradeHistoryService, WorkerBase-Log, IBKR
• Modul-DbContext (ct_) im CongressTrading-Projekt + EF-Repo
• EF-Migrationen erzeugen (dotnet ef migrations add); Dapper + manuelle Migrationen entfernen
• Hinweis: nur build-verifizierbar (Unit-Tests laufen ohne DB); Schema-Anwendung erfolgt extern

R4 – Trading-Kern einфügen

• Risk/Execution/Portfolio/Broker-Seam nach Core/Trading (aus Phase 3 portiert)
• Hintergrund-Jobs als IHostedService

R5 – CongressTrading als vollständige Strategie

• Scraper/Jobs → IHostedService; Signal → ExecutionService
• Modul-View (Tabs) via RegisterUi

R6 – Sicherheit + Config-Härtung

• SecretProtection (Master-Key, AES-256-GCM at-rest), TLS-Warnung
• Connection-String nur in appsettings.Local.json (gitignored); Secrets aus Repo/Historie

R7 – Tests + Feinschliff

• Bestehende Unit-Tests portieren; --smoke-ui; EF-InMemory-Tests wo sinnvoll

---

4. Historie (bereits erledigt, teils zu ersetzen)

• Phase 0–3 (Python-basiert): Testfundament, IModule/ModuleRegistry, LauncherForm+WindowManager, Trading-Kern (Risk/Execution/Portfolio, NullBroker). Logik brauchbar, Infrastruktur wird ersetzt.
• Commits bis 2ad4b55 auf Gitea.