Vision general del funcionamiento

El nucleo de DevLingo es un sistema inteligente de “consulta por capas”: comienza con una consulta local rapida y escala progresivamente hacia el razonamiento de IA. Asi, la mayoria de las consultas se completan en milisegundos, y las consultas complejas no superan los 2 segundos.

Flujo de trabajo completo

El usuario selecciona texto en cualquier aplicacion
    ↓
[Activacion] Presiona el atajo ⌘⇧D
    ↓
[Extraccion] TextExtractor obtiene:
    • El texto seleccionado
    • 50 caracteres de contexto antes y despues (para que la IA entienda el contexto)
    • El bundleIdentifier de la aplicacion actual (Xcode / Slack / GitHub, etc.)
    ↓
[Clasificacion] InputTypeDetector determina el tipo de entrada:
    • Idioma nativo → modo Express
    • Una palabra → modo Word
    • 2-4 palabras sin estructura oracional → modo Phrase
    • Oracion completa ≤20 palabras → modo Sentence
    • Multiples oraciones o >20 palabras → modo Paragraph
    ↓
[Consulta] LookupCoordinator consulta por capas (detalle abajo)
    ↓
[Renderizado] FloatingPanelController:
    • Muestra un panel flotante NSPanel debajo del cursor
    • Muestra skeleton screen (animacion de carga)
    • Selecciona la subclase de View correspondiente al modo (WordView / PhraseView / SentenceView, etc.)
    • Cuando llegan los datos, se muestran con una transicion suave
    ↓
[Interaccion] El usuario puede:
    • Hacer clic en el boton de reproduccion para escuchar la pronunciacion
    • Hacer clic en una palabra para realizar una consulta recursiva
    • Guardar en el "cuaderno de palabras" (SwiftData)
    • Cerrar el panel flotante y continuar trabajando

Sistema de consulta por capas

Esta es la clave del rendimiento de DevLingo. Se consulta por orden de prioridad, y se devuelve el resultado tan pronto como se encuentra:

Primera capa: Base de datos local de terminos tecnicos (<50ms)

Para entradas en ingles, primero se busca en la base de datos SQLite local. Contiene 85+ terminos de desarrollo comunes precargados:

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

Tasa de acierto de aproximadamente 30% de las consultas de vocabulario de desarrollo. Respuesta ultrarapida.

Segunda capa: Base de datos local de frases de desarrollo (<100ms)

Para frases de 2-4 palabras, se consulta la base de datos local de frases (50+ frases precargadas):

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

Tasa de acierto de aproximadamente 20% de las consultas de frases.

Tercera capa: Cache de SwiftData (<10ms)

Las palabras, frases y oraciones que el usuario ha consultado previamente se almacenan en cache local en SwiftData. Si se encuentra, se devuelve directamente.

El usuario consulto "idempotent" → la proxima consulta <10ms

Tasa de acierto de aproximadamente 50% (depende del historial de uso).

Cuarta capa: Claude API (0.5-2s)

Si las tres capas anteriores no obtienen resultado, se llama a la Claude API para obtener una respuesta estructurada.

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

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

:::note Por que el diseno por capas

95% del vocabulario comun se resuelve en las tres primeras capas, <100ms de respuesta
5% del vocabulario poco comun o nuevo requiere la Claude API, pero solo toma 1-2 segundos
Sin conexion aun puede consultar la base de datos local y el cache
Ahorro de cuota del usuario La Claude API se cobra por uso; el sistema por capas reduce el 95% de las llamadas API :::

Arquitectura del backend

El backend de DevLingo esta desplegado en nodos de borde de Cloudflare Workers, procesando solicitudes API.

Aplicacion Mac
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (enrutamiento Hono)
  ├─ Auth Middleware (verificacion JWT)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (proxy de solicitudes IA)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (proxy de sintesis de pronunciacion)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (base de datos de usuarios)

Componentes clave

Framework Hono: Framework HTTP ligero, optimizado para Cloudflare Workers
Base de datos D1: SQLite en Cloudflare, almacena el cuaderno de palabras y datos de sincronizacion del usuario
Almacenamiento KV: Tokens de sesion, cache de limite de velocidad, cache de respuestas API
Proxy de Claude API: La aplicacion Mac envia solicitudes a Claude a traves del proxy de Workers, evitando exponer claves API localmente

Extraccion de texto y contexto

TextExtractor utiliza AXUIElement (API de accesibilidad de macOS) para obtener:

El usuario selecciona en Slack: "idempotent"

Resultado de extraccion:
{
  "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."
}

Este contexto se envia a Claude para ayudar a la IA a entender: “idempotent aqui se refiere al contexto de diseno de API”, y no a otra cosa.

Algoritmo de deteccion de tipo de entrada

if el texto contiene caracteres del idioma nativo:
  → modo Express
elif numero_palabras == 1:
  → modo Word
elif numero_palabras in [2, 3, 4]:
  if contiene estructura oracional completa:
    → modo Sentence
  else:
    → modo Phrase
elif numero_oraciones > 1 or numero_palabras > 20:
  → modo Paragraph
else:
  → modo Sentence

:::tip Deteccion inteligente La deteccion de entrada se realiza instantaneamente de forma local, sin llamadas API. Garantiza que el usuario nunca perciba un retraso en el paso de “determinar el tipo de entrada”. :::

Presentacion del panel flotante

FloatingPanelController crea un NSPanel (panel flotante):

Caracteristicas:
• Se muestra sobre todas las aplicaciones (Level: screenSaver)
• Posicion: justo debajo del cursor (y offset +20px, para no obstruir)
• Estado inicial: skeleton screen (esqueleto de carga)
• Cuando llegan los datos: transicion suave, se destruye el skeleton
• Interaccion: transparente al raton (no bloquea aplicaciones en segundo plano)
• Formas de cerrar: clic fuera, presionar ESC, cierre automatico tras 5 minutos de inactividad

Objetivos de rendimiento

Consulta de base local: <50ms (percentil 99)
Cache hit: <10ms
Extremo a extremo completo (con API): <2s (percentil 99)
Tiempo de aparicion del panel flotante: <300ms (rapidez percibida por el usuario)
Generacion de audio TTS: primera vez <2s, posteriores con cache <100ms

:::note Estrategia de cache El audio TTS tambien se almacena en cache local y en KV; la pronunciacion de una misma palabra solo se sintetiza una vez. :::

Privacidad de datos

Texto del usuario
  ↓
Aplicacion Mac (cifrado HTTPS)
  ↓
Cloudflare Edge (procesamiento instantaneo)
  ├─ Solicitud a Claude API (temporal, no se usa para entrenamiento)
  └─ Resultado en cache en KV (expiracion automatica)
  ↓
Resultado devuelto a la Mac
  ↓
Almacenamiento local en SwiftData (en el dispositivo, sincronizacion opcional en la nube via D1)

El contenido de texto no se almacena a menos que el usuario lo guarde activamente en el cuaderno de palabras. Consulte Privacidad y seguridad de datos para mas detalles.

La filosofia de diseno de la arquitectura de DevLingo es: “Velocidad primero, IA como apoyo, privacidad ante todo”.