Funktionsweise im Ueberblick

Der Kern von DevLingo ist ein intelligentes “mehrstufiges Abfragesystem”: Beginnend mit schnellen lokalen Abfragen wird schrittweise auf AI-Verarbeitung eskaliert. So werden die meisten Abfragen in Millisekunden beantwortet, und selbst komplexe Abfragen dauern nicht laenger als 2 Sekunden.

Vollstaendiger Arbeitsablauf

Benutzer waehlt Text in einer beliebigen Anwendung aus
    ↓
[Ausloeser] Tastenkombination ⌘⇧D druecken
    ↓
[Extraktion] TextExtractor erfasst:
    • Den ausgewaehlten Text
    • 50 Zeichen Kontext davor und danach (fuer AI-Kontextverstaendnis)
    • Die bundleIdentifier der aktuellen Anwendung (Xcode / Slack / GitHub usw.)
    ↓
[Klassifizierung] InputTypeDetector bestimmt den Eingabetyp:
    • Nicht-englischer Text → Express-Modus
    • Einzelnes Wort → Word-Modus
    • 2-4 Woerter ohne Satzstruktur → Phrase-Modus
    • Vollstaendiger Satz ≤20 Woerter → Sentence-Modus
    • Mehrere Saetze oder >20 Woerter → Paragraph-Modus
    ↓
[Abfrage] LookupCoordinator stufenweise Abfrage (siehe unten)
    ↓
[Darstellung] FloatingPanelController:
    • Zeigt ein NSPanel-Schwebefenster unterhalb des Mauszeigers
    • Zeigt einen Skeleton Screen (Ladeanimation)
    • Waehlt je nach Modus die entsprechende View-Unterklasse (WordView / PhraseView / SentenceView usw.)
    • Blendet die Ergebnisse nach Eintreffen der Daten sanft ein
    ↓
[Interaktion] Der Benutzer kann:
    • Auf die Abspielen-Schaltflaeche klicken, um die Aussprache zu hoeren
    • Auf ein Wort klicken fuer eine rekursive Abfrage
    • Im "Vokabelheft" speichern (SwiftData)
    • Das Schwebefenster schliessen und weiterarbeiten

Mehrstufiges Abfragesystem

Dies ist der Schluessel zur Leistung von DevLingo. Abfragen erfolgen nach Prioritaet; sobald ein Ergebnis gefunden wird, wird es zurueckgegeben:

Stufe 1: Lokale technische Vokabeldatenbank (<50ms)

Fuer englische Eingaben wird zuerst die lokale SQLite-Datenbank abgefragt. Sie enthaelt 85+ gaengige Entwicklungsbegriffe:

idempotent, deployment, microservice, containerization,
latency, throughput, cache invalidation, API gateway,
circuit breaker, distributed tracing, ...

Trefferquote: ca. 30% der Entwickler-Vokabelabfragen. Extrem schnelle Antwort.

Stufe 2: Lokale Entwickler-Phrasendatenbank (<100ms)

Fuer 2-4-Wort-Phrasen wird die lokale Phrasendatenbank abgefragt (50+ vorinstallierte Phrasen):

yak shaving, bikeshedding, rubber ducking, code smell,
low-hanging fruit, technical debt, nerd sniping, ...

Trefferquote: ca. 20% der Phrasenabfragen.

Stufe 3: SwiftData-Cache (<10ms)

Zuvor abgefragte Vokabeln, Phrasen und Saetze werden im lokalen SwiftData-Cache gespeichert. Bei einem Treffer wird direkt zurueckgegeben.

Benutzer hat "idempotent" abgefragt → naechste Abfrage <10ms

Trefferquote: ca. 50% (abhaengig vom Nutzungsverlauf).

Stufe 4: Claude API (0.5-2s)

Wenn die ersten drei Stufen keinen Treffer ergeben, wird die Claude API fuer eine strukturierte Antwort aufgerufen.

Anfrage: {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "de"
}

Antwort: {
  "type": "phrase", // compound verb
  "definition_en": "...",
  "definition_de": "...",
  "examples": [...],
  "pronunciation": {...},
  "register": "technical",
  "l1_tips": "..."
}

:::note Warum ein mehrstufiges Design?

• 95% der gaengigen Vokabeln treffen auf die ersten drei Stufen, <100ms Antwortzeit
• 5% der seltenen oder neuen Vokabeln benoetigen die Claude API, aber auch nur 1-2 Sekunden
• Ohne Netzwerk koennen lokale Datenbank und Cache weiterhin abgefragt werden
• Kontingent sparen: Claude API wird pro Aufruf berechnet; das Stufensystem reduziert 95% der API-Aufrufe :::

Backend-Architektur

Das DevLingo-Backend ist auf Cloudflare Workers Edge-Knoten bereitgestellt und verarbeitet API-Anfragen.

Mac-Anwendung
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (Hono-Routing)
  ├─ Auth Middleware (JWT-Verifizierung)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (Proxy fuer AI-Anfragen)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (Proxy fuer Sprachsynthese)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (Benutzerdatenbank)

Schluesselkomponenten

• Hono-Framework: Leichtgewichtiges HTTP-Framework, optimiert fuer Cloudflare Workers
• D1-Datenbank: SQLite auf Cloudflare, speichert Vokabelheft und Synchronisierungsdaten der Benutzer
• KV-Speicher: Sitzungs-Token, Rate-Limiting-Cache, API-Antwort-Cache
• Claude API-Proxy: Die Mac-Anwendung leitet alle Anfragen an Claude ueber Workers weiter, um API-Schluessel nicht lokal preiszugeben

Textextraktion und Kontext

TextExtractor nutzt AXUIElement (macOS Bedienungshilfen-API) zur Erfassung von:

Benutzer waehlt in Slack aus: "idempotent"

Extraktionsergebnis:
{
  "selectedText": "idempotent",
  "beforeContext": "We need to make sure this endpoint is ",
  "afterContext": " for retry requests.",
  "sourceApp": "com.tinyspeck.slackmacgap",  // Slack
  "fullSentence": "We need to make sure this endpoint is idempotent for retry requests."
}

Dieser Kontext wird an Claude gesendet und hilft der AI zu verstehen: “idempotent bezieht sich hier auf API-Design”, und nicht auf etwas anderes.

Algorithmus zur Eingabetyp-Erkennung

if Text enthaelt nicht-englische Zeichen:
  → Express-Modus
elif Wortanzahl == 1:
  → Word-Modus
elif Wortanzahl in [2, 3, 4]:
  if enthaelt vollstaendige Satzstruktur:
    → Sentence-Modus
  else:
    → Phrase-Modus
elif Satzanzahl > 1 or Wortanzahl > 20:
  → Paragraph-Modus
else:
  → Sentence-Modus

:::tip Intelligente Erkennung Die Eingabeerkennung erfolgt lokal und sofort, ohne API-Aufruf. So spuert der Benutzer keine Verzoegerung durch den Schritt “Eingabetyp bestimmen”. :::

Darstellung im Schwebefenster

FloatingPanelController erstellt ein NSPanel (Schwebefenster):

Eigenschaften:
• Wird ueber allen Anwendungen angezeigt (Level: screenSaver)
• Position: direkt unterhalb des Mauszeigers (y offset +20px, um Verdeckung zu vermeiden)
• Anfangszustand: Skeleton Screen (Ladegeruest)
• Daten eingetroffen: sanftes Einblenden, Skeleton wird entfernt
• Interaktion: vollstaendige Maus-Durchreichung (blockiert keine Hintergrundanwendungen)
• Schliessen: Klick ausserhalb, ESC druecken, automatisches Schliessen nach 5 Minuten Inaktivitaet

Leistungsziele

• Lokale Datenbankabfrage: <50ms (99. Perzentil)
• Cache-Treffer: <10ms
• Vollstaendig End-to-End (mit API): <2s (99. Perzentil)
• Erscheinungszeit des Schwebefensters: <300ms (vom Benutzer als schnell wahrgenommen)
• TTS-Audiogenerierung: Erstmalig <2s, danach aus dem Cache <100ms

:::note Cache-Strategie Auch TTS-Audio wird lokal und in KV zwischengespeichert. Die Aussprache eines Wortes wird nur einmal synthetisiert. :::

Datenschutz

Benutzertext
  ↓
Mac-Anwendung (HTTPS-verschluesselt)
  ↓
Cloudflare Edge (sofortige Verarbeitung)
  ├─ Claude API-Anfrage (temporaer, nicht fuer Training verwendet)
  └─ Ergebnis-Cache in KV (laeuft automatisch ab)
  ↓
Ergebnis zurueck an den Mac
  ↓
Lokaler SwiftData-Speicher (auf dem Geraet, optionale Cloud-Synchronisation zu D1)

Textinhalte werden nicht gespeichert, es sei denn, der Benutzer speichert sie aktiv im Vokabelheft. Weitere Details finden Sie unter Datenschutz und Sicherheit.

Die Architekturphilosophie von DevLingo lautet: “Schnelligkeit zuerst, AI als Ergaenzung, Datenschutz an erster Stelle”.