Finlytic/FinlyticApp/Architecture.MD

FinlyticApp — Architecture Guidelines & Engineering Standards

Dieses Dokument definiert die verbindlichen Architektur- und Entwicklungsstandards für die FinlyticApp (Dart / Flutter Cross-Platform Client für Android, iOS und Web).

---

1. Grundprinzipien & Dateistruktur

Das Projekt folgt einer strengen Feature-Driven Clean Architecture. Dadurch wird eine vollständige Entkopplung von Benutzeroberfläche, Geschäftslogik und Datenquellen gewährleistet.

📏 Dateigröße & Struktur-Limits

• Maximal 150 bis 200 Zeilen pro Datei: Wenn eine Datei diese Grenze überschreitet, muss sie in kleinere, fokussierte Einheiten refactored werden (Single Responsibility Principle).
• Eine Hauptklasse pro Datei: Helper-Klassen gehören in eigene Dateien, es sei denn, sie sind private und ausschließlich lokal relevant.
• Kompakte build()-Methoden: Die build()-Methode dient nur der Anordnung von Sub-Widgets und darf selten länger als 30–40 Zeilen sein.

📁 Verzeichnisstruktur (lib/)

lib/
├── core/
│   ├── network/          # ApiClient, MQTT-Service, WebSockets
│   ├── theme/            # Finlytic Dark Glassmorphism, Typography, Colors
│   ├── utils/            # Formatierer (Währungen, Prozentangaben, Datum)
│   └── widgets/          # App-weit genutzte UI-Komponenten (Buttons, Modals)
├── features/
│   ├── dashboard/        # Dashboard-Overview, Analytics-Cards
│   ├── news/             # Feed, Pagination, Sentiment-Analysen
│   ├── favorites/        # Favoriten-Grid, Watchlist
│   ├── calendar/         # Corporate Calendar, Earnings, Dividenden
│   ├── trades/           # Trade-Signale, Automatische Trades
│   ├── admin/            # User-Verwaltung, System-Settings (Admin-Only)
│   └── asset_detail/     # Fundamentaldaten, TA-Chart, Finance-Metrics
└── main.dart             # Entry Point & Service Locator Initialization

2. Clean Architecture Layering
Jedes Feature im features/-Ordner wird intern strikt in drei Layer unterteilt:LayerVerantwortlichkeitErlaubte Abhängigkeiten1. PresentationUI-Komponenten, Screen-Layouts, Consumer von States.Greift nur auf Logic (BLoC/Notifier) zu. Keine direkten API/DB-Calls!2. Domain / LogicBusiness-Logik, State Management, UseCases, Entities.Absolut frei von flutter/material.dart! Nutzt Repositories als Abstraktion.3. DataAPI-Clients, DTOs, Local Caching, MQTT-Stream Handlers.Implementiert Repository-Interfaces aus dem Domain Layer.

3. Widget-Architektur & Sub-Widget Auslagerung
❌ VERBOTEN: Helper-Methoden für Widgets (_buildX())Unter keinen Umständen dürfen Methoden innerhalb von Widget-Klassen definiert werden, die ein Widget zurückgeben:Dart// ❌ FALSCH: Baut keinen eigenen BuildContext/Lifecycle auf und erfordert Rebuilding des gesamten Mutter-Widgets!
Widget _buildHeader() {
  return Container(
    padding: const EdgeInsets.all(16),
    child: const Text('Dashboard'),
  );
}
✅ PFLICHT: Auslagerung in eigene StatelessWidget KlassenJedes logische Teilsegment der Benutzeroberfläche muss als eigene Klasse ausgegliedert werden:Dart// ✅ KORREKT: Saubere Performance, eigener BuildContext, optimierter Element-Tree
class DashboardHeader extends StatelessWidget {
  const DashboardHeader({super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(16),
      child: const Text('Dashboard'),
    );
  }
}
⚡ Performance-Regeln für Widgets:const Konstruktoren: Jedes Sub-Widget muss wenn möglich einen const Konstruktor haben, um unnötige Re-Renders im Widget-Tree zu verhindern.Keine Business-Logik im UI-Widget: Widgets reagieren ausschließlich auf übergebene Daten oder States und leiten Nutzerinteraktionen über Callbacks / BLoC-Events weiter.

4. Data Classes & Code-Generierung
Immutability: Alle Models, DTOs und States müssen unbeeinflussbar (immutable) sein.Freezed & JSON Serializable: Das manuelle Schreiben von fromJson, toJson oder copyWith ist untersagt. Es wird freezed zusammen mit build_runner eingesetzt.Dartimport 'package:freezed_annotation/freezed_annotation.dart';

part 'asset_model.freezed.dart';
part 'asset_model.g.dart';

@freezed
class Asset with _$Asset {
  const factory Asset({
    required String isin,
    required String name,
    required double currentPrice,
    required String currency,
  }) = _Asset;

  factory Asset.fromJson(Map<String, dynamic> json) => _$AssetFromJson(json);
}
5. Responsive & Adaptive Navigation LayoutFinlyticApp wird plattformübergreifend betrieben und muss sich dem Screen-Format anpassen:Mobile Breakpoint (< 800px): Anforderung von Material NavigationBar (Android) / Cupertino Tab Bar (iOS) am unteren Bildschirmrand.Web / Desktop Breakpoint (>= 800px): Automatische Skalierung auf ein linkes Tab-Menü (NavigationRail / Sidebar).Keine starren Dimensionen: Nutzung von LayoutBuilder, Flexible und Expanded, um Überläufe (Pixel Overflow) auf schmalen Displays zu verhindern.6. Linter Standard (analysis_options.yaml)Alle Entwickler müssen die folgenden Linter-Regeln in der analysis_options.yaml einhalten:YAMLlinter:
  rules:
    - prefer_const_constructors
    - prefer_const_declarations
    - prefer_final_fields
    - prefer_final_locals
    - avoid_unnecessary_containers
    - sizedbox_for_whitespace
    - use_build_context_synchronously
    - always_declare_return_types