Heute habe ich BudgetBuddys gesamtes CSS-Framework ausgetauscht. DaisyUI 5.5.5 raus, reines Custom CSS mit CSS-Variablen rein. 42 Dateien, ~1750 Zeilen geaendert, ~1550 geloescht. Und am Ende ein automatisierter Code-Review, der drei kritische Bugs gefunden hat, die ich uebersehen hatte.

Ausgangslage: Warum DaisyUI weg musste

BudgetBuddy hatte ein interessantes Schichtenproblem. Es gab:

1. DaisyUI als Tailwind-Plugin (liefert .btn, .card, .modal-box, .toggle etc.)
2. Ein F# DesignSystem (src/Client/DesignSystem/) mit 18 Modulen, die DaisyUI-Klassen in F#-Funktionen wrappen
3. Einen HTML-Prototypen (prototypes/unified-responsive-v1.html) der das Ziel-Design definiert — komplett ohne DaisyUI

Der Prototyp war Mobile-First designt mit eigenem Token-System: CSS-Variablen fuer Farben (--bg-card: #111128), Radien (--radius-sm: 8px), Easing-Kurven (--ease-out-quint) und Animationen. DaisyUI hatte eigene HSL-Variablen (--b1, --p, --su), ein Theme-System ([data-theme="dark"]), und eigene Komponenten-Klassen. Die zwei Welten existierten parallel und kollidierten an mehreren Stellen.

Das Ergebnis: Settings-Formulare sahen anders aus als der SyncFlow (der bereits ans Prototyp-Design angepasst war). Die Rules-Seite verwendete DaisyUI-Dropdowns, waehrend der Rest Custom-CSS nutzte. Toggles waren mal DaisyUI-Slider, mal Prototype-Checkboxen.

Herausforderung 1: Die Migrationsstrategie — Alles auf einmal oder inkrementell?

Das Problem

DaisyUI ist kein einfaches Stylesheet das man loescht. Es liefert Basis-Styles fuer .btn, .card, .badge, .input, .select etc. Entfernt man das Plugin, haben alle diese Klassen ploetzlich null Styling. Die App waere sofort kaputt.

Gleichzeitig verwendet der F#-Code diese Klassen hundertfach — nicht direkt, sondern durch die DesignSystem-Abstraktionsschicht. Button.primary generiert intern "btn btn-primary bg-gradient-to-br from-neon-orange...". Die DaisyUI-Klassen sind also eingekapselt, aber trotzdem ueberall.

Die Loesung: 5-Phasen-Migration mit Parallelitaet

Ich habe mich fuer eine additive Migration entschieden:

Phase 0: CSS-Variablen und neue Komponenten-Klassen zum bestehenden Stylesheet hinzufuegen — DaisyUI bleibt drin. Die neuen Klassen (.input-field, .select-field, .proto-toggle) existieren parallel.

Phase 1-2: Die 15+ DesignSystem-F#-Dateien migrieren — jetzt referenzieren sie die neuen Klassen statt DaisyUI. Da die DesignSystem-Module eine Abstraktionsschicht sind, aendert sich fuer die Component-Views nichts.

Phase 3: Die Component-Views (Settings, Rules, Dashboard, SyncFlow) aktualisieren — hier waren DaisyUI-Klassen “durchgesickert”, also direkt verwendet statt ueber das DesignSystem.

Phase 4: DaisyUI entfernen — jetzt sicher, weil nichts mehr darauf referenziert.

Phase 5: Verifikation.

Der entscheidende Trick: In Phase 0 koexistieren beide Systeme. Die neuen CSS-Klassen stehen am Ende des Stylesheets und gewinnen durch die CSS-Kaskade bei Namenskollisionen (.btn, .card, .badge). Aber da der F#-Code noch die alten Klassen referenziert, bleibt alles funktional.

/* Phase 0: Neue Klassen hinzufuegen, DaisyUI bleibt */
.input-field {
  width: 100%;
  padding: 10px 14px;
  background: var(--bg-input);
  border: 1px solid var(--border);
  border-radius: var(--radius-sm);
  color: var(--text-primary);
  font-size: 14px;
  transition: border-color var(--duration-fast) ease,
              box-shadow var(--duration-fast) ease;
}
.input-field:focus {
  border-color: var(--color-neon-teal);
  box-shadow: 0 0 0 2px var(--neon-teal-glow);
}

Herausforderung 2: Das Token-Mapping — Zwei Farbsysteme vereinen

Das Problem

DaisyUI nutzt HSL-Variablen: hsl(var(--b1)) fuer den Hintergrund, hsl(var(--bc)) fuer Text. Der Prototyp nutzt direkte Hex/RGBA-Werte: --bg-card: #111128, --text-primary: #e8e8f0.

Tailwind CSS 4 hat ein @theme-System, das CSS-Variablen zu Utility-Klassen mapped. Also --color-surface-card: var(--bg-card) erzeugt automatisch die Klasse bg-surface-card. Das war die Bruecke.

Die Loesung: Dreischichtige Token-Architektur

:root CSS-Variablen  →  @theme Tailwind-Mapping  →  F# Token-Strings
--bg-card: #111128   →  --color-surface-card     →  "bg-surface-card"
--text-primary       →  --color-text-primary      →  "text-text-primary"
--border             →  --color-border-default    →  "border-border-default"

Das Mapping in styles.css:

@theme {
  --color-surface-app: var(--bg-app);
  --color-surface-card: var(--bg-card);
  --color-surface-elevated: var(--bg-elevated);
  --color-surface-input: var(--bg-input);
  --color-surface-hover: var(--bg-hover);
  --color-border-default: var(--border);
  --color-border-subtle: var(--border-subtle);
  --color-text-primary: var(--text-primary);
  --color-text-secondary: var(--text-secondary);
  --color-text-muted: var(--text-muted);
}

Und in Tokens.fs:

module Colors =
    let textPrimary = "text-text-primary"    // war: "text-base-content"
    let textSecondary = "text-text-secondary" // war: "text-base-content/70"
    let textMuted = "text-text-muted"         // war: "text-base-content/60"

module Backgrounds =
    let dark = "bg-surface-card"      // war: "bg-base-100"
    let surface = "bg-surface-elevated" // war: "bg-base-200"
    let elevated = "bg-surface-input"   // war: "bg-base-300"

Warum diese Indirektion? Weil der F#-Code Token-Namen wie Backgrounds.dark verwendet, nicht CSS-Klassen direkt. Aendert sich das Farbschema, aendere ich eine Zeile in Tokens.fs — nicht 150 Stellen im Code.

Ein schoener Nebeneffekt: Der SyncFlow hatte bereits --sf-*-Variablen die identisch zu den Prototyp-Tokens waren (gleicher Designer, gleicher Prototyp). Diese konnte ich einfach als Aliase auf die neuen Root-Tokens umbiegen:

:root {
  --sf-bg-card: var(--bg-card);    /* war: #111128 (hardcoded) */
  --sf-border: var(--border);       /* war: #2a2a4a (hardcoded) */
  /* ... */
}

Herausforderung 3: Der Toggle-Rewrite — Von Slider zu Checkbox

Das Problem

DaisyUI hat ein Slider-Toggle (wie iOS-Switch): eine Kapsel mit Kreis der hin- und herschiebt. Der Prototyp zeigt ein quadratisches 20x20px Kaestchen mit SVG-Checkmark. Zwei komplett verschiedene HTML-Strukturen:

DaisyUI (vorher):

<input type="checkbox" class="toggle toggle-sm [--tglbg:...]" />

Prototyp (nachher):

<label class="proto-toggle">
  <input type="checkbox" />
  <span class="toggle-track">
    <svg class="toggle-check" viewBox="0 0 10 10">
      <path d="M2 5l2.5 2.5L8 3" />
    </svg>
  </span>
</label>

Warum ein neues CSS-Pattern statt DaisyUI-Override?

Ich haette DaisyUI’s .toggle per CSS umstylen koennen. Aber das waere fragil — DaisyUI erwartet eine bestimmte HTML-Struktur fuer den Slider, und ein visueller Override zu einem Checkbox-Look wuerde die interne Logik unterwandern.

Stattdessen: Eigene CSS-Klasse .proto-toggle mit eigener HTML-Struktur. In F# wird das zu einer Feliz-Komposition:

let toggle (isChecked: bool) (onChange: bool -> unit) (label: string option) =
    Html.label [
        prop.className "flex items-center gap-3 cursor-pointer"
        prop.children [
            Html.label [
                prop.className "proto-toggle"
                prop.onClick (fun e -> e.stopPropagation())
                prop.children [
                    Html.input [
                        prop.type' "checkbox"
                        prop.isChecked isChecked
                        prop.onChange (fun (e: Browser.Types.Event) ->
                            let target = e.target :?> Browser.Types.HTMLInputElement
                            onChange target.``checked``)
                    ]
                    Html.span [
                        prop.className "toggle-track"
                        prop.children [
                            Svg.svg [
                                svg.className "toggle-check"
                                svg.viewBox(0, 0, 10, 10)
                                svg.children [
                                    Svg.path [
                                        svg.d "M2 5l2.5 2.5L8 3"
                                        svg.fill "none"
                                        svg.stroke "currentColor"
                                        svg.strokeWidth 2
                                    ]
                                ]
                            ]
                        ]
                    ]
                ]
            ]
            // Optional label text
            match label with
            | Some l -> Html.span [ prop.className "text-text-primary"; prop.text l ]
            | None -> ()
        ]
    ]

Das CSS dazu nutzt die Prototyp-Animationstokens:

.proto-toggle input:checked + .toggle-track {
  background: var(--color-neon-teal);
  border-color: var(--color-neon-teal);
}
.proto-toggle .toggle-check {
  opacity: 0;
  transform: scale(0.5);
  transition: opacity var(--duration-micro) var(--ease-out-cubic),
              transform var(--duration-fast) var(--ease-out-quint);
}
.proto-toggle input:checked + .toggle-track .toggle-check {
  opacity: 1;
  transform: scale(1);
}

Das Ergebnis: Ein knackiges Check-Haekchen das mit ease-out-quint reinzoomt. Subtil, aber es fuehlt sich gut an.

Herausforderung 4: Design-Entscheidungen — Was aus dem Prototyp uebernehmen, was nicht?

Die drei kritischen Fragen

Der Prototyp definiert das Ziel-Design, aber nicht jede Entscheidung war 1:1 uebertragbar:

1. Primary-Button-Farbe: Der Prototyp hat Teal-to-Green Gradient, die App hat Orange. Entscheidung: Orange beibehalten — das ist die Markenfarbe fuer CTAs in BudgetBuddy.

2. Settings als Read-Only: Der Prototyp zeigt Settings nur als Anzeige (Werte, kein Edit-Modus). Die App hat Edit-Formulare die funktional noetig sind. Entscheidung: Edit-Modus beibehalten, aber die Read-Only-Darstellung und die Formulare ans neue Design anpassen.

3. Toggle-Style: Slider vs. Checkbox. Entscheidung: Checkbox wie Prototyp — kompakter, passt besser zum dichten Transaction-Layout.

Diese Entscheidungen habe ich bewusst vor der Implementierung geklaert (per interaktiver Rueckfrage). Das hat verhindert, dass ich die halbe App umbaue und dann hoere “nee, Orange sollte bleiben”.

Herausforderung 5: Parallelisierung — 15+ Dateien gleichzeitig migrieren

Das Problem

Die DesignSystem-Migration betraf 18 Dateien mit aehnlichen Aenderungen: bg-base-100 → bg-surface-card, text-base-content → text-text-primary, usw. Jede Datei einzeln durchzugehen waere monoton und fehleranfaellig.

Die Loesung: Parallele Agenten mit klarem Mapping

Ich habe die Arbeit auf mehrere spezialisierte Agenten aufgeteilt, die gleichzeitig laufen:

• Agent 1: Card.fs, Badge.fs, Table.fs, Stats.fs (Daten-Display-Komponenten)
• Agent 2: Loading.fs, Toast.fs, ErrorDisplay.fs, PageHeader.fs, Money.fs, Icons.fs, Primitives.fs, Navigation.fs, Modal.fs, BottomSheet.fs, Form.fs (Rest)
• Agent 3: Settings/View.fs (DaisyUI-Leaks in Formularen)
• Agent 4: Rules/View.fs (DaisyUI-Dropdown-Struktur)
• Agent 5: Dashboard/View.fs, SyncFlow Views (verstreute Farbreferenzen)

Jeder Agent bekam dasselbe Token-Mapping und arbeitete mit Serena’s symbolischen Code-Tools (LSP-basiert). Das Ergebnis: Alle 15+ DesignSystem-Dateien in einem Durchgang migriert, danach ein dotnet build — 0 Fehler.

Herausforderung 6: Code-Review entdeckt drei kritische Bugs

Das Problem

Nach der Migration lief dotnet build und dotnet test fehlerfrei (457 Tests pass). Alles gut? Nein.

Ich habe einen automatisierten Code-Review-Agenten ueber alle 42 geaenderten Dateien laufen lassen. Sein Ergebnis: 3 kritische Issues.

Die drei Bugs

1. Loading.fs — Vergessene DaisyUI-Spinner

Die spinner-Funktion war korrekt auf proto-spinner migriert. Aber ring und dots (alternative Spinner-Varianten) verwendeten noch loading loading-ring und loading loading-dots. Mit DaisyUI entfernt: unsichtbare Spinner.

2. Input.fs — Unsichtbare Checkboxen

Die checkbox und checkboxSimple Funktionen hatten noch checkbox checkbox-sm [--chkbg:...] [--chkfg:...] — reine DaisyUI-Klassen mit internen CSS-Custom-Properties. Ohne DaisyUI: nackte Browser-Checkboxen ohne Styling.

3. ErrorDisplay.fs — Fehlende Fehler-Farben

text-error, bg-error/20, bg-error/5 — die error-Farbe war von DaisyUI definiert. Ohne DaisyUI: weisser Text auf transparentem Hintergrund. Fehleranzeigen waeren unsichtbar gewesen.

Warum ich das uebersehen habe

Alle drei Bugs haben eine Gemeinsamkeit: dotnet build kann sie nicht finden. Es sind CSS-Klassen in String-Literalen — der Compiler sieht nur "loading loading-ring" als gueltigen String. Erst ein Code-Review (oder visuelles Testing) findet solche Brueche.

Die Fixes

// Loading.fs: ring/dots → proto-spinner
let ring size color = spinner size color  // Gleicher Spinner, anderer Name

// Input.fs: DaisyUI checkbox → proto-toggle Pattern
let checkbox isChecked onChange label =
    Html.label [
        prop.className "proto-toggle"
        // ... SVG checkmark structure (same as toggle)
    ]

// ErrorDisplay.fs: error → neon-red
// text-error → text-neon-red
// bg-error/20 → bg-neon-red/20
// border-error → border-neon-red

Lesson Learned

String-basierte CSS-Klassen sind eine Schwachstelle in F#-Frontends. Der Compiler schuetzt dich bei Types, Pattern Matching, und API-Aufrufen. Aber prop.className "loading loading-spinner" ist fuer ihn nur ein String. Hier ist ein Code-Review-Schritt nach CSS-Migrationen essentiell.

Ein moeglicher Ansatz fuer die Zukunft: Alle CSS-Klassen als F#-Konstanten in Tokens.fs definieren und niemals rohe Strings in Views verwenden. Dann wuerde ein Rename in Tokens.fs einen Compile-Error in jeder View erzeugen.

Herausforderung 7: MVU-Integritaet bei grossflaechigen Aenderungen

Das Problem

Bei 42 geaenderten Dateien besteht das Risiko, dass die MVU-Architektur (Model-View-Update) verletzt wird — versehentlich Side-Effects in Views, mutable State ausserhalb des Models, oder Business-Logik in View-Dateien.

Der Check

Ein zweiter Review-Durchlauf, diesmal fokussiert auf MVU-Regeln:

• Views muessen pure Functions vom Model sein
• Alle State-Aenderungen gehen durch Msg → update
• Side-Effects nur via Cmd
• Model als Single Source of Truth

Ergebnis: Keine Verletzungen. Aber der Review hat etwas Wichtiges gefunden: Der ForceImportDuplicates-Button war waehrend des Redesigns verschwunden. Die Msg und der Handler existierten noch in Types.fs und State.fs, aber der UI-Trigger war weg.

Das ist kein MVU-Bug, aber ein Feature-Bug: Wenn ein User in YNAB eine Transaktion loescht und sie neu importieren will, braucht er diesen Button. Er wurde in den expanded Action-Chips der TransactionRow wiederhergestellt — sichtbar nur bei Duplikat-Transaktionen.

Ergebnis

Zahlen

Was sich verbessert hat

1. Konsistenz: Alle Seiten nutzen jetzt dasselbe Token-System. Keine Mischung aus DaisyUI-HSL und Custom-Hex mehr.
2. Bundle-Groesse: DaisyUI’s Komponentenbibliothek ist raus. ~50% weniger CSS.
3. Kontrolle: Jede CSS-Klasse ist jetzt explizit definiert, nicht von einem Framework generiert.
4. Prototyp-Naehe: Settings, Rules, und SyncFlow sehen jetzt aus wie der Prototyp.
5. Kein Dashboard-Umweg: SyncFlow ist direkt die Startseite.

Key Takeaways

1. CSS-Framework-Migrationen brauchen eine Abstraktionsschicht. Das DesignSystem hat hier den Unterschied gemacht. Statt 150+ Views zu aendern, habe ich 18 DesignSystem-Dateien aktualisiert — der Rest hat die neuen Klassen automatisch uebernommen.

2. Additive Migration vor subtraktiver. Erst die neuen CSS-Klassen hinzufuegen (Phase 0), dann den F#-Code umstellen (Phase 1-3), dann das alte Framework entfernen (Phase 4). Niemals gleichzeitig.

3. Code-Review nach CSS-Migrationen ist nicht optional. Der Compiler hilft bei String-basierten CSS-Klassen nicht. Drei von drei kritischen Bugs waren “unsichtbar” fuer dotnet build und dotnet test. Nur ein systematischer Review hat sie gefunden.

In den letzten Tagen habe ich ein umfangreiches Feature für BudgetBuddy implementiert: Ein editierbares Payee-Feld im Sync Flow mit YNAB-Autovervollständigung. Was zunächst wie eine einfache Ergänzung aussah, entwickelte sich zu einer interessanten Architektur-Herausforderung mit mehreren Iterationen und einem klassischen Regressions-Bug am Ende.

Ausgangslage

Der Sync Flow in BudgetBuddy zeigt Transaktionen von der Bank (Comdirect) an, die nach YNAB importiert werden sollen. Bisher konnte der User nur die Kategorie auswählen - der Payee (Zahlungsempfänger) wurde vom Backend automatisch aus den Transaktionsdaten extrahiert und war nicht editierbar.

Das war suboptimal aus mehreren Gründen:

1. Manchmal erkennt das System den Payee falsch
2. Der User möchte einen standardisierten Namen verwenden (z.B. “Amazon” statt “AMZN MKTP DE*…”)
3. Für Überweisungen zwischen YNAB-Konten braucht man spezielle “Transfer”-Payees

Herausforderung 1: ComboBox vs. SearchableSelect

Das Problem

Die bestehende SearchableSelect-Komponente im Design System erlaubt nur die Auswahl aus einer vordefinierten Liste. Der User kann keinen freien Text eingeben. Für Payees brauchte ich aber beides:

• Auswahl aus bestehenden YNAB-Payees (Autovervollständigung)
• Freie Texteingabe für neue/individuelle Payee-Namen

Optionen, die ich betrachtet habe

Option 1: SearchableSelect erweitern

• Pro: Wiederverwendung bestehenden Codes
• Contra: Fundamentale Änderung der Semantik - ein Select gibt immer einen Wert aus der Liste zurück

Option 2: Neue ComboBox-Komponente (gewählt)

• Pro: Klare Trennung der Konzepte, saubere API
• Contra: Code-Duplikation bei Dropdown-Logik

Die Lösung: ComboBox-Komponente

Ich habe mich für eine neue ComboBox-Komponente entschieden, die sich von SearchableSelect unterscheidet:

/// ComboBox: A text input with dropdown suggestions.
/// Unlike SearchableSelect, this allows custom text input (not just selection).
/// The Value is the actual text, not an option id.
[<ReactComponent>]
let ComboBox (props: ComboBoxProps) =
    let isOpen, setIsOpen = React.useState false
    let highlightedIndex, setHighlightedIndex = React.useState -1
    // ...

Architekturentscheidung: Warum eine separate Komponente?

1. Unterschiedliche Semantik: Bei SearchableSelect ist der Value immer eine ID aus der Optionsliste. Bei ComboBox ist der Value der tatsächliche Text - egal ob ausgewählt oder frei eingegeben.

2. Unterschiedliches Verhalten:
   • SearchableSelect: Input filtert Optionen, Auswahl setzt ID als Value
   • ComboBox: Input IST der Value, Optionen sind nur Vorschläge
3. Typensicherheit: Verschiedene Rückgabetypen (ID vs. Text) sollten durch verschiedene APIs erzwungen werden.

Herausforderung 2: Gruppierte Optionen mit Section Headers

Das Problem

YNAB unterscheidet zwischen regulären Payees und “Transfer-Payees” (für Überweisungen zwischen Konten). Im Dropdown sollten diese getrennt angezeigt werden:

Transfers
  Transfer : Tagesgeld ING
  Transfer : Girokonto
Payees
  Amazon
  Edeka
  ...

Die Lösung: ComboBoxOption mit IsDisabled-Flag

Anstatt eine komplexe verschachtelte Datenstruktur einzuführen, habe ich einen eleganten Trick verwendet:

type ComboBoxOption = {
    Id: string
    Label: string
    IsDisabled: bool  // True for section headers (non-selectable)
}

/// Create a section header (non-selectable) for grouping options
let sectionHeader label : ComboBoxOption =
    { Id = ""; Label = label; IsDisabled = true }

Rationale: Section Headers sind einfach “disabled” Optionen. Das bedeutet:

• Sie werden angezeigt, aber nicht auswählbar
• Keyboard-Navigation überspringt sie automatisch
• Filtering berücksichtigt sie (Header bleibt, wenn Items darunter matchen)

Die Filterlogik war der trickreichste Teil:

// Keep section headers if any following non-header matches
let rec filterWithHeaders (opts: ComboBoxOption list) (acc: ComboBoxOption list) =
    match opts with
    | [] -> List.rev acc
    | header :: rest when header.IsDisabled ->
        // Find all items until next header
        let itemsUntilNextHeader =
            rest |> List.takeWhile (fun o -> not o.IsDisabled)
        let hasMatchingItems =
            itemsUntilNextHeader
            |> List.exists (fun o -> o.Label.ToLowerInvariant().Contains searchLower)
        if hasMatchingItems then
            // Include header and matching items
            let matchingItems =
                itemsUntilNextHeader
                |> List.filter (fun o -> o.Label.ToLowerInvariant().Contains searchLower)
            filterWithHeaders (rest |> List.skip itemsUntilNextHeader.Length)
                              (List.rev matchingItems @ header :: acc)
        else
            // Skip header and its items
            filterWithHeaders (rest |> List.skip itemsUntilNextHeader.Length) acc
    | opt :: rest ->
        if opt.Label.ToLowerInvariant().Contains searchLower then
            filterWithHeaders rest (opt :: acc)
        else
            filterWithHeaders rest acc

Warum rekursiv mit Pattern Matching?

F# macht rekursive Algorithmen mit Pattern Matching sehr elegant. Der Code ist fast selbstdokumentierend:

• Leere Liste? Fertig.
• Header? Prüfe ob Items darunter matchen.
• Normales Item? Prüfe ob es selbst matcht.

Herausforderung 3: Keyboard-Navigation mit Disabled Items

Das Problem

Die Standard-Keyboard-Navigation (ArrowUp/ArrowDown) sollte Section Headers überspringen. User wollen zu selektierbaren Items navigieren, nicht auf einem Header landen.

Die Lösung: Selectable Indices

// Get only selectable (non-disabled) options for keyboard navigation
let selectableIndices =
    filteredOptions
    |> List.indexed
    |> List.filter (fun (_, opt) -> not opt.IsDisabled)
    |> List.map fst

// Find next/previous selectable index (skipping disabled items)
let findNextSelectable currentIndex direction =
    if selectableIndices.IsEmpty then -1
    else
        match direction with
        | 1 -> // Down
            selectableIndices
            |> List.tryFind (fun i -> i > currentIndex)
            |> Option.defaultValue (List.head selectableIndices)
        | _ -> // Up
            selectableIndices
            |> List.rev
            |> List.tryFind (fun i -> i < currentIndex)
            |> Option.defaultValue (List.last selectableIndices)

Design-Entscheidung: Wraparound

Wenn man am Ende der Liste ist und “Down” drückt, springt die Navigation zum Anfang zurück (und umgekehrt). Das fühlt sich natürlicher an als “am Ende stehen bleiben”.

Herausforderung 4: Payee-Loading und State-Management

Das Problem

Payees müssen von der YNAB-API geladen werden. Ich brauchte:

1. API-Endpoint zum Laden der Payees
2. State im SyncFlow-Model
3. Loading beim App-Start

Die Architektur

Backend (Shared + Server):

// Shared/Domain.fs - Neue Typen
type YnabPayeeId = YnabPayeeId of Guid

type YnabPayee = {
    Id: YnabPayeeId
    Name: string
    TransferAccountId: Guid option  // Some wenn Transfer-Payee
}

// Shared/Api.fs - API erweitern
type YnabApi = {
    // ...
    getPayees: BudgetId -> Async<Result<YnabPayee list, string>>
}

Frontend State:

type Model = {
    // ...
    Payees: YnabPayee list
    PendingPayeeVersions: Map<TransactionId, int>  // Für Debouncing
}

type Msg =
    | LoadPayees
    | PayeesLoaded of Result<YnabPayee list, string>
    | SetPayeeOverride of TransactionId * string option
    | CommitPayeeChange of TransactionId * string option * int

Der Bug: Fehlende Command-Weiterleitung

Nach der Implementierung funktionierten die Payees nicht - das Dropdown war leer! Nach einigem Debugging fand ich den Fehler:

In src/Client/State.fs wurde der syncFlowCmd von SyncFlow.State.init() nicht an den Parent weitergeleitet:

// VORHER (kaputt):
let cmd = Cmd.batch [
    Cmd.map DashboardMsg dashboardCmd
    Cmd.map SettingsMsg settingsCmd
    initialPageCmd
]

// NACHHER (funktioniert):
let cmd = Cmd.batch [
    Cmd.map DashboardMsg dashboardCmd
    Cmd.map SettingsMsg settingsCmd
    Cmd.map SyncFlowMsg syncFlowCmd  // <-- fehlte!
    initialPageCmd
]

Lesson Learned: Bei Elmish-Architekturen mit verschachtelten Components muss man darauf achten, dass Commands auf allen Ebenen korrekt weitergeleitet werden.

Herausforderung 5: Debouncing für API-Calls

Das Problem

Genau wie bei Kategorien wollte ich nicht bei jedem Tastendruck einen API-Call machen. Schnelles Tippen würde den Server überlasten.

Die Lösung: Version-basiertes Debouncing

Ich habe das gleiche Pattern wie bei Kategorien verwendet:

| SetPayeeOverride (txId, payee) ->
    let transactions =
        model.Transactions
        |> List.map (fun tx ->
            if tx.Transaction.Id = txId then
                { tx with PayeeOverride = payee }
            else tx)

    let currentVersion =
        model.PendingPayeeVersions
        |> Map.tryFind txId
        |> Option.defaultValue 0
    let newVersion = currentVersion + 1

    { model with
        Transactions = transactions
        PendingPayeeVersions = Map.add txId newVersion model.PendingPayeeVersions
    },
    Debounce.delayedDefault (CommitPayeeChange (txId, payee, newVersion))

| CommitPayeeChange (txId, payee, version) ->
    let currentVersion =
        model.PendingPayeeVersions
        |> Map.tryFind txId
        |> Option.defaultValue 0
    if version = currentVersion then
        // Nur committen wenn Version noch aktuell
        // ... API-Call ...
    else
        // Veraltete Version, ignorieren
        model, Cmd.none

Warum Version-Tracking statt Timer-Cancel?

In Elmish gibt es keinen direkten Weg, einen laufenden Cmd zu canceln. Stattdessen:

1. Jede Änderung inkrementiert die Version
2. Der verzögerte Commit enthält die Version zum Zeitpunkt der Erstellung
3. Beim Commit prüfen wir, ob die Version noch aktuell ist
4. Veraltete Commits werden einfach ignoriert

Herausforderung 6: Gruppierung im TransactionList

Das Problem

Die Payees aus der YNAB-API kommen als flache Liste. Ich musste sie gruppieren:

1. Transfer-Payees oben (für Kontoüberweisungen)
2. Reguläre Payees darunter

Die Lösung

let payeeOptions : Input.ComboBoxOption list =
    let transfers, regularPayees =
        model.Payees |> List.partition (fun p -> p.TransferAccountId.IsSome)
    [
        if not transfers.IsEmpty then
            yield Input.sectionHeader "Transfers"
            for p in transfers |> List.sortBy (fun p -> p.Name) do
                let (YnabPayeeId id) = p.Id
                yield { Input.ComboBoxOption.Id = id.ToString()
                        Label = p.Name
                        IsDisabled = false }

        if not regularPayees.IsEmpty then
            if not transfers.IsEmpty then
                yield Input.sectionHeader "Payees"
            for p in regularPayees |> List.sortBy (fun p -> p.Name) do
                let (YnabPayeeId id) = p.Id
                yield { Input.ComboBoxOption.Id = id.ToString()
                        Label = p.Name
                        IsDisabled = false }
    ]

Design-Entscheidung: “Payees” Header nur wenn auch Transfers existieren

Wenn es keine Transfer-Payees gibt, brauchen wir auch keinen “Payees”-Header - das wäre redundant. Der Code prüft das explizit mit if not transfers.IsEmpty then.

Herausforderung 7: Die Regression - Verlorene External Links

Das Problem

Nach dem Release des Payee-Features bemerkte ich, dass die Amazon Order Links verschwunden waren! Diese Links führen direkt zur Amazon-Bestellseite und sind extrem nützlich beim Kategorisieren.

Root Cause: Beim Refactoring des Payee-Feldes hatte ich den Code für External Links versehentlich entfernt. Die Links wurden im Backend korrekt berechnet, aber nicht mehr im Frontend angezeigt.

Die Lösung: externalLinkButton Helper

Ich habe eine dedizierte Helper-Funktion erstellt:

let externalLinkButton (externalLinks: ExternalLink list) =
    match externalLinks |> List.tryHead with
    | Some link ->
        Html.a [
            prop.className "p-1 rounded hover:bg-neon-teal/10 text-neon-teal/60 hover:text-neon-teal transition-colors flex-shrink-0"
            prop.href link.Url
            prop.target "_blank"
            prop.rel "noopener noreferrer"
            prop.title link.Label
            prop.children [ Icons.externalLink Icons.XS Icons.NeonTeal ]
        ]
    | None -> Html.none

Und dann unterschiedliche Behandlung für aktive vs. übersprungene Transaktionen:

Skipped Transactions: Der Payee-Text selbst wird zum Link

if tx.Status = Skipped then
    match tx.ExternalLinks |> List.tryHead with
    | Some link ->
        Html.a [
            prop.className "text-sm text-neon-teal/60 hover:text-neon-teal truncate flex items-center gap-1"
            prop.href link.Url
            prop.target "_blank"
            prop.title $"{displayPayee} - {link.Label}"
            prop.children [
                Html.span [ prop.className "truncate"; prop.text displayPayee ]
                Icons.externalLink Icons.XS Icons.NeonTeal
            ]
        ]
    | None ->
        Html.span [ prop.text displayPayee ]

Active Transactions: Separates Link-Icon neben dem ComboBox

else
    // Active: render ComboBox (interactive)
    Input.comboBoxGrouped displayPayee onChange "Payee..." payeeOptions
    // External link icon für aktive Transaktionen
    if tx.Status <> Skipped then
        externalLinkButton tx.ExternalLinks

Rationale für unterschiedliche Behandlung:

• Bei übersprungenen Transaktionen ist der Payee nicht editierbar (kein ComboBox), also kann der Text selbst klickbar sein
• Bei aktiven Transaktionen brauchen wir den ComboBox für die Eingabe, also muss der Link daneben erscheinen

Lessons Learned

1. Feature-Additions können Features entfernen

Beim Hinzufügen des Payee-ComboBox habe ich den External Link Code überschrieben. Das zeigt: Auch bei “additiven” Änderungen muss man prüfen, was dabei verloren geht.

Gegenmaßnahme: Vor größeren UI-Änderungen eine Checkliste machen: Was war vorher da? Was muss erhalten bleiben?

2. Elmish Commands werden nicht automatisch weitergeleitet

Nested Components in Elmish haben ihre eigenen init-Funktionen, die Commands zurückgeben. Diese müssen explizit an den Parent weitergeleitet werden. Das ist ein häufiger Fehler!

3. Disabled Items sind ein guter Trick für Gruppierung

Anstatt komplexe verschachtelte Datenstrukturen einzuführen, kann man “disabled” Items als Section Headers missbrauchen. Das ist pragmatisch und funktioniert gut.

4. Version-basiertes Debouncing ist elegant in Elmish

Ohne Möglichkeit zum Command-Cancelling ist das Version-Pattern die beste Lösung: Einfach alte Commits ignorieren.

Fazit

Das Payee-Feature war eine interessante Reise durch mehrere Schichten der Anwendung:

1. Design System: Neue ComboBox-Komponente mit gruppierter Option-Liste
2. API: Neuer Endpoint für YNAB-Payees
3. State Management: Payee-Loading und Debouncing
4. UI Integration: Mobile und Desktop Layouts mit External Links

Am Ende sind es ~300 neue Zeilen Code im ComboBox und ~100 Zeilen im TransactionRow - ein überschaubares Feature mit interessanten Architektur-Entscheidungen.

Statistiken:

• Tests: 377 passed, 6 skipped
• Build: Erfolgreich (0 Errors, 2 Warnings)
• Neue Komponenten: ComboBox, comboBoxGrouped, sectionHeader, externalLinkButton

Key Takeaways für Neulinge

1. Semantik vor Wiederverwendung: Manchmal ist eine neue Komponente besser als eine bestehende zu “verbiegen”. ComboBox und SearchableSelect haben unterschiedliche Semantiken und verdienen getrennte Implementierungen.

2. Flache Datenstrukturen mit Flags: Anstatt verschachtelter GroupedOption<Option> Typen kann man oft mit einem simplen IsDisabled: bool Flag auskommen. Keep It Simple!

3. Regressions-Tests bei UI-Änderungen: Auch wenn man “nur” etwas hinzufügt, sollte man checken was dabei kaputt gehen könnte. Eine manuelle Checkliste hilft.

Für wen ist dieser Guide? Erfahrene F#-Entwickler, die verstehen wollen, wie ein Full-Stack F# Projekt strukturiert ist, und Web-Entwickler aus anderen Sprachen (React, Redux, Clean Architecture), die die F#-Äquivalente kennenlernen möchten.

Einleitung: Warum F# Full-Stack?

BudgetBuddy ist eine Self-Hosted Web-App, die Banktransaktionen von Comdirect mit YNAB (You Need A Budget) synchronisiert. Die zentrale Architektur-Entscheidung war: F# durchgehend – vom Frontend bis zum Backend.

Warum? Drei Gründe:

1. Geteilte Typen: Domain-Typen werden einmal definiert und in beiden Projekten verwendet. Keine Drift, keine “Contract Tests”, keine JSON-Schema-Synchronisation.

2. Type-Safe RPC: Fable.Remoting ersetzt REST APIs durch typisierte Funktionsaufrufe. Änderst du eine API-Signatur, bricht der Build – nicht erst der Production-User.

3. Konsistentes Mental Model: Pattern Matching, Discriminated Unions, und Immutability überall. Kein Context-Switch zwischen TypeScript und C#.

Teil 1: Die 4-Projekt-Struktur

src/
├── Shared/     → Geteilte Typen (Domain.fs, Api.fs)
├── Server/     → Backend (Giraffe + Fable.Remoting)
├── Client/     → Frontend (Elmish + Feliz)
└── Tests/      → Expecto Tests

Warum diese Aufteilung?

Shared ist der Schlüssel. Jeder Typ, der über die Netzwerkgrenze geht, lebt hier:

// src/Shared/Domain.fs
type TransactionStatus =
    | Pending
    | AutoCategorized
    | ManualCategorized
    | NeedsAttention
    | Imported
    | Skipped

Dieser TransactionStatus wird:

• Im Backend gespeichert und verarbeitet
• Im Frontend angezeigt und geändert
• Über die API hin- und hergeschickt

Eine Definition, null Drift.

Vergleich zu anderen Stacks

Teil 2: Shared Types & API Contracts

Domain.fs – Das Herzstück

Die wichtigste Datei im Projekt. Hier werden alle Domain-Konzepte modelliert:

// Typisierte IDs verhindern "String-Soup"
type TransactionId = TransactionId of Guid
type RuleId = RuleId of Guid
type YnabCategoryId = YnabCategoryId of Guid

// Discriminated Unions für endliche Zustände
type PatternType =
    | Contains    // Substring-Match
    | Exact       // Exakter Match
    | Regex       // Regulärer Ausdruck

// Records für strukturierte Daten
type Rule = {
    Id: RuleId
    Name: string
    Pattern: string
    PatternType: PatternType
    CategoryId: YnabCategoryId option
    CategoryName: string option
    TargetField: TargetField
    PayeeOverride: string option
    Priority: int
    Enabled: bool
    CreatedAt: DateTime
    UpdatedAt: DateTime
}

Architektur-Entscheidung: Warum typisierte IDs?

Statt Guid überall zu verwenden, haben wir TransactionId, RuleId, etc. Das verhindert:

// ❌ Kompiliert, aber semantisch falsch
let deleteRule (transactionId: Guid) = ...
deleteRule someTransaction.Id  // Oops, Transaction statt Rule!

// ✅ Kompiliert nicht
let deleteRule (ruleId: RuleId) = ...
deleteRule someTransaction.Id  // Compiler-Error!

Kosten: Etwas mehr Boilerplate. Nutzen: Unmöglichkeit einer ganzen Fehlerklasse.

Api.fs – Die Verträge

// src/Shared/Api.fs
type SettingsApi = {
    getSettings: unit -> Async<AppSettings>
    saveYnabToken: string -> Async<SettingsResult<unit>>
    testYnabConnection: unit -> Async<SettingsResult<YnabBudgetWithAccounts list>>
    // ...
}

type SyncApi = {
    startSync: unit -> Async<SyncResult<SyncSession>>
    categorizeTransaction: TransactionId * YnabCategoryId option * string option -> Async<SyncResult<unit>>
    importToYnab: SyncSessionId -> Async<SyncResult<ImportResult>>
    // ...
}

Das ist der API-Vertrag. Nicht eine Swagger-Datei, nicht eine Markdown-Dokumentation – sondern F#-Typen, die der Compiler prüft.

Für React-Entwickler: Stell dir vor, dein Backend wäre eine TypeScript-Bibliothek mit perfekten Typen. Kein any, kein unknown, kein as.

Result-Typen für Fehlerbehandlung

Jeder API-Endpunkt verwendet typisierte Fehler:

type SettingsResult<'T> = Result<'T, SettingsError>

type SettingsError =
    | YnabTokenInvalid of string
    | YnabConnectionFailed of int * string
    | ComdirectCredentialsInvalid of string * string
    | EncryptionFailed of string
    | DatabaseError of string * string

Warum nicht Exceptions? Exceptions sind “invisible return types”. Mit Result<'T, SettingsError> ist klar:

1. Diese Funktion kann fehlschlagen
2. Diese spezifischen Fehler können auftreten
3. Der Aufrufer muss beide Fälle behandeln

Teil 3: Backend-Architektur

Die Schichten

Request → Api.fs → Domain.fs → Persistence.fs → SQLite
            ↓           ↓
       Validation    Pure Logic

Api.fs – Der Eintrittspunkt

// src/Server/Api.fs
let settingsApi : SettingsApi = {
    saveYnabToken = fun token -> async {
        // 1. Validierung
        match validateYnabToken token with
        | Error errors -> return Error (SettingsError.YnabTokenInvalid (String.concat "; " errors))
        | Ok validToken ->
            // 2. Externer API-Call (Test ob Token gültig ist)
            match! YnabClient.getBudgets validToken with
            | Error ynabError ->
                return Error (SettingsError.YnabConnectionFailed (0, ynabErrorToString ynabError))
            | Ok _ ->
                // 3. Persistierung
                try
                    do! Persistence.Settings.setSetting "ynab_token" validToken true
                    return Ok ()
                with ex ->
                    return Error (SettingsError.DatabaseError ("save_ynab_token", ex.Message))
    }
    // ...
}

Pattern: Validierung → Business Logic → Side Effects

Domain.fs – Pure Funktionen

// src/Server/Domain.fs
// KEINE I/O-Operationen hier!

let applyRule (rule: Rule) (transaction: BankTransaction) : bool =
    let fieldValue =
        match rule.TargetField with
        | Payee -> transaction.Payee
        | Memo -> transaction.Memo |> Option.defaultValue ""
        | Combined -> $"{transaction.Payee} {transaction.Memo |> Option.defaultValue ""}"

    match rule.PatternType with
    | Contains -> fieldValue.Contains(rule.Pattern, StringComparison.OrdinalIgnoreCase)
    | Exact -> String.Equals(fieldValue, rule.Pattern, StringComparison.OrdinalIgnoreCase)
    | Regex -> Regex.IsMatch(fieldValue, rule.Pattern, RegexOptions.IgnoreCase)

Architektur-Entscheidung: Warum “Pure Domain”?

1. Testbarkeit: Keine Mocks nötig. Input → Output, fertig.
2. Reasoning: Keine versteckten Abhängigkeiten, keine Seiteneffekte.
3. Parallelisierung: Pure Funktionen sind thread-safe by design.

Für Clean-Architecture-Kenner: Das entspricht dem “Use Case Layer” oder “Application Layer” – aber funktional statt OOP.

Persistence.fs – Die Datenbank-Grenze

// src/Server/Persistence.fs
module Settings =
    let getSetting (key: string) : Async<string option> = async {
        use! conn = getConnection()
        let! result = conn.QueryFirstOrDefaultAsync<string>(
            "SELECT value FROM settings WHERE key = @Key",
            {| Key = key |})
        return Option.ofObj result
    }

    let setSetting (key: string) (value: string) (encrypt: bool) : Async<unit> = async {
        let finalValue = if encrypt then Encryption.encrypt value else value
        use! conn = getConnection()
        do! conn.ExecuteAsync(
            "INSERT OR REPLACE INTO settings (key, value, is_encrypted) VALUES (@Key, @Value, @IsEncrypted)",
            {| Key = key; Value = finalValue; IsEncrypted = encrypt |}) |> Async.AwaitTask |> Async.Ignore
    }

Warum Dapper statt Entity Framework?

1. Explizite Queries: Keine Magie, keine N+1-Überraschungen
2. F#-freundlich: Funktioniert gut mit Records und Option-Types
3. Leichtgewicht: Kein Change-Tracking, keine Migrations-Komplexität

Fable.Remoting – Die Magie

// src/Server/Api.fs
let webApp =
    Remoting.createApi()
    |> Remoting.withRouteBuilder routeBuilder
    |> Remoting.fromValue settingsApi
    |> Remoting.fromValue syncApi
    |> Remoting.fromValue rulesApi
    |> Remoting.fromValue ynabApi
    |> Remoting.buildHttpHandler

Das generiert automatisch HTTP-Endpunkte für alle API-Funktionen. Der Client ruft sie so auf:

// src/Client/Api.fs
let settings = Remoting.createApi() |> Remoting.buildProxy<SettingsApi>

// Aufruf (irgendwo im Client)
let! result = Api.settings.saveYnabToken token

Kein REST, keine URLs, keine JSON-Serialisierung – alles automatisch.

Teil 4: Frontend-Architektur (MVU/Elmish)

Das MVU-Pattern

MVU (Model-View-Update) ist das funktionale Äquivalent zu Redux:

// src/Client/State.fs
type Model = {
    CurrentPage: Page
    Dashboard: DashboardModel
    Settings: SettingsModel
    SyncFlow: SyncFlowModel
    Rules: RulesModel
    Toasts: Toast list
}

type Msg =
    | NavigateTo of Page
    | UrlChanged of string list
    | ShowToast of string * ToastType
    | DismissToast of Guid
    | DashboardMsg of DashboardMsg
    | SettingsMsg of SettingsMsg
    | SyncFlowMsg of SyncFlowMsg
    | RulesMsg of RulesMsg

Die Update-Funktion

let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
    match msg with
    | NavigateTo page ->
        let segments = Routing.toUrlSegments page
        model, Cmd.navigate(segments |> List.toArray)

    | UrlChanged segments ->
        let page = Routing.parseUrl segments
        if page = model.CurrentPage then
            model, Cmd.none
        else
            let extraCmds =
                match page with
                | Dashboard -> Cmd.map DashboardMsg (Cmd.ofMsg LoadLastSession)
                | SyncFlow -> Cmd.map SyncFlowMsg (Cmd.ofMsg LoadCurrentSession)
                | Rules -> Cmd.map RulesMsg (Cmd.ofMsg LoadRules)
                | Settings -> Cmd.map SettingsMsg (Cmd.ofMsg LoadSettings)
            { model with CurrentPage = page }, extraCmds

    | DashboardMsg dashboardMsg ->
        let model', cmd = Dashboard.State.update dashboardMsg model.Dashboard
        { model with Dashboard = model' }, Cmd.map DashboardMsg cmd
    // ...

Architektur-Entscheidung: Component-basierte Verschachtelung

Jede “Page” hat eigene Types.fs, State.fs, View.fs:

Components/
├── Dashboard/
│   ├── Types.fs    → DashboardModel, DashboardMsg
│   ├── State.fs    → init, update
│   └── View.fs     → view
├── SyncFlow/
│   └── ...

Die Haupt-State.fs delegiert an die Komponenten und handled nur Cross-Cutting-Concerns (Toasts, Navigation).

RemoteData – Async State Management

// src/Client/Types.fs
type RemoteData<'T> =
    | NotAsked     // Noch nicht geladen
    | Loading      // Lädt gerade
    | Success of 'T
    | Failure of string

Warum nicht einfach 'T option?

option unterscheidet nicht zwischen “noch nicht geladen” und “geladen, aber leer”. RemoteData macht alle vier Zustände explizit:

match model.Transactions with
| NotAsked -> Html.text "Klicke auf Laden"
| Loading -> Loading.spinner MD Teal
| Success [] -> Html.text "Keine Transaktionen"
| Success txns -> TransactionList.view txns dispatch
| Failure err -> ErrorDisplay.card err (Some retry)

Für Redux-Entwickler: Das ist wie { loading: boolean, error: string | null, data: T | null } – aber ohne die Möglichkeit inkonsistenter Zustände (loading=true UND error!=null).

Das Helper-Modul

module RemoteData =
    let map (f: 'a -> 'b) (rd: RemoteData<'a>) : RemoteData<'b> =
        match rd with
        | Success x -> Success (f x)
        | Loading -> Loading
        | NotAsked -> NotAsked
        | Failure err -> Failure err

    let isLoading rd = match rd with Loading -> true | _ -> false
    let withDefault defaultValue rd = match rd with Success x -> x | _ -> defaultValue
    let fromResult result = match result with Ok x -> Success x | Error e -> Failure e

Das DesignSystem

DesignSystem/
├── Tokens.fs      → Farben, Abstände, Fonts
├── Primitives.fs  → Container, Grid, Stack
├── Button.fs      → Button-Varianten
├── Card.fs        → Card-Layouts
├── Input.fs       → Form-Inputs
├── Modal.fs       → Dialog-Komponenten
├── ErrorDisplay.fs → Fehler-Darstellung
└── ...

Architektur-Entscheidung: Warum ein eigenes Design System?

1. Konsistenz: Alle Buttons sehen gleich aus, alle Errors werden gleich angezeigt
2. Wiederverwendung: Button.primary "Speichern" onClick statt 20 Zeilen Tailwind
3. Typsicherheit: Props sind F#-Records, nicht String-Attributes

// Statt:
Html.button [
    prop.className "btn btn-primary bg-orange-500 hover:bg-orange-600 ..."
    prop.onClick (fun _ -> dispatch Save)
    prop.text "Speichern"
]

// Schreibt man:
Button.primary "Speichern" (fun () -> dispatch Save)

Teil 5: Wie hängt alles zusammen?

Der Datenfluss eines API-Calls

1. User klickt "Speichern" im Frontend
   └→ dispatch (SettingsMsg (SaveYnabToken token))

2. State.fs update-Funktion
   └→ Cmd.OfAsync.either Api.settings.saveYnabToken token ...

3. Fable.Remoting serialisiert und sendet HTTP-Request

4. Server Api.fs empfängt
   └→ validateYnabToken token
   └→ YnabClient.getBudgets token
   └→ Persistence.Settings.setSetting ...
   └→ return Ok ()

5. Fable.Remoting sendet Response zurück

6. Client empfängt Result
   └→ dispatch (SettingsMsg (YnabTokenSaved (Ok ())))

7. State.fs update-Funktion
   └→ { model with Settings = { model.Settings with SaveStatus = Success () } }

8. View rendert neuen Zustand
   └→ "Token gespeichert!" Toast

Wo fängt man an, um X zu verstehen?

Lessons Learned

Was ich anders machen würde

1. Früher ein Design System: Die ersten UI-Komponenten waren inline Tailwind. Die Migration zu DesignSystem-Komponenten hat Zeit gekostet.

2. Mehr Property-Based Tests: Unit-Tests sind gut, aber FsCheck hätte Edge-Cases früher gefunden.

3. Striktere Trennung von Queries/Commands: Manche API-Funktionen machen beides. CQRS-Trennung wäre sauberer.

Was gut funktioniert hat

1. Shared Types von Anfang an: Nie “Contract Drift” gehabt.

2. Result-Types statt Exceptions: Fehlerbehandlung ist explizit und vollständig.

3. MVU für komplexe Flows: Der Sync-Wizard mit 7 Zuständen wäre mit imperativem Code ein Albtraum.

Key Takeaways

1. Shared Types sind der größte Gewinn von F# Full-Stack: Eine Typdefinition, zwei Projekte, null Synchronisations-Aufwand.

2. MVU/Elmish ist Redux done right: Gleiche Ideen, aber mit Compiler-Support statt Runtime-Checks.

3. Pure Domain Logic zahlt sich aus: Leicht zu testen, leicht zu verstehen, leicht zu ändern.

4. Fable.Remoting eliminiert eine ganze Fehlerklasse: Keine falschen URLs, keine JSON-Parsing-Errors, keine vergessenen Endpunkte.

Dieser Guide wurde geschrieben, um Entwicklern den Einstieg in die BudgetBuddy-Codebase zu erleichtern. Bei Fragen: Issues auf GitHub sind willkommen!

Ein klassischer Bug, der zeigt, warum “Single Source of Truth” keine optionale Best Practice ist, sondern eine Notwendigkeit. In diesem Post beschreibe ich, wie ein simpler Format-Unterschied zwischen zwei Dateien zu einem kritischen Bug führte – und was wir daraus lernen können.

Die Ausgangslage

BudgetBuddy importiert Banktransaktionen in YNAB (You Need A Budget). Um Duplikate zu vermeiden, verwendet YNAB ein import_id Feld: wenn zwei Transaktionen dieselbe Import-ID haben, wird die zweite als Duplikat erkannt und abgelehnt.

Das System bestand aus zwei Komponenten:

1. YnabClient.fs – Generiert Import-IDs beim Erstellen von Transaktionen
2. DuplicateDetection.fs – Prüft vor dem Import, ob Transaktionen bereits existieren

Soweit die Theorie. In der Praxis hatte ich einen Bug, der lange unentdeckt blieb.

Das Problem: “Force Import” erstellt Duplikate

Ich stellte fest: “Wenn ich Force Import verwende, erscheinen meine Transaktionen doppelt in YNAB.”

Force Import ist eine Funktion, die Transaktionen erneut importiert, selbst wenn sie als Duplikate erkannt wurden. Nützlich, wenn man eine Transaktion in YNAB gelöscht hat und sie wieder haben möchte.

Meine erste Reaktion: “Das kann nicht sein, Force Import generiert neue UUIDs als Import-IDs, also sollten sie als neue Transaktionen erkannt werden.”

Aber der Bug war real.

Herausforderung 1: Das Format-Mismatch finden

Die Symptome verstehen

Ich habe mir die Logs angeschaut und etwas Seltsames bemerkt: bei Force Import wurden ALLE Transaktionen als “Duplikate” markiert, nicht nur einzelne. Das war merkwürdig – wie konnten alle Transaktionen Duplikate sein?

Die Spurensuche

Ich habe die beiden relevanten Dateien verglichen:

YnabClient.fs (wie Import-IDs generiert werden):

let importId =
    let txIdNoDashes = txId.ToString().Replace("-", "")
    $"BB:{txIdNoDashes}"

DuplicateDetection.fs (wie Import-IDs gesucht werden):

let matchesByImportId (bankTx: BankTransaction) (ynabTx: YnabTransaction) : bool =
    match ynabTx.ImportId with
    | Some importId ->
        let (TransactionId txId) = bankTx.Id
        importId.StartsWith($"BUDGETBUDDY:{txId}:")

Da war es. Offensichtlich. Peinlich offensichtlich.

• YnabClient generierte: BB:tx123456
• DuplicateDetection suchte nach: BUDGETBUDDY:tx-123-456:

Unterschiedliches Prefix (BB: vs BUDGETBUDDY:), unterschiedliche Behandlung der Bindestriche (entfernt vs beibehalten), und ein zusätzlicher Doppelpunkt am Ende.

Warum war das so schlimm?

Die matchesByImportId Funktion fand niemals einen Match. Das bedeutete:

• Der Import-ID-basierte Duplikat-Check funktionierte nicht
• Das System fiel auf andere Heuristiken zurück (Datum, Betrag, Payee)
• Diese Heuristiken waren unzuverlässig

Herausforderung 2: Die gefährliche Fallback-Logik

Der zweite Bug im Bug

Während ich den Code analysierte, fand ich noch etwas Erschreckendes in Api.fs:

// ALTE VERSION - GEFÄHRLICH
if mapped.IsEmpty && not result.DuplicateImportIds.IsEmpty then
    toImport |> List.map (fun tx -> tx.Transaction.Id)
else
    mapped

Diese Logik sagte: “Wenn wir die Duplikat-IDs nicht den ursprünglichen Transaktionen zuordnen können, markiere ALLE Transaktionen als Duplikate.”

Das war die eigentliche Ursache für den Bug! Weil das Format-Mismatch dafür sorgte, dass mapped immer leer war, wurden bei jedem Import ALLE Transaktionen als Duplikate markiert.

Die “Sicherheitslogik” die alles kaputt machte

Diese Fallback-Logik war vermutlich als Sicherheitsnetz gedacht: “Lieber zu viele Duplikate erkennen als zu wenige.” Aber in Kombination mit dem Format-Bug wurde sie zum Problem.

Lesson Learned: Fallback-Logik, die “sicherheitshalber” den schlimmsten Fall annimmt, kann genau das Gegenteil bewirken. Lieber ehrlich scheitern (mit Logging) als still falsche Annahmen treffen.

Herausforderung 3: Tautologische Tests

Tests die nichts testen

Jetzt kam die unangenehme Frage: Warum haben die Tests das nicht gefangen?

Die Antwort: Die Tests waren tautologisch. Sie testeten das falsche Format gegen das falsche Format:

// ALTE VERSION - TAUTOLOGISCH
testCase "generates consistent import IDs for same transaction" <| fun () ->
    let transactionId = TransactionId "tx-123"
    let bookingDate = DateTime(2025, 11, 29)

    let (TransactionId id) = transactionId
    let importId1 = $"BUDGETBUDDY:{id}:{bookingDate.Ticks}"
    let importId2 = $"BUDGETBUDDY:{id}:{bookingDate.Ticks}"

    Expect.equal importId1 importId2 "Same transaction should generate same import ID"

Dieser Test prüft, ob X == X. Natürlich ist das wahr. Aber er testet nicht, ob der Code das richtige Format verwendet!

Das gleiche Problem in den DuplicateDetection-Tests:

// ALTE VERSION - TAUTOLOGISCH
test "matchesByImportId returns true when import IDs match" {
    let txId = "TX123"
    let ynabTx = createYnabTransaction ... (Some $"BUDGETBUDDY:{txId}:12345")

    let result = matchesByImportId bankTx' ynabTx
    Expect.isTrue result "Should match by import ID"
}

Der Test erstellt das Format manuell (BUDGETBUDDY:...) und prüft dann, ob der Code dieses Format findet. Das funktioniert, weil der Test und der Code zufällig das gleiche (falsche) Format verwenden.

Das fundamentale Problem

Tautologische Tests sind gefährlich, weil sie:

1. Grün sind – sie geben falsches Vertrauen
2. Bugs nicht finden – sie testen nicht das echte Verhalten
3. Refactoring verhindern – sie brechen bei Änderungen, auch wenn das echte Verhalten korrekt bleibt

Die Lösung: Single Source of Truth

Schritt 1: Zentralisieren des Formats

Ich habe das Import-ID-Format in Domain.fs zentralisiert:

/// Import ID prefix used for YNAB transactions to prevent duplicates.
/// MUST be used in both YnabClient (generation) and DuplicateDetection (matching).
[<Literal>]
let ImportIdPrefix = "BB"

/// Generates an import ID from a transaction ID.
/// Format: "BB:{transactionId}" (max 36 chars for YNAB)
let generateImportId (TransactionId txId) : string =
    let txIdNoDashes = txId.Replace("-", "")
    $"{ImportIdPrefix}:{txIdNoDashes}"

/// Checks if an import ID matches a transaction ID.
/// Used in duplicate detection to identify transactions we previously imported.
let matchesImportId (TransactionId txId) (importId: string) : bool =
    let txIdNoDashes = txId.Replace("-", "")
    importId.StartsWith($"{ImportIdPrefix}:{txIdNoDashes}")

Warum diese Entscheidungen:

1. [<Literal>] für den Prefix – Compile-time Konstante, kann nicht versehentlich geändert werden
2. Beide Funktionen nebeneinander – Macht die Beziehung zwischen Generierung und Matching offensichtlich
3. In Domain.fs – Das Shared-Modul, das von Server und Tests importiert wird

Schritt 2: YnabClient anpassen

// NEUE VERSION
let importId =
    if forceNewImportId then
        let newGuid = Guid.NewGuid().ToString("N")
        $"{Shared.Domain.ImportIdPrefix}:{newGuid}"
    else
        Shared.Domain.generateImportId tx.Transaction.Id

Jetzt verwendet YnabClient die zentrale Funktion. Kein Risiko mehr, dass das Format an einer Stelle geändert wird und an der anderen nicht.

Schritt 3: DuplicateDetection anpassen

// NEUE VERSION
let matchesByImportId (bankTx: BankTransaction) (ynabTx: YnabTransaction) : bool =
    match ynabTx.ImportId with
    | None -> false
    | Some importId ->
        Shared.Domain.matchesImportId bankTx.Id importId

Keine duplizierte Logik mehr. Die Matching-Logik ist jetzt exakt das Gegenstück zur Generierungs-Logik.

Schritt 4: Gefährliche Fallback-Logik entfernen

// NEUE VERSION
if mapped.IsEmpty && not result.DuplicateImportIds.IsEmpty then
    printfn "[WARNING] Could not map %d duplicate import IDs to transaction IDs: %A"
        result.DuplicateImportIds.Length result.DuplicateImportIds
// Only return actually mapped duplicates, never all transactions
mapped

Statt “alle als Duplikate markieren” loggen wir jetzt eine Warnung. Das System verhält sich ehrlich: wenn etwas nicht funktioniert, tut es so, als hätte es keine Duplikate gefunden – was sicherer ist als das Gegenteil.

Schritt 5: Echte Tests schreiben

// NEUE VERSION - ECHTER TEST
testCase "generateImportId produces correct format with BB prefix" <| fun () ->
    let txId = TransactionId "TX-123-456"
    let importId = generateImportId txId

    Expect.stringStarts importId $"{ImportIdPrefix}:" "Import ID should start with BB:"
    Expect.stringContains importId "TX123456" "Should contain transaction ID without dashes"

testCase "matchesImportId works with generateImportId output" <| fun () ->
    let txId = TransactionId "abc-def-ghi"
    let importId = generateImportId txId

    Expect.isTrue (matchesImportId txId importId) "Generated ID should match its source"

test "matchesByImportId returns true when import IDs match" {
    let txId = TransactionId "TX123"
    let bankTx' = { bankTx with Id = txId }
    // Use Domain.generateImportId to ensure test uses same format as production code
    let importId = generateImportId txId
    let ynabTx = createYnabTransaction ... (Some importId)

    let result = matchesByImportId bankTx' ynabTx
    Expect.isTrue result "Should match by import ID"
}

Der Unterschied: Die Tests verwenden jetzt generateImportId statt ein hardcodiertes Format. Wenn das Format geändert wird, ändern sich Tests und Produktionscode gemeinsam.

Lessons Learned

1. “Single Source of Truth” ist nicht optional

Wenn zwei Code-Teile dasselbe Format oder dieselbe Logik verwenden, müssen sie eine gemeinsame Quelle haben. Alles andere ist ein Bug, der nur darauf wartet zu passieren.

In diesem Fall:

• Vorher: Format in YnabClient.fs UND DuplicateDetection.fs (unabhängig)
• Nachher: Format in Domain.fs, verwendet von beiden

2. Tautologische Tests sind gefährlicher als keine Tests

Ein Test, der X == X prüft, gibt falsches Vertrauen. Er ist grün, also denkt man, alles funktioniert. Aber er testet nichts Nützliches.

Erkennungsmerkmale tautologischer Tests:

• Der Test erstellt Testdaten mit demselben Code/Format, den er dann prüft
• Der Test verwendet hardcodierte Werte, die zufällig mit dem aktuellen Code übereinstimmen
• Wenn man den Produktionscode ändert, muss man auch die Test-Assertions ändern

Lösung: Tests sollten eine andere “Quelle der Wahrheit” haben als der Code selbst. In diesem Fall: Domain.generateImportId.

3. Defensive Fallbacks können mehr schaden als nutzen

Die Logik “wenn unser Check fehlschlägt, nimm den schlimmsten Fall an” klingt sicher. Aber sie kann genau das Gegenteil bewirken:

• Sie versteckt den eigentlichen Bug (der Check schlägt fehl!)
• Sie verursacht oft mehr Schaden als ein ehrliches Scheitern
• Sie macht Debugging schwieriger

Besser: Loggen und ehrlich scheitern. Lieber eine fehlende Funktion als eine kaputte.

4. Bugs in “glue code” sind am schwierigsten zu finden

Der Bug war nicht in der Generierungs-Logik. Der Bug war nicht in der Matching-Logik. Beide Teile für sich waren korrekt. Der Bug war im Zusammenspiel – in der Annahme, dass beide dasselbe Format verwenden.

Solche Bugs sind schwer zu testen, weil Unit-Tests typischerweise einzelne Komponenten isoliert testen.

Lösung: Integration-Tests, die den gesamten Flow testen. Und: weniger “glue code” durch bessere Abstraktion (Single Source of Truth).

Fazit

Am Ende war es ein simpler Fix: ~50 Zeilen neuer Code in Domain.fs, einige Zeilen gelöscht in YnabClient.fs und DuplicateDetection.fs, und überarbeitete Tests.

Änderungen im Überblick:

• src/Shared/Domain.fs – Neue Funktionen generateImportId, matchesImportId, Konstante ImportIdPrefix
• src/Server/YnabClient.fs – Verwendet jetzt Domain.generateImportId
• src/Server/DuplicateDetection.fs – Verwendet jetzt Domain.matchesImportId
• src/Server/Api.fs – Gefährliche Fallback-Logik durch Logging ersetzt
• src/Tests/*.fs – Tests verwenden jetzt die Domain-Funktionen statt hardcodierte Formate

Build: Erfolgreich Tests: 375/375 bestanden

Aber die Geschichte war noch nicht zu Ende…

Der Follow-up Bug: Comdirect IDs mit Slashes

Das Problem kehrt zurück

Nur wenige Stunden nach dem Fix meldete sich das gleiche Symptom zurück: Force Import funktionierte nicht, alle Transaktionen wurden als Duplikate markiert.

Die Docker-Logs zeigten eine alarmierende Meldung:

[WARNING] Could not map 41 duplicate import IDs to transaction IDs

Moment – diese Warnung hatte ich gerade erst eingebaut. Wenn sie erscheint, bedeutet das, dass das Mapping zwischen YNAB-Duplikat-IDs und lokalen Transaktions-IDs fehlschlägt. Aber wie konnte das sein, wenn ich gerade erst das Format vereinheitlicht hatte?

Die Spurensuche

Ich schaute mir die Api.fs genauer an. Dort fand ich diese Zeile:

// ALTE VERSION
let cleanId = txIdPart.Split('/') |> Array.head

Diese Zeile sollte das Prefix BB: von der Import-ID abtrennen. Aber warum wurde an / gesplittet?

Dann fiel es mir wie Schuppen von den Augen: Comdirect Transaktions-IDs enthalten Slashes!

Eine typische Comdirect-ID sieht so aus:

3I2C21XS1ZXDAP9P/33825

Der Slash ist Teil der ID, nicht ein Trennzeichen. Aber der Code Split('/') zerlegte diese ID in zwei Teile und behielt nur den ersten:

Input:  "BB:3I2C21XS1ZXDAP9P/33825"
Nach Split('/'):  ["BB:3I2C21XS1ZXDAP9P", "33825"]
Array.head:  "BB:3I2C21XS1ZXDAP9P"  // FALSCH - Suffix fehlt!

Die lokalen Transaktionen hatten aber die vollständige ID 3I2C21XS1ZXDAP9P/33825. Da YNAB die abgeschnittene Version zurückgab, fand das Mapping nie einen Match.

Warum dieser Code überhaupt existierte

Ich habe im Git-Log nachgeschaut. Der Split('/') Code war ein Überbleibsel aus einer früheren Version, als Import-IDs ein anderes Format hatten. Jemand (wahrscheinlich ich selbst) hatte angenommen, dass / ein Format-Trennzeichen war, das sicher entfernt werden konnte.

Lesson Learned: Wenn du Code kopierst oder anpasst, verstehe WARUM er so geschrieben wurde. Ein Split('/') sieht harmlos aus, kann aber katastrophale Auswirkungen haben, wenn deine IDs dieses Zeichen enthalten.

Der Fix

Die Lösung war simpel – das fehlerhafte Split entfernen:

// NEUE VERSION
// Don't split on '/' - Comdirect IDs contain slashes as part of the ID!
let cleanId = txIdPart

Und natürlich habe ich Regression-Tests hinzugefügt:

testCase "handles Comdirect IDs with slashes" <| fun () ->
    let txId = TransactionId "3I2C21XS1ZXDAP9P/33825"
    let importId = generateImportId txId

    Expect.isTrue (matchesImportId txId importId) "Should match Comdirect ID with slash"

testCase "Comdirect IDs with slashes round-trip correctly" <| fun () ->
    let txId = TransactionId "ABC123DEF/99999"
    let importId = generateImportId txId

    // Simulate what YNAB returns - should still match
    Expect.isTrue (matchesImportId txId importId) "Round-trip should work"

Änderungen:

• src/Server/Api.fs – Fehlerhaften Split('/') entfernt
• src/Tests/DuplicateDetectionTests.fs – 2 neue Regression-Tests für Comdirect IDs

Build: Erfolgreich Tests: 377/377 bestanden (+2 neue Regression-Tests)

Die Meta-Lesson

Dieser Follow-up Bug zeigt ein wichtiges Muster:

Ein Bug kommt selten allein.

Wenn du einen Bug findest, der sich lange versteckt hat, prüfe die umgebenden Code-Pfade. Oft gibt es verwandte Bugs, die aus derselben falschen Annahme entstanden sind.

In diesem Fall:

1. Bug 1: Format-Mismatch zwischen BB: und BUDGETBUDDY:
2. Bug 2: Slash-Parsing zerstört Comdirect IDs

Beide Bugs hatten dieselbe Root Cause: Code, der Annahmen über das ID-Format machte, ohne diese Annahmen explizit zu dokumentieren oder zentral zu definieren.

Der Bug existierte wahrscheinlich seit der ersten Implementation des Duplikat-Checks. Er wurde nie gefunden, weil:

1. Der normale Import-Flow trotzdem funktionierte (andere Heuristiken)
2. Die Tests “grün” waren
3. Force Import relativ selten verwendet wurde

Das ist das Heimtückische an solchen Bugs: sie verstecken sich in Edge Cases und zeigen sich erst, wenn mehrere ungünstige Umstände zusammenkommen.

Key Takeaways für Neulinge

1. Wenn zwei Code-Teile dasselbe Format verwenden, definiere es genau einmal. Nicht “die verwenden beide dasselbe Format” – sondern “die verwenden beide DIESE Konstante/Funktion”. Das ist ein fundamentaler Unterschied.

2. Tautologische Tests erkennen: Wenn dein Test und dein Produktionscode beide ein Format/eine Logik hardcoden, ist der Test wertlos. Der Test muss eine unabhängige Quelle der Wahrheit haben.

3. “Defensiv programmieren” heißt nicht “alle Fehler verstecken”. Ehrliches Scheitern mit gutem Logging ist fast immer besser als stilles Fehlverhalten.

4. Ein Bug kommt selten allein. Wenn du einen lange versteckten Bug findest, prüfe verwandte Code-Pfade. Oft gibt es weitere Bugs mit derselben Root Cause.

5. Verstehe den Code, bevor du ihn änderst. Ein harmlos aussehender Split('/') kann katastrophale Auswirkungen haben, wenn deine Daten dieses Zeichen enthalten. Frage dich immer: “Warum wurde das so geschrieben?”

In den letzten Tagen habe ich drei zusammenhängende Themen bearbeitet, die alle mit dem Betrieb von BudgetBuddy in Docker zu tun haben: Ein kritischer Bug, bei dem verschlüsselte Einstellungen nach jedem Container-Rebuild verloren gingen, ein Automatisierungsskript für Rule-Deployments, und ein neues Feature zum Testen der Comdirect-Verbindung. Diese scheinbar unterschiedlichen Aufgaben haben eine gemeinsame Eigenschaft: Sie alle betreffen die Schnittstelle zwischen Entwicklung und Produktion.

Ausgangslage

BudgetBuddy läuft als Docker-Container mit Tailscale-Integration für sicheren Remote-Zugriff. Die Architektur sieht so aus:

services:
  budgetbuddy-app:
    volumes:
      - ${HOME}/my_apps/budgetbuddy:/app/data  # Persistente Daten
    environment:
      - DATA_DIR=/app/data

  tailscale-budgetbuddy:
    network_mode: "service:budgetbuddy-app"
    command: tailscale serve --https=443 http://127.0.0.1:5001

Die App speichert sensible Daten (YNAB-Token, Comdirect-Credentials) verschlüsselt in einer SQLite-Datenbank. Das Volume /app/data enthält diese Datenbank und überlebt Container-Rebuilds.

Das Problem: Nach jedem docker-compose up -d --build waren alle Einstellungen “weg” – die Datenbank war noch da, aber die verschlüsselten Werte konnten nicht mehr entschlüsselt werden.

Herausforderung 1: Der Encryption-Key-Bug

Das Problem

Die Verschlüsselung in Persistence.fs verwendete einen Key, der aus Environment.MachineName abgeleitet wurde:

let private getEncryptionKey () =
    let machineKey = Environment.MachineName + "BudgetBuddy2025"
    use sha = SHA256.Create()
    sha.ComputeHash(Encoding.UTF8.GetBytes(machineKey))

Auf meinem Mac heißt die Maschine Sachses-MacBook-Pro. Der daraus abgeleitete Key ist deterministisch – solange der Hostname gleich bleibt.

Das Problem: In Docker erhält jeder Container einen zufälligen Hostnamen wie a1b2c3d4e5f6. Bei jedem Rebuild ändert sich dieser Name, und damit auch der Encryption Key.

# Container 1 (erste Woche)
MachineName: "a1b2c3d4e5f6"
Key: sha256("a1b2c3d4e5f6BudgetBuddy2025") = 0xAB12...

# Container 2 (nach Rebuild)
MachineName: "f6e5d4c3b2a1"  # Neuer Container = neuer Hostname!
Key: sha256("f6e5d4c3b2a1BudgetBuddy2025") = 0xCD34...  # Anderer Key!

Wenn Container 2 versucht, die von Container 1 verschlüsselten Daten zu lesen, scheitert die Entschlüsselung – die Daten sind “korrupt” (eigentlich: mit dem falschen Key verschlüsselt).

Optionen, die ich betrachtet habe

Option 1: hostname in docker-compose.yml festlegen

services:
  budgetbuddy-app:
    hostname: budgetbuddy-fixed

Pro:

• Einfach, eine Zeile Änderung
• Keine Code-Änderung nötig

Contra:

• Security through obscurity – der Key ist immer noch trivial ableitbar
• Jeder, der den Code liest, kann den Key berechnen
• Nicht dokumentiert, warum hostname wichtig ist

Option 2: Key als Environment Variable (gewählt)

environment:
  - BUDGETBUDDY_ENCRYPTION_KEY=${BUDGETBUDDY_ENCRYPTION_KEY}

Pro:

• Echter zufälliger Key: openssl rand -base64 32
• Key ist geheim und kann gesichert werden
• Explizit und dokumentiert

Contra:

• Erfordert .env Datei mit dem Key
• Bestehende Daten müssen neu eingegeben werden (einmalig)

Option 3: Key aus einer Datei lesen

let keyFile = Path.Combine(dataDir, ".encryption-key")
if File.Exists(keyFile) then
    File.ReadAllBytes(keyFile)
else
    let newKey = RandomNumberGenerator.GetBytes(32)
    File.WriteAllBytes(keyFile, newKey)
    newKey

Pro:

• Automatisch – kein manueller Schritt
• Key überlebt im Volume

Contra:

• Key-Datei liegt neben der Datenbank – wenn jemand die DB stiehlt, hat er auch den Key
• Backup-Komplexität steigt
• Ich müsste sicherstellen, dass die Datei die richtigen Permissions hat

Die Lösung

Ich habe mich für Option 2 entschieden und getEncryptionKey angepasst:

let private getEncryptionKey () =
    let keyEnv = Environment.GetEnvironmentVariable("BUDGETBUDDY_ENCRYPTION_KEY")
    if String.IsNullOrWhiteSpace(keyEnv) then
        // Fallback: derive from machine name (for local development)
        let machineKey = Environment.MachineName + "BudgetBuddy2025"
        use sha = SHA256.Create()
        sha.ComputeHash(Encoding.UTF8.GetBytes(machineKey))
    else
        Convert.FromBase64String(keyEnv)

Warum der Fallback?

Für lokale Entwicklung ist die MachineName-Variante völlig ausreichend. Der Hostname meines Macs ändert sich nicht. Nur in Docker muss der Key explizit gesetzt werden.

Setup für Docker:

# Einmalig: Key generieren
openssl rand -base64 32 >> .env
# Editieren: BUDGETBUDDY_ENCRYPTION_KEY=<generierter-wert>

# docker-compose.yml liest automatisch .env

Wichtiger Hinweis: Nach dieser Änderung sind alle bestehenden verschlüsselten Daten verloren. Der Benutzer muss YNAB-Token und Comdirect-Credentials neu eingeben. Das ist ein einmaliger Aufwand, aber es vermeidet das wiederkehrende Problem bei jedem Rebuild.

Herausforderung 2: Rule-Deployment-Script

Das Problem

BudgetBuddy hat Kategorisierungsregeln, die in rules.yml definiert sind. Um diese in die Live-Datenbank zu importieren, musste ich bisher:

1. Docker-Container stoppen
2. DATA_DIR Environment Variable setzen
3. dotnet fsi scripts/import-rules.fsx "Budget Name" ausführen
4. Container wieder starten
5. Auf Healthcheck warten

Das sind 5 manuelle Schritte, bei denen man leicht etwas vergessen kann (besonders Schritt 2 – ohne DATA_DIR schreibt das Script in die lokale Dev-Datenbank!).

Die Lösung: deploy-rules.sh

Ich habe ein Bash-Script erstellt, das alle Schritte automatisiert:

#!/bin/bash
# deploy-rules.sh - Import rules from rules.yml to the live Docker database

set -e  # Abbruch bei Fehler

CONTAINER_NAME="budgetbuddy-app"
DATA_DIR="${HOME}/my_apps/budgetbuddy"

# Prerequisite-Checks
check_prerequisites() {
    if [[ ! -f "$PROJECT_DIR/.env" ]]; then
        log_error ".env file not found"
        exit 1
    fi
    if [[ ! -d "$DATA_DIR" ]]; then
        log_error "Data directory not found: $DATA_DIR"
        exit 1
    fi
    # ... weitere Checks
}

# Container-Management
stop_app() {
    if is_container_running; then
        log_info "Stopping $CONTAINER_NAME..."
        docker-compose stop "$CONTAINER_NAME"
    fi
}

start_app() {
    log_info "Starting $CONTAINER_NAME..."
    docker-compose start "$CONTAINER_NAME"

    # Auf Healthcheck warten
    for i in {1..30}; do
        if docker ps | grep "$CONTAINER_NAME" | grep -q "healthy"; then
            log_info "App is healthy!"
            return 0
        fi
        sleep 1
    done
}

# Import mit korrektem DATA_DIR
run_import() {
    DATA_DIR="$DATA_DIR" dotnet fsi scripts/import-rules.fsx "$@"
}

# Hauptlogik
main() {
    check_prerequisites
    stop_app
    run_import "$budget" "$clear_flag" && start_app
}

Architekturentscheidung: Warum Bash statt F#?

1. Unix-Philosophie: Container-Management ist Shell-Arbeit
2. Keine Build-Abhängigkeit: Das Script braucht kein dotnet build
3. Komposition: Es ruft das existierende import-rules.fsx auf, ohne es zu duplizieren
4. Portabilität: Bash läuft überall, wo Docker läuft

Features:

# Nur neue Regeln hinzufügen
./scripts/deploy-rules.sh "My Budget"

# Alle Regeln löschen und neu importieren
./scripts/deploy-rules.sh "My Budget" --clear

# Verfügbare Budgets anzeigen
./scripts/deploy-rules.sh --list

Safety-Feature: Das Script merkt sich, ob der Container vorher lief. Wenn er nicht lief, wird er auch nicht gestartet – man kann das Script zum Testen auch offline nutzen.

local was_running=false
if is_container_running; then
    was_running=true
fi

# ... Import ...

if $was_running; then
    start_app
else
    log_warn "Container was not running before, not starting it"
fi

Herausforderung 3: Comdirect Connection Test

Das Problem

Benutzer konnten ihre Comdirect-Credentials in den Settings speichern, aber erst beim nächsten Sync erfahren, ob sie korrekt sind. Bei falschen Credentials scheitert der Sync mit einer kryptischen Fehlermeldung.

Ursprünglich wollte ich einen “Account Discovery”-Endpunkt implementieren: Der Benutzer gibt Client ID, Secret, Username und PIN ein, und BudgetBuddy zeigt ihm seine Konten zur Auswahl.

Die Realität: Nach stundenlanger Recherche und Tests stellte sich heraus, dass Comdirect keinen öffentlichen /api/banking/v1/accounts Endpunkt hat. Alle Varianten returnen 404:

• GET /api/banking/v1/accounts → 404
• GET /api/banking/v2/accounts → 404
• GET /api/banking/accounts → 404

Die pragmatische Lösung

Statt Account Discovery implementiere ich nur einen Connection Test: Der volle OAuth + TAN Flow wird durchlaufen, aber statt Accounts abzufragen, bestätigen wir nur, dass die Credentials korrekt sind.

API-Design:

type SettingsApi = {
    /// Initiates Comdirect TAN authentication to test connection.
    /// Returns: Challenge ID for TAN confirmation or SettingsError.
    testComdirectConnection: unit -> Async<SettingsResult<string>>

    /// Confirms TAN to complete credential validation.
    /// Returns: Unit on success or SettingsError.
    confirmComdirectTan: unit -> Async<SettingsResult<unit>>
}

UX-Flow:

1. Benutzer speichert Comdirect-Credentials
2. “Test Connection” Button erscheint (nur wenn Credentials gespeichert)
3. Klick → Push-TAN wird angefordert → Orange “Waiting” UI
4. Benutzer bestätigt TAN in der Comdirect-App
5. Klick auf “I’ve Confirmed” → Validierung
6. Grüne Erfolgsmeldung oder rote Fehlermeldung

Frontend Model:

type Model = {
    // ... andere Felder ...
    ComdirectConnectionValid: bool option  // None = nicht getestet, Some true = valid, Some false = invalid
    ComdirectAuthPending: bool  // true = warte auf TAN-Bestätigung
}

State-Übergänge:

Initial: ComdirectConnectionValid = None, ComdirectAuthPending = false

TestConnection clicked:
  → ComdirectAuthPending = true
  → API: testComdirectConnection()
  → Bei Fehler: ComdirectConnectionValid = Some false

ConfirmTan clicked:
  → API: confirmComdirectTan()
  → Bei Erfolg: ComdirectConnectionValid = Some true, ComdirectAuthPending = false
  → Bei Fehler: ComdirectConnectionValid = Some false, ComdirectAuthPending = false

Warum zwei API-Calls statt einem?

Das Comdirect OAuth + TAN System ist asynchron:

1. testComdirectConnection startet den Flow und gibt sofort zurück
2. Der Benutzer bestätigt die TAN in der Banking-App (außerhalb unserer Kontrolle)
3. confirmComdirectTan fragt bei Comdirect nach, ob die TAN bestätigt wurde

Ein synchroner Call würde bedeuten, dass der Server auf die TAN-Bestätigung warten müsste – das können Minuten dauern, wenn der Benutzer sein Handy erst suchen muss.

Code im Backend

// In Api.fs
testComdirectConnection = fun () -> async {
    match! Persistence.loadSettings() with
    | None ->
        return Error (SettingsError.ValidationFailed "Settings not found")
    | Some settings ->
        match settings.Comdirect with
        | None ->
            return Error (SettingsError.ValidationFailed "Comdirect not configured")
        | Some creds ->
            match! ComdirectAuthSession.startAuth creds with
            | Error err ->
                return Error (SettingsError.ComdirectError err)
            | Ok challengeId ->
                return Ok challengeId
}

confirmComdirectTan = fun () -> async {
    match! ComdirectAuthSession.confirmTan() with
    | Error err ->
        return Error (SettingsError.ComdirectError err)
    | Ok () ->
        return Ok ()
}

Account-ID bleibt manuell: Da wir keine Accounts auslesen können, muss der Benutzer seine Account-ID selbst eingeben. Er findet sie im Comdirect Online-Banking unter Kontodetails.

Lessons Learned

1. Environment-abhängige Konfiguration gehört in Environment Variables

Der MachineName-Bug hätte nie passieren dürfen. Die Regel ist einfach: Alles, was sich zwischen Umgebungen unterscheiden kann (Dev/Prod, lokal/Docker), gehört in Environment Variables.

// Schlecht: Implizite Annahme über die Umgebung
let key = deriveFromMachineName()

// Gut: Explizite Konfiguration
let key = Environment.GetEnvironmentVariable("KEY") |> Option.ofObj |> Option.defaultWith fallback

2. Shell-Scripts für Container-Operations

Ich hätte versuchen können, das Rule-Import-Script in F# zu schreiben, inklusive Docker-Management über die Docker-API. Aber Bash ist das richtige Tool für diesen Job:

• docker-compose stop/start sind Ein-Zeiler
• Health-Check-Polling ist trivial mit einer Shell-Schleife
• Das Script ist lesbar für jeden, der Docker kennt

3. MVP statt Overengineering

Der ursprüngliche Plan für Account Discovery war ambitioniert. Die Realität (404 bei allen Endpunkten) hat mich zu einer einfacheren Lösung gezwungen. Das Ergebnis ist besser:

• Connection Test validiert Credentials → Hauptproblem gelöst
• Account-ID als manuelles Feld → Kein Code für nicht-existierende APIs
• Weniger Code = weniger Bugs

Fazit

Drei Änderungen, ein Thema: Production-Readiness. Der Encryption-Bug hätte im echten Betrieb zu Datenverlust geführt. Das Deploy-Script macht Updates sicherer und wiederholbar. Der Connection Test gibt Benutzern Feedback, bevor sie einen Sync starten.

Geänderte Dateien:

Statistiken:

• Encryption-Bug: 8 Zeilen Code-Änderung, verhindert wiederkehrenden Datenverlust
• Deploy-Script: 206 Zeilen Bash, ersetzt 5 manuelle Schritte
• Connection Test: ~100 Zeilen F# (Frontend + Backend), neues Feature

Key Takeaways für Neulinge

1. Container-Hostnames sind nicht stabil: Leite niemals kryptographische Keys aus Container-Metadaten ab. Verwende explizite Environment Variables für alles, was persistent sein muss.

2. Shell-Scripts für DevOps: Für Container-Management, Deployment-Automatisierung und ähnliche Aufgaben ist Bash oft besser geeignet als die Hauptsprache des Projekts. Es ist die Lingua Franca der Ops-Welt.

3. API-Realität akzeptieren: Nicht jede API bietet die Endpunkte, die du dir wünschst. Statt Workarounds zu bauen, überlege, ob ein einfacheres Feature (Connection Test statt Account Discovery) das eigentliche Problem genauso gut löst.

Heute habe ich zwei zusammenhängende UX-Verbesserungen an BudgetBuddy vorgenommen: Ein durchgängiges Formular-Validierungs-System und ein radikal vereinfachtes Dashboard. Beide Änderungen verfolgen dasselbe Ziel – dem Benutzer genau die Information zu geben, die er braucht, und nichts mehr.

Ausgangslage

BudgetBuddy hatte zwei UX-Probleme, die auf den ersten Blick unabhängig voneinander aussahen:

Problem 1: Unsichtbare Formularvalidierung

Wenn ein Benutzer auf einen “Speichern”-Button klickte, der deaktiviert war, passierte… nichts. Der Button sah fast genauso aus wie ein aktiver Button (nur minimal ausgegraut), und es gab keinerlei Feedback darüber, warum der Button nicht funktionierte. War etwas kaputt? Fehlte ein Feld? Welches Feld?

Problem 2: Dashboard-Überladung

Das Dashboard zeigte drei Statistik-Karten (“Letzter Sync”, “Total Importiert”, “Sync Sessions”) und eine Historie der letzten fünf Syncs. Das klingt nach nützlichen Informationen – war es aber nicht. Keine dieser Zahlen war anklickbar oder führte irgendwohin. “42 Transaktionen importiert” ist eine Zahl ohne Kontext. Die Historie konnte man nicht anklicken, um Details zu sehen.

Benutzer-Feedback war eindeutig: “Ich schaue mir das Dashboard nie an. Ich klicke direkt auf ‘Sync starten’.”

Herausforderung 1: Validierungsfeedback ohne Redundanz

Das Problem

Ein typisches Formular in BudgetBuddy (z.B. die Comdirect-Einstellungen) hat mehrere Pflichtfelder:

• Client ID
• Client Secret
• Benutzerkennung
• PIN
• Account-ID

Wenn eines fehlt, sollte der Speichern-Button deaktiviert sein. Aber welches fehlt?

Die naive Lösung wäre, unter jedem Feld eine Fehlermeldung anzuzeigen (“Dieses Feld ist erforderlich”). Das führt aber zu visueller Überfrachtung – fünf rote Fehlermeldungen sehen aus wie ein Katastrophen-Bildschirm.

Optionen, die ich betrachtet habe

Option 1: Fehlermeldung pro Feld

// Jedes Feld zeigt seinen eigenen Fehler
Input.group {
    Label = "Client ID"
    Error = if String.IsNullOrEmpty model.ClientId then Some "Erforderlich" else None
    ...
}

Pro:

• Direkte Zuordnung von Fehler zu Feld
• Bekanntes Pattern aus Web-Formularen

Contra:

• Bei 5 leeren Feldern = 5 Fehlermeldungen = visuelles Chaos
• Benutzer wird erschlagen, bevor er überhaupt angefangen hat
• Redundant: Der Benutzer sieht, dass das Feld leer ist

Option 2: Toast-Benachrichtigung beim Klick

// Beim Klick auf deaktivierten Button erscheint Toast
| SaveClicked when not isValid ->
    model, Cmd.none, ShowToast "Bitte füllen Sie alle Pflichtfelder aus"

Pro:

• Keine permanente visuelle Störung
• Klares Signal, dass etwas fehlt

Contra:

• Sagt nicht, welche Felder fehlen
• Button ist deaktiviert, also kommt der Klick nicht an
• Toast verschwindet, Information ist weg

Option 3: Zusammengefasste Meldung unter dem Button (gewählt)

// Eine Meldung listet alle fehlenden Felder auf
Html.div [
    prop.text $"Bitte ausfüllen: {missingFields}"
]

Pro:

• Eine zentrale Stelle für Validierungsfeedback
• Listet konkret die fehlenden Felder auf
• Verschwindet automatisch, wenn alles ausgefüllt ist
• Fokussiert auf den Ort, wo der Benutzer hinschauen will (den Button)

Contra:

• Benutzer muss zum Button scrollen, um den Fehler zu sehen
• Bei sehr vielen Feldern wird die Liste lang

Ich habe mich für Option 3 entschieden, weil BudgetBuddy-Formulare selten mehr als 5-6 Pflichtfelder haben und der Button typischerweise sichtbar ist.

Die Lösung: Form.fs Design System Component

Ich habe ein neues Modul Form.fs im Design System erstellt:

module Client.DesignSystem.Form

open Feliz
open Client.DesignSystem.Button
open Client.DesignSystem.Icons
open Client.DesignSystem.Loading

// Prüft, ob ein Wert als "ausgefüllt" gilt
let private isRequiredValid (value: string) =
    not (System.String.IsNullOrWhiteSpace value)

// Gibt die Namen aller fehlenden Felder zurück
let private getMissingFields (fields: (string * string) list) =
    fields
    |> List.filter (fun (_, value) -> not (isRequiredValid value))
    |> List.map fst

let submitButton (text: string) (onClick: unit -> unit) (isLoading: bool) (requiredFields: (string * string) list) =
    let missingFields = getMissingFields requiredFields
    let isDisabled = isLoading || not (List.isEmpty missingFields)

    Html.div [
        prop.className "space-y-2"
        prop.children [
            Button.view {
                Button.defaultProps with
                    Text = text
                    OnClick = onClick
                    Variant = Button.Primary
                    IsLoading = isLoading
                    IsDisabled = isDisabled
                    Icon = Some (Icons.check SM Icons.Primary)
            }

            // Validierungsmeldung nur wenn deaktiviert UND Felder fehlen
            if isDisabled && not isLoading && not (List.isEmpty missingFields) then
                Html.div [
                    prop.className "flex items-center gap-2 text-sm text-neon-orange"
                    prop.children [
                        Icons.warning SM NeonOrange
                        Html.span [
                            let fields = String.concat ", " missingFields
                            prop.text $"Bitte ausfüllen: {fields}"
                        ]
                    ]
                ]
        ]
    ]

Architekturentscheidung: Warum eine separate Komponente?

1. Konsistenz: Alle Formulare in der App verwenden jetzt dasselbe Pattern
2. Deklarativ: Der Aufrufer übergibt nur eine Liste von (Feldname, Wert) – die Logik steckt in der Komponente
3. Testbar: Die Validierungslogik ist pure und leicht zu testen
4. Erweiterbar: Später können wir weitere Validierungsregeln hinzufügen (Min-Länge, Pattern, etc.)

Button-Styling für Disabled-State

Ein weiteres Problem war, dass deaktivierte Buttons kaum von aktiven zu unterscheiden waren. Ich habe in Button.fs den disabled-State angepasst:

// Vorher: Nur cursor-not-allowed
"disabled:cursor-not-allowed"

// Nachher: Deutlich sichtbar deaktiviert
"disabled:opacity-50 disabled:cursor-not-allowed disabled:shadow-none"

Die opacity-50 macht den Button halbtransparent, und shadow-none entfernt den charakteristischen Neon-Glow-Effekt. Jetzt ist sofort erkennbar, dass der Button nicht klickbar ist.

Required-Marker konsistent machen

Das letzte Puzzleteil war, alle Pflichtfelder mit einem roten Sternchen zu markieren. Das Input.group-Pattern hatte bereits Required: bool, aber es wurde nicht überall genutzt. Ich habe eine Convenience-Funktion hinzugefügt:

let groupRequired label children =
    group {
        Label = label
        Required = true
        Error = None
        HelpText = None
        Children = children
    }

Das Label-Rendering zeigt jetzt automatisch das Sternchen:

Html.label [
    prop.children [
        Html.text props.Label
        if props.Required then
            Html.span [
                prop.className "text-neon-red ml-0.5"
                prop.text "*"
            ]
    ]
]

Herausforderung 2: Das Dashboard-Dilemma

Das Problem

Das Dashboard war ein klassischer Fall von “Feature Creep”. Beim initialen Design dachte ich: “Ein Dashboard sollte Statistiken zeigen!” Also habe ich hinzugefügt:

• Letzter Sync: Datum und Uhrzeit des letzten Syncs
• Total Importiert: Gesamtzahl aller jemals importierten Transaktionen
• Sync Sessions: Anzahl der durchgeführten Syncs
• Quick Actions: Buttons für häufige Aktionen
• Recent Activity: Die letzten 5 Sync-Sessions mit Zeitstempel

Das Problem: Keine dieser Informationen half dem Benutzer, irgendetwas zu tun. “23 Sync Sessions” – und dann? Was macht der Benutzer mit dieser Information?

Die radikale Lösung: Alles löschen

Ich habe das gesamte Dashboard auf einen einzigen Button reduziert: “Start Sync”.

Vorher:

+------------------+------------------+------------------+
| Letzter Sync     | Total Importiert | Sync Sessions    |
| 15.12.25 18:30   | 1,234            | 23               |
+------------------+------------------+------------------+
| Quick Actions                                          |
| [Start Sync] [Rules] [Settings]                        |
+------------------+------------------+------------------+
| Recent Activity                                        |
| - 15.12.25 18:30: 12 Transaktionen                    |
| - 14.12.25 09:15: 8 Transaktionen                     |
| - 13.12.25 20:00: 15 Transaktionen                    |
| ...                                                    |
+--------------------------------------------------------+

Nachher:

            [  Start Sync  ]

      Letzter Sync: 15.12.25 18:30
         12 Transaktionen

Warum das besser ist

1. Eine Aktion, eine Frage

Wenn ein Benutzer BudgetBuddy öffnet, will er genau eine Sache: Transaktionen synchronisieren. Das Dashboard beantwortet jetzt nur noch zwei Fragen:

• “Was kann ich hier tun?” → Den großen Button drücken
• “Wann habe ich das zuletzt gemacht?” → Die Info unter dem Button

2. Kognitive Last reduziert

Das alte Dashboard hatte ~15 visuelle Elemente (3 Karten × 4 Elemente + 5 History-Items). Das neue hat 3: Button, Datum, Summary. Der Benutzer muss nicht mehr filtern, was wichtig ist.

3. Mobile-First

Auf einem Handy war das alte Dashboard ein Alptraum – scrollen, um den “Start Sync” Button zu finden. Jetzt ist er das Erste, was man sieht.

Implementierung: Drastisch vereinfachte Types

Die Dashboard-Types wurden entsprechend verschlankt:

// Vorher
type Model = {
    CurrentSession: RemoteData<SyncSession option>
    RecentSessions: RemoteData<SyncSession list>  // Für Historie
    Settings: RemoteData<Settings option>
    Stats: RemoteData<DashboardStats>  // Total Imported, etc.
}

// Nachher
type Model = {
    CurrentSession: RemoteData<SyncSession option>
    LastSession: RemoteData<SyncSession option>  // Nur die letzte!
    Settings: RemoteData<Settings option>
}

Die Messages wurden ebenfalls vereinfacht:

type Msg =
    | LoadCurrentSession
    | CurrentSessionLoaded of Result<SyncSession option, string>
    | LoadLastSession  // Vorher: LoadRecentSessions
    | LastSessionLoaded of Result<SyncSession option, string>  // Vorher: List
    | LoadSettings
    | SettingsLoaded of Result<Settings option, string>

Der Hero-Button

Der große “Start Sync” Button ist ein Custom-Styling, kein Standard-Design-System-Button:

let syncButton (onNavigateToSync: unit -> unit) =
    Html.button [
        prop.className """
            group relative
            px-12 py-5
            rounded-xl
            bg-gradient-to-r from-neon-orange to-neon-orange/80
            text-base-100 font-bold text-lg md:text-xl font-display
            shadow-[0_0_30px_rgba(255,107,44,0.4)]
            hover:shadow-[0_0_50px_rgba(255,107,44,0.6)]
            hover:scale-105
            transition-all duration-300
        """
        prop.onClick (fun _ -> onNavigateToSync())
        prop.children [
            Html.div [
                prop.className "flex items-center gap-3"
                prop.children [
                    Icons.sync Icons.MD Icons.Primary
                    Html.span [ prop.text "Start Sync" ]
                ]
            ]
        ]
    ]

Warum kein Design-System-Button?

Das Frontend Architecture Review hat dies als Verbesserungspotenzial markiert. Technisch korrekt – aber ich habe mich bewusst dagegen entschieden:

1. Einmalige Verwendung: Dieser Button erscheint nur hier. Ein Button.hero-Variant im Design System wäre Over-Engineering.
2. Spezielle Proportionen: px-12 py-5 sind deutlich größer als alle anderen Buttons (normalerweise px-4 py-2)
3. Neon-Glow-Effekt: Der orangefarbene Schatten ist Dashboard-spezifisch und passt nicht zu anderen Kontexten

Falls ich später mehr “Hero”-Buttons brauche, werde ich das Design System erweitern. Bis dahin: YAGNI.

Lessons Learned

1. UX > Features

Es ist verlockend, mehr Features hinzuzufügen. “Ein Dashboard braucht Statistiken!” Aber jedes Feature, das nicht hilft, schadet – weil es Aufmerksamkeit von den Features abzieht, die helfen.

2. Validierungsfeedback gehört zum Action-Button

Die Idee, die Validierungsmeldung unter den Button zu setzen, kam aus der Beobachtung: Wenn ein Benutzer auf einen deaktivierten Button klickt, schaut er auf den Button. Genau dort sollte die Erklärung sein.

3. Konsistenz durch das Design System

Ohne das Design System hätte ich die Required-Marker in jedem Formular einzeln implementieren müssen. Mit dem Design System war es eine Änderung in Input.fs, und alle Formulare profitierten.

4. Weniger ist mehr (aber es braucht Mut)

Das Löschen von funktionierendem Code fühlt sich falsch an. “Das habe ich doch implementiert!” Aber wenn es dem Benutzer nicht hilft, ist es Ballast. Das Dashboard-Redesign hat ~200 Zeilen Code gelöscht und das Produkt besser gemacht.

Fazit

Zwei scheinbar unabhängige UX-Verbesserungen, die dasselbe Prinzip verfolgen: Dem Benutzer genau das zeigen, was er braucht – nicht mehr und nicht weniger.

Geänderte Dateien:

Ergebnis:

• Build: ✅
• Tests: 294/294 bestanden
• Code gelöscht: ~200 Zeilen Dashboard-Komplexität
• Code hinzugefügt: ~50 Zeilen Form-Validierung

Key Takeaways für Neulinge

1. Validierungsfeedback ist kein Afterthought: Plane von Anfang an, wie du dem Benutzer Validierungsfehler zeigst. Eine konsistente Lösung im Design System spart später viel Arbeit.

2. Hinterfrage jeden Datenpunkt: Bevor du eine Statistik anzeigst, frage: “Was macht der Benutzer mit dieser Information?” Wenn die Antwort “nichts” ist, zeige sie nicht an.

3. Design System Components für wiederkehrende Patterns: Sobald du dasselbe Pattern zweimal schreibst, extrahiere es in eine wiederverwendbare Komponente. Das garantiert Konsistenz und macht Änderungen einfach.

Was passiert, wenn man sich ehrlich die eigene Codebasis anschaut und fragt: “Ist das wirklich gut strukturiert?” In diesem Blogpost dokumentiere ich ein umfassendes Frontend-Refactoring von BudgetBuddy – einer F#/Fable-Anwendung mit Elmish-Architektur. Über 8 Milestones habe ich die Codequalität systematisch verbessert, ohne die Funktionalität zu ändern.

Das Ergebnis: 4158 neue Zeilen, 1978 entfernte Zeilen, 25 geänderte Dateien – und eine deutlich wartbarere Codebasis.

Ausgangslage: Eine funktionierende, aber gewachsene Codebasis

BudgetBuddy ist eine persönliche Finanz-App, die Transaktionen von der Comdirect-Bank mit YNAB synchronisiert. Das Frontend ist in F# mit Fable geschrieben und nutzt die Elmish-Architektur (Model-View-Update). Nach mehreren Feature-Iterationen war die Codebasis funktional, aber es hatten sich einige technische Schulden angesammelt:

• SyncFlow/View.fs: Eine 1700+ Zeilen große Datei mit allen UI-Komponenten für den Synchronisations-Flow
• Rules/Types.fs: 10 separate Felder für Form-State statt eines gruppierten Records
• Inline-Styles: Hero-Buttons mit 17 Zeilen Tailwind-Code direkt in den Views
• Inkonsistente Fehleranzeigen: Jede Komponente hatte ihre eigene Error-Darstellung
• Fehlende Utilities: Keine Helper-Funktionen für das häufig verwendete RemoteData-Pattern
• Keine Debouncing-Strategie: Jede Kategorie-Änderung löste sofort einen API-Call aus

Die App funktionierte – aber jede Änderung wurde schwieriger. Zeit für ein systematisches Refactoring.

Der Prozess: Vom Review zum Milestone-Plan

Bevor ich Code anfasste, führte ich ein strukturiertes Frontend Architecture Review durch. Dabei bewertete ich jeden Aspekt der Codebasis:

Elmish MVU Pattern:     9/10 ✓
Feliz Usage:            8/10 ✓
Component Structure:    6/10 ⚠ (SyncFlow zu groß)
State Management:       7/10 ⚠ (Rules Form nicht gruppiert)
Design System:          7/10 ⚠ (Lücken bei Error/PageHeader)
Performance:            7/10 ⚠ (keine Debouncing-Strategie)

Aus diesem Review entstand ein priorisierter Milestone-Plan mit 8 konkreten Verbesserungen. Die Prioritäten basierten auf zwei Faktoren:

1. Wartbarkeits-Impact: Wie sehr blockiert das aktuelle Design zukünftige Änderungen?
2. Risiko: Wie wahrscheinlich sind Bugs durch den aktuellen Zustand?

Herausforderung 1: Die 1700-Zeilen-Datei (Milestone 2)

Das Problem

SyncFlow/View.fs war ein Monolith. Alle UI-Komponenten für den Sync-Flow – Status-Anzeigen, Transaktionsliste, Inline-Regel-Formular, Einzelne Transaktionszeilen – lebten in einer Datei. Das machte Navigation schwierig und erhöhte das Risiko von Merge-Konflikten.

Optionen, die ich betrachtet habe

1. Komponenten in separate Dateien extrahieren (gewählt)

• Pro: Klare Zuständigkeiten, einfache Navigation, unabhängige Bearbeitung
• Contra: Mehr Dateien zu verwalten, Abhängigkeiten müssen klar definiert werden

2. Regions/Comments zur Strukturierung

• Pro: Keine Datei-Änderungen, schnell umgesetzt
• Contra: Löst das eigentliche Problem nicht, nur kosmetisch

3. Alles in einem Modul belassen

• Pro: Kein Refactoring-Aufwand
• Contra: Problem verschärft sich mit jedem Feature

Die Lösung: Vier fokussierte Module

Ich extrahierte logisch zusammengehörige Komponenten in einen neuen Views/-Ordner:

src/Client/Components/SyncFlow/
├── Types.fs          (Model, Msg - unverändert)
├── State.fs          (update function - unverändert)
├── View.fs           (~90 Zeilen - nur noch Komposition)
└── Views/
    ├── StatusViews.fs     (~350 Zeilen)
    ├── InlineRuleForm.fs  (~200 Zeilen)
    ├── TransactionRow.fs  (~450 Zeilen)
    └── TransactionList.fs (~310 Zeilen)

Die Abhängigkeitskette war entscheidend für die Reihenfolge in Client.fsproj:

// StatusViews.fs - keine Abhängigkeiten zu anderen Views
let startSyncView (onStartSync: unit -> unit) = ...
let errorView (error: string) (onRetry: unit -> unit) = ...

// InlineRuleForm.fs - verwendet von TransactionRow
let inlineRuleForm (form: InlineRuleFormState) (dispatch: Msg -> unit) = ...

// TransactionRow.fs - verwendet InlineRuleForm
let transactionRow (tx: SyncTransaction) ... = ...

// TransactionList.fs - verwendet TransactionRow
let transactionListView (model: Model) (dispatch: Msg -> unit) = ...

// View.fs - Hauptkomposition, verwendet alle anderen
let view (model: Model) (dispatch: Msg -> unit) =
    match model.CurrentSession with
    | Success (Some session) ->
        match session.Status with
        | Idle -> StatusViews.startSyncView (fun () -> dispatch StartSync)
        | ReviewingTransactions -> TransactionList.transactionListView model dispatch
        // ...

Architekturentscheidung: Warum separate Module statt Nested Modules?

F# unterstützt Nested Modules, aber ich entschied mich für separate Dateien weil:

1. IDE-Navigation: Jede Datei erscheint in der Sidebar
2. Compilation Order: F# compiliert Dateien in Reihenfolge – bei separaten Dateien ist die Abhängigkeit explizit
3. Git History: Änderungen an TransactionRow.fs verschmutzen nicht die History von StatusViews.fs

Ergebnis: View.fs schrumpfte von 1700+ auf ~90 Zeilen. Die neue Struktur macht klar, wo welche Komponente lebt.

Herausforderung 2: Form State Explosion (Milestone 3)

Das Problem

Das Rules-Model hatte 10 separate Felder für Form-State:

type Model = {
    Rules: RemoteData<Rule list>
    EditingRule: Rule option
    IsNewRule: bool
    RuleFormName: string           // Form-Feld
    RuleFormPattern: string        // Form-Feld
    RuleFormPatternType: PatternType  // Form-Feld
    RuleFormTargetField: TargetField  // Form-Feld
    RuleFormCategoryId: YnabCategoryId option  // Form-Feld
    RuleFormPayeeOverride: string  // Form-Feld
    RuleFormEnabled: bool          // Form-Feld
    RuleFormTestInput: string      // Form-Feld
    RuleFormTestResult: string option  // Form-Feld
    RuleSaving: bool               // Form-Feld
    ConfirmingDeleteRuleId: RuleId option
}

Das Problem: Form-State und Domain-State waren vermischt. Das “RuleForm”-Prefix musste überall wiederholt werden, und das Zurücksetzen des Formulars erforderte 10 separate Zuweisungen.

Die Lösung: Dedizierter Record-Typ mit Helper-Modul

type RuleFormState = {
    Name: string
    Pattern: string
    PatternType: PatternType
    TargetField: TargetField
    CategoryId: YnabCategoryId option
    PayeeOverride: string
    Enabled: bool
    TestInput: string
    TestResult: string option
    IsSaving: bool
}

module RuleFormState =
    let empty = {
        Name = ""
        Pattern = ""
        PatternType = Contains
        TargetField = Combined
        CategoryId = None
        PayeeOverride = ""
        Enabled = true
        TestInput = ""
        TestResult = None
        IsSaving = false
    }

    let fromRule (rule: Rule) = {
        Name = rule.Name
        Pattern = rule.Pattern
        PatternType = rule.PatternType
        TargetField = rule.TargetField
        CategoryId = Some rule.CategoryId
        PayeeOverride = rule.PayeeOverride |> Option.defaultValue ""
        Enabled = rule.Enabled
        TestInput = ""
        TestResult = None
        IsSaving = false
    }

type Model = {
    Rules: RemoteData<Rule list>
    EditingRule: Rule option
    IsNewRule: bool
    Form: RuleFormState  // Alles gebündelt
    ConfirmingDeleteRuleId: RuleId option
}

Warum ein Companion Module?

Das RuleFormState-Modul bietet zwei entscheidende Vorteile:

1. Initialisierung wird deklarativ: ```fsharp // Vorher: 10 Zeilen { model with RuleFormName = “”; RuleFormPattern = “”; RuleFormPatternType = Contains RuleFormTargetField = Combined; RuleFormCategoryId = None; … }

// Nachher: 1 Zeile { model with Form = RuleFormState.empty }

2. **Konvertierung von Domain zu Form ist explizit:**
```fsharp
// Vorher: Verstreuter Code
let name = rule.Name
let pattern = rule.Pattern
// ... 8 weitere Zeilen

// Nachher: Ein Funktionsaufruf
{ model with Form = RuleFormState.fromRule rule }

Refactoring in der View:

// Vorher
Input.text model.RuleFormName (fun v -> dispatch (SetRuleFormName v))

// Nachher
Input.text model.Form.Name (fun v -> dispatch (SetRuleFormName v))

Der model.Form.X-Zugriff macht sofort klar: “Das ist Form-State, nicht Domain-State.”

Herausforderung 3: Inkonsistente Fehleranzeigen (Milestone 4)

Das Problem

Jede Komponente hatte ihre eigene Art, Fehler anzuzeigen:

// In Settings/View.fs
Html.div [
    prop.className "bg-error/10 border border-error/30 rounded-lg p-4"
    prop.children [
        Html.span [ prop.text error ]
    ]
]

// In Rules/View.fs
Html.div [
    prop.className "alert alert-error"
    prop.text error
]

// In SyncFlow/View.fs
Html.div [
    prop.className "card bg-base-200 p-6"
    prop.children [ ... komplexeres Layout ... ]
]

Drei verschiedene Stile für dasselbe Konzept. Keine ARIA-Attribute für Accessibility. Keine einheitliche Retry-Funktionalität.

Die Lösung: ErrorDisplay Design System Komponente

Ich erstellte src/Client/DesignSystem/ErrorDisplay.fs mit mehreren Varianten:

module ErrorDisplay =
    /// Inline error for form validation
    let inline' (message: string) =
        Html.span [
            prop.role "alert"
            prop.className "text-error text-sm"
            prop.text message
        ]

    /// Compact card for inline contexts
    let cardCompact (message: string) (onRetry: (unit -> unit) option) =
        Html.div [
            prop.role "alert"
            prop.className "rounded-xl bg-error/5 border border-error/20 p-4"
            prop.children [
                Html.div [
                    prop.className "flex items-center gap-3"
                    prop.children [
                        Icons.alertCircle Icons.MD Icons.Error
                        Html.span [
                            prop.className "text-sm text-error flex-1"
                            prop.text message
                        ]
                        match onRetry with
                        | Some retry ->
                            Button.ghost "Retry" retry
                        | None -> ()
                    ]
                ]
            ]
        ]

    /// Hero-style error for major operation failures
    let hero (title: string) (message: string) (actionText: string)
             (actionIcon: ReactElement) (onAction: unit -> unit) =
        Html.div [
            prop.role "alert"
            prop.className "text-center py-12 px-6"
            prop.children [
                // Großes Error-Icon mit Glow-Effekt
                Html.div [
                    prop.className "mb-6"
                    prop.children [
                        Html.div [
                            prop.className "inline-flex p-4 rounded-full bg-error/10"
                            prop.children [ Icons.alertCircle Icons.XL Icons.Error ]
                        ]
                    ]
                ]
                Html.h2 [
                    prop.className "text-2xl font-bold text-error mb-2"
                    prop.text title
                ]
                Html.p [
                    prop.className "text-base-content/60 mb-6 max-w-md mx-auto"
                    prop.text message
                ]
                Button.primaryWithIcon actionText actionIcon onAction
            ]
        ]

Design-Entscheidungen:

1. role="alert" auf allen Varianten für Screen-Reader-Unterstützung
2. Neon-Farbpalette (error = neon-red/pink Gradient) für Konsistenz mit dem Design System
3. Optionaler Retry-Button als (unit -> unit) option – nicht jeder Fehler ist retry-fähig
4. Mehrere Größen für verschiedene Kontexte (inline → card → hero → fullPage)

Anwendung in den Views:

// Settings: Einfache Fehlerkarte
| Failure error -> ErrorDisplay.cardCompact error None

// SyncFlow: Hero-Style für kritische Fehler
| Failure error ->
    ErrorDisplay.hero
        "Sync Failed"
        error
        "Try Again"
        (Icons.sync Icons.SM Icons.Primary)
        (fun () -> dispatch StartSync)

Herausforderung 4: Hero-Button Inline-Styles (Milestone 5)

Das Problem

Der Sync-Button auf dem Dashboard hatte 17 Zeilen Inline-Tailwind:

let syncButton (onClick: unit -> unit) =
    Html.button [
        prop.className (String.concat " " [
            "relative px-8 py-4 text-lg font-semibold rounded-xl"
            "bg-gradient-to-r from-neon-orange to-neon-pink"
            "text-white shadow-lg"
            "hover:shadow-neon-orange/50 hover:scale-105"
            "transition-all duration-300 ease-out"
            "before:absolute before:inset-0 before:rounded-xl"
            "before:bg-gradient-to-r before:from-neon-orange before:to-neon-pink"
            "before:blur-xl before:opacity-50 before:-z-10"
        ])
        prop.onClick (fun _ -> onClick())
        prop.children [
            Html.span [
                prop.className "flex items-center gap-3"
                prop.children [
                    Icons.sync Icons.MD Icons.Primary
                    Html.text "Start Sync"
                ]
            ]
        ]
    ]

Dieser Glow-Effekt war nicht wiederverwendbar. Wenn ich einen zweiten Hero-Button brauchte, müsste ich alles kopieren.

Die Lösung: Button.hero Varianten im Design System

Zuerst erweiterte ich Tokens.fs um große Glow-Effekte:

module Glows =
    // Existing small glows...

    // Large glows for hero buttons
    let orangeLg = "shadow-[0_0_30px_rgba(255,140,50,0.4)]"
    let orangeHoverLg = "hover:shadow-[0_0_40px_rgba(255,140,50,0.6)]"
    let tealLg = "shadow-[0_0_30px_rgba(0,245,212,0.4)]"
    let tealHoverLg = "hover:shadow-[0_0_40px_rgba(0,245,212,0.6)]"

Dann fügte ich Button.hero Varianten hinzu:

/// Hero button - large CTA with prominent glow
let hero (text: string) (onClick: unit -> unit) =
    Html.button [
        prop.className (String.concat " " [
            "relative px-8 py-4 text-lg font-semibold rounded-xl"
            "bg-gradient-to-r from-neon-orange to-neon-pink"
            "text-white"
            Tokens.Glows.orangeLg
            Tokens.Glows.orangeHoverLg
            "hover:scale-105 transition-all duration-300"
        ])
        prop.onClick (fun _ -> onClick())
        prop.text text
    ]

/// Hero button with icon before text
let heroWithIcon (text: string) (icon: ReactElement) (onClick: unit -> unit) =
    Html.button [
        prop.className (String.concat " " [
            "relative px-8 py-4 text-lg font-semibold rounded-xl"
            "bg-gradient-to-r from-neon-orange to-neon-pink"
            "text-white flex items-center gap-3"
            Tokens.Glows.orangeLg
            Tokens.Glows.orangeHoverLg
            "hover:scale-105 transition-all duration-300"
        ])
        prop.onClick (fun _ -> onClick())
        prop.children [
            icon
            Html.span [ prop.text text ]
        ]
    ]

Dashboard nach dem Refactoring:

// Vorher: 17 Zeilen
let syncButton (onClick: unit -> unit) = ...

// Nachher: 1 Zeile
Button.heroWithIcon "Start Sync" (Icons.sync Icons.MD Icons.Primary) onNavigateToSync

Herausforderung 5: RemoteData ohne Helper (Milestone 6)

Das Problem

RemoteData<'T> ist ein Discriminated Union für asynchrone Daten:

type RemoteData<'T> =
    | NotAsked
    | Loading
    | Success of 'T
    | Failure of string

Überall im Code gab es explizite Pattern Matches:

// Ist das Loading?
match model.Data with
| Loading -> true
| _ -> false

// Hole den Wert oder Default
match model.Data with
| Success value -> value
| _ -> []

// Transformiere den Wert
match model.Data with
| Success value -> Success (transform value)
| Loading -> Loading
| NotAsked -> NotAsked
| Failure e -> Failure e

Das ist nicht falsch – aber repetitiv und fehleranfällig (man kann leicht einen Case vergessen).

Die Lösung: RemoteData Modul mit 17 Helper-Funktionen

Ich fügte ein RemoteData Modul zu Types.fs hinzu:

[<RequireQualifiedAccess>]
module RemoteData =
    /// Transform the success value
    let map (f: 'a -> 'b) (rd: RemoteData<'a>) : RemoteData<'b> =
        match rd with
        | Success value -> Success (f value)
        | Loading -> Loading
        | NotAsked -> NotAsked
        | Failure e -> Failure e

    /// Chain operations that return RemoteData
    let bind (f: 'a -> RemoteData<'b>) (rd: RemoteData<'a>) : RemoteData<'b> =
        match rd with
        | Success value -> f value
        | Loading -> Loading
        | NotAsked -> NotAsked
        | Failure e -> Failure e

    /// Quick state checks
    let isLoading rd = match rd with Loading -> true | _ -> false
    let isSuccess rd = match rd with Success _ -> true | _ -> false
    let isFailure rd = match rd with Failure _ -> true | _ -> false

    /// Extract value with default
    let withDefault (defaultValue: 'a) (rd: RemoteData<'a>) : 'a =
        match rd with
        | Success value -> value
        | _ -> defaultValue

    /// Convert to Option
    let toOption (rd: RemoteData<'a>) : 'a option =
        match rd with
        | Success value -> Some value
        | _ -> None

    /// Recover from failure
    let recover (value: 'a) (rd: RemoteData<'a>) : RemoteData<'a> =
        match rd with
        | Failure _ -> Success value
        | other -> other

    /// Combine two RemoteData values
    let map2 (f: 'a -> 'b -> 'c) (rd1: RemoteData<'a>) (rd2: RemoteData<'b>) : RemoteData<'c> =
        match rd1, rd2 with
        | Success a, Success b -> Success (f a b)
        | Failure e, _ -> Failure e
        | _, Failure e -> Failure e
        | Loading, _ -> Loading
        | _, Loading -> Loading
        | NotAsked, _ -> NotAsked
        | _, NotAsked -> NotAsked

    // ... weitere Helper (fromResult, fromOption, fold, etc.)

[<RequireQualifiedAccess>] war wichtig:

Ohne das Attribut würde map den eingebauten List.map überlagern. Mit dem Attribut ist der Zugriff explizit:

// Klar und eindeutig
let transformed = RemoteData.map (fun x -> x + 1) model.Data
let hasData = RemoteData.isSuccess model.Data
let items = RemoteData.withDefault [] model.Data

63 Unit Tests für Korrektheit:

testList "RemoteData.map" [
    testCase "maps Success value" <| fun () ->
        let result = RemoteData.map (fun x -> x * 2) (Success 5)
        Expect.equal result (Success 10) "Should double the value"

    testCase "preserves Loading" <| fun () ->
        let result = RemoteData.map (fun x -> x * 2) Loading
        Expect.equal result Loading "Should stay Loading"

    testCase "preserves NotAsked" <| fun () ->
        let result = RemoteData.map (fun x -> x * 2) NotAsked
        Expect.equal result NotAsked "Should stay NotAsked"

    testCase "preserves Failure" <| fun () ->
        let result = RemoteData.map (fun x -> x * 2) (Failure "error")
        Expect.equal result (Failure "error") "Should preserve error"
]

Herausforderung 6: Seitenheader Duplikation (Milestone 7)

Das Problem

Jede Seite hatte ihren eigenen Header-Code:

// Settings/View.fs
Html.div [
    prop.className "flex flex-col md:flex-row md:items-center md:justify-between gap-4 mb-8"
    prop.children [
        Html.div [
            Html.h1 [ prop.className "text-2xl font-bold"; prop.text "Settings" ]
            Html.p [ prop.className "text-base-content/60"; prop.text "Configure..." ]
        ]
        Html.div [ (* action buttons *) ]
    ]
]

// Rules/View.fs - ähnlich, aber mit Gradient-Titel
Html.div [
    prop.className "flex flex-col md:flex-row ..."
    prop.children [
        Html.h1 [
            prop.className "text-2xl font-bold bg-gradient-to-r from-neon-teal to-neon-green bg-clip-text text-transparent"
            prop.text "Categorization Rules"
        ]
        // ...
    ]
]

Leichte Variationen überall. Manche mit Gradient, manche ohne. Manche mit Actions, manche ohne.

Die Lösung: PageHeader Komponente mit TitleStyle

module PageHeader =
    type TitleStyle = Standard | Gradient

    type Props = {
        Title: string
        Subtitle: string option
        Actions: ReactElement list
        TitleStyle: TitleStyle
    }

    let defaultProps = {
        Title = ""
        Subtitle = None
        Actions = []
        TitleStyle = Standard
    }

    let view (props: Props) =
        let titleClass =
            match props.TitleStyle with
            | Standard -> "text-2xl md:text-3xl font-bold text-base-content"
            | Gradient -> "text-2xl md:text-3xl font-bold bg-gradient-to-r from-neon-teal to-neon-green bg-clip-text text-transparent"

        Html.div [
            prop.className "flex flex-col md:flex-row md:items-center md:justify-between gap-4 mb-8 animate-fade-in"
            prop.children [
                Html.div [
                    prop.className "space-y-1"
                    prop.children [
                        Html.h1 [ prop.className titleClass; prop.text props.Title ]
                        match props.Subtitle with
                        | Some subtitle ->
                            Html.p [
                                prop.className "text-base-content/60"
                                prop.text subtitle
                            ]
                        | None -> ()
                    ]
                ]
                if not props.Actions.IsEmpty then
                    Html.div [
                        prop.className "flex flex-wrap items-center gap-2"
                        prop.children props.Actions
                    ]
            ]
        ]

    // Convenience functions
    let simple title = view { defaultProps with Title = title }
    let withSubtitle title subtitle = view { defaultProps with Title = title; Subtitle = Some subtitle }
    let gradient title = view { defaultProps with Title = title; TitleStyle = Gradient }
    let gradientWithActions title subtitle actions =
        view { defaultProps with Title = title; Subtitle = subtitle; Actions = actions; TitleStyle = Gradient }

Anwendung:

// Settings - Standard mit Actions
PageHeader.withActions "Settings" (Some "Configure your connections.") [
    Button.ghost "" (fun () -> dispatch Refresh) // Refresh-Icon
]

// Rules - Gradient mit Actions
PageHeader.gradientWithActions "Categorization Rules" (Some "Automate categorization.") [
    Button.primaryWithIcon "Add Rule" (Icons.plus Icons.SM Icons.Primary) (fun () -> dispatch AddRule)
]

// SyncFlow - Standard mit Actions
PageHeader.withActions "Review Transactions" (Some "Categorize before import.") [
    Button.secondary "Cancel" (fun () -> dispatch CancelSync)
]