Vue d'ensemble du fonctionnement

Le coeur de DevLingo repose sur un systeme intelligent de “recherche par niveaux” : en commencant par une recherche locale rapide, puis en escaladant progressivement vers le raisonnement IA. Ainsi, la plupart des recherches s’effectuent en quelques millisecondes, et les recherches complexes ne depassent pas 2 secondes.

Flux de travail complet

L'utilisateur selectionne du texte dans n'importe quelle application
    |
[Declenchement] Appui sur le raccourci ⌘⇧D
    |
[Extraction] TextExtractor recupere :
    - Le texte selectionne
    - 50 caracteres de contexte avant et apres (pour la comprehension IA)
    - Le bundleIdentifier de l'application (Xcode / Slack / GitHub, etc.)
    |
[Classification] InputTypeDetector determine le type d'entree :
    - Langue maternelle -> mode Express
    - Un seul mot -> mode Word
    - 2-4 mots sans structure de phrase -> mode Phrase
    - Phrase complete <= 20 mots -> mode Sentence
    - Plusieurs phrases ou > 20 mots -> mode Paragraph
    |
[Recherche] LookupCoordinator recherche par niveaux (voir ci-dessous)
    |
[Rendu] FloatingPanelController :
    - Affiche un panneau flottant NSPanel sous le curseur
    - Affiche un skeleton screen (animation de chargement)
    - Selectionne la sous-vue correspondant au mode (WordView / PhraseView / SentenceView, etc.)
    - A l'arrivee des donnees, fondu enchaine vers les resultats
    |
[Interaction] L'utilisateur peut :
    - Cliquer sur le bouton de lecture pour ecouter la prononciation
    - Cliquer sur un mot pour une recherche recursive
    - Enregistrer dans le "carnet de vocabulaire" (SwiftData)
    - Fermer le panneau flottant et continuer a travailler

Systeme de recherche par niveaux

C’est la cle des performances de DevLingo. Les niveaux sont interroges par ordre de priorite, et le premier resultat trouve est retourne :

Niveau 1 : Base de donnees locale de termes techniques (<50ms)

Pour les entrees en anglais, la recherche s’effectue d’abord dans la base de donnees SQLite locale. Plus de 85 termes de developpement courants sont pre-integres :

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

Taux de correspondance d’environ 30 % des recherches de vocabulaire technique. Reponse quasi instantanee.

Niveau 2 : Base de donnees locale d’expressions (<100ms)

Pour les expressions de 2 a 4 mots, recherche dans la base d’expressions locale (50+ expressions pre-integrees) :

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

Taux de correspondance d’environ 20 % des recherches d’expressions.

Niveau 3 : Cache SwiftData (<10ms)

Les mots, expressions et phrases precedemment recherches sont mis en cache localement dans SwiftData. S’ils sont trouves, le resultat est retourne directement.

L'utilisateur a deja recherche "idempotent" -> prochaine recherche <10ms

Taux de correspondance d’environ 50 % (selon l’historique d’utilisation).

Niveau 4 : Claude API (0.5-2s)

Si les trois premiers niveaux ne donnent aucun resultat, l’API Claude est appelee pour obtenir une reponse structuree.

Requete : {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "fr-FR"
}

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

:::note Pourquoi une conception par niveaux

• 95 % du vocabulaire courant est trouve dans les trois premiers niveaux, retour en <100ms
• 5 % des mots rares ou nouveaux necessitent l’API Claude, mais seulement 1-2 secondes
• Sans connexion reseau, la base locale et le cache restent accessibles
• Economie de quota utilisateur L’API Claude est facturee a l’utilisation ; la recherche par niveaux reduit 95 % des appels API :::

Architecture backend

Le backend de DevLingo est deploye sur les noeuds edge de Cloudflare Workers pour traiter les requetes API.

Application Mac
  | HTTPS (Bearer token)
Cloudflare Workers (Edge)
  |-- API Gateway (routage Hono)
  |-- Auth Middleware (verification JWT)
  |-- Lookup Endpoint (/api/lookup)
  |   +-- Claude API Client (proxy des requetes IA)
  |-- TTS Endpoint (/api/tts)
  |   +-- Google Cloud TTS (proxy de synthese vocale)
  +-- Data Sync Endpoints
      +-- Cloudflare D1 (base de donnees utilisateur)

Composants cles

• Framework Hono : framework HTTP leger, optimise pour Cloudflare Workers
• Base de donnees D1 : SQLite sur Cloudflare, stocke les carnets de vocabulaire et les donnees de synchronisation
• Stockage KV : jetons de session, limitation de debit, cache de reponses API
• Proxy Claude API : l’application Mac effectue ses requetes a Claude via Workers, evitant d’exposer la cle API localement

Extraction de texte et contexte

TextExtractor utilise AXUIElement (API d’accessibilite macOS) pour obtenir :

L'utilisateur selectionne dans Slack : "idempotent"

Resultat d'extraction :
{
  "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."
}

Ce contexte est envoye a Claude pour l’aider a comprendre : “idempotent ici concerne la conception d’API”, et non autre chose.

Algorithme de detection du type d’entree

si le texte contient la langue maternelle :
  -> mode Express
sinon si nombre de mots == 1 :
  -> mode Word
sinon si nombre de mots in [2, 3, 4] :
  si contient une structure de phrase complete :
    -> mode Sentence
  sinon :
    -> mode Phrase
sinon si nombre de phrases > 1 ou nombre de mots > 20 :
  -> mode Paragraph
sinon :
  -> mode Sentence

:::tip Detection intelligente La detection d’entree s’effectue instantanement en local, sans appel API. L’utilisateur ne percoit jamais le delai lie a la determination du type d’entree. :::

Presentation du panneau flottant

FloatingPanelController cree un NSPanel (panneau flottant) :

Caracteristiques :
- Affiche au-dessus de toutes les applications (Level: screenSaver)
- Position : directement sous le curseur (y offset +20px, pour eviter de masquer le texte)
- Etat initial : skeleton screen (structure de chargement)
- Arrivee des donnees : fondu enchaine, destruction du skeleton
- Interaction : transparence de la souris (ne bloque pas les applications en arriere-plan)
- Fermeture : clic a l'exterieur, touche ESC, fermeture automatique apres 5 minutes d'inactivite

Objectifs de performance

• Recherche dans la base locale : <50ms (99e percentile)
• Cache hit : <10ms
• Bout en bout complet (avec API) : <2s (99e percentile)
• Temps d’apparition du panneau : <300ms (rapidite percue par l’utilisateur)
• Generation audio TTS : premiere fois <2s, cache par la suite <100ms

:::note Strategie de cache L’audio TTS est egalement mis en cache localement et dans KV ; la prononciation d’un meme mot n’est synthetisee qu’une seule fois. :::

Confidentialite des donnees

Texte de l'utilisateur
  |
Application Mac (chiffrement HTTPS)
  |
Cloudflare Edge (traitement immediat)
  |-- Requete API Claude (temporaire, non utilisee pour l'entrainement)
  +-- Cache des resultats dans KV (expiration automatique)
  |
Resultats renvoyes vers le Mac
  |
Stockage local SwiftData (sur l'appareil, synchronisation cloud optionnelle vers D1)

Le contenu textuel n’est pas stocke, sauf si l’utilisateur l’enregistre volontairement dans le carnet de vocabulaire. Voir Confidentialite des donnees et securite pour plus de details.

La philosophie de conception de l’architecture de DevLingo est : “La rapidite d’abord, l’IA en complement, la confidentialite en priorite.”