Visao Geral da Arquitetura

O nucleo do DevLingo e um sistema inteligente de “consulta em camadas”: comecando com consultas locais rapidas, escalando gradualmente ate o raciocinio por IA. Assim, a maioria das consultas e concluida em milissegundos, e mesmo as consultas complexas nao ultrapassam 2 segundos.

Fluxo Completo de Trabalho

O usuario seleciona texto em qualquer aplicativo
    ↓
[Acionamento] Pressiona o atalho ⌘⇧D
    ↓
[Extracao] TextExtractor captura:
    - O texto selecionado
    - 50 caracteres de contexto antes e depois (para a IA entender o contexto)
    - O bundleIdentifier do aplicativo atual (Xcode / Slack / GitHub etc.)
    ↓
[Classificacao] InputTypeDetector determina o tipo de entrada:
    - Idioma nativo → Modo Express
    - Uma palavra → Modo Word
    - 2-4 palavras sem estrutura de frase → Modo Phrase
    - Frase completa com ate 20 palavras → Modo Sentence
    - Multiplas frases ou >20 palavras → Modo Paragraph
    ↓
[Consulta] LookupCoordinator consulta em camadas (detalhes abaixo)
    ↓
[Renderizacao] FloatingPanelController:
    - Exibe uma janela flutuante NSPanel abaixo do mouse
    - Mostra skeleton screen (animacao de carregamento)
    - Seleciona a subclasse de View correspondente ao modo (WordView / PhraseView / SentenceView etc.)
    - Quando os dados chegam, faz fade-in suave do resultado
    ↓
[Interacao] O usuario pode:
    - Clicar no botao de reproducao para ouvir a pronuncia
    - Clicar em uma palavra para consulta recursiva
    - Salvar no "caderno de vocabulario" (SwiftData)
    - Fechar a janela flutuante e continuar trabalhando

Sistema de Consulta em Camadas

Esta e a chave para o desempenho do DevLingo. Consulta por prioridade, retornando ao encontrar resultado:

Primeira Camada: Banco de Termos Tecnicos Local (<50ms)

Para entradas em ingles, primeiro consulta o banco de dados SQLite local. Contem 85+ termos de desenvolvimento comuns pre-carregados:

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

Taxa de acerto de aproximadamente 30% das consultas de vocabulario de desenvolvimento. Resposta ultrarapida.

Segunda Camada: Banco de Expressoes de Desenvolvimento Local (<100ms)

Para expressoes de 2-4 palavras, consulta o banco de dados local de expressoes (50+ expressoes pre-carregadas):

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

Taxa de acerto de aproximadamente 20% das consultas de expressoes.

Terceira Camada: Cache SwiftData (<10ms)

Vocabulario, expressoes e frases consultados anteriormente pelo usuario ficam em cache no SwiftData local. Se encontrado, retorna diretamente.

Usuario consultou "idempotent" → proxima consulta <10ms

Taxa de acerto de aproximadamente 50% (depende do historico de uso).

Quarta Camada: Claude API (0.5-2s)

Se as tres primeiras camadas nao tiverem resultado, chama a Claude API para obter uma resposta estruturada.

Requisicao: {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "pt-BR"
}

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

:::note Por que o design em camadas

• 95% do vocabulario comum acerta nas tres primeiras camadas, retorno em <100ms
• 5% de vocabulario raro ou novo precisa da Claude API, mas leva apenas 1-2 segundos
• Sem internet ainda e possivel consultar o banco local e o cache
• Economiza cota do usuario A Claude API cobra por uso; as camadas reduzem 95% das chamadas de API :::

Arquitetura do Backend

O backend do DevLingo e implantado nos nos de borda do Cloudflare Workers, processando requisicoes de API.

Aplicativo Mac
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (rotas Hono)
  ├─ Auth Middleware (verificacao JWT)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (proxy de requisicoes de IA)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (proxy de sintese de pronuncia)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (banco de dados do usuario)

Componentes Principais

• Framework Hono: Framework HTTP leve, otimizado para Cloudflare Workers
• Banco de dados D1: SQLite no Cloudflare, armazena o caderno de vocabulario e dados de sincronizacao do usuario
• Armazenamento KV: Tokens de sessao, cache de limitacao de taxa, cache de respostas da API
• Proxy Claude API: O aplicativo Mac faz proxy das requisicoes ao Claude atraves dos Workers, evitando exposicao de chaves de API localmente

Extracao de Texto e Contexto

O TextExtractor usa AXUIElement (API de Acessibilidade do macOS) para obter:

Usuario seleciona no Slack: "idempotent"

Resultado da extracao:
{
  "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."
}

Esse contexto e enviado ao Claude, ajudando a IA a entender: “idempotent aqui esta no contexto de design de API”, e nao em outro sentido.

Algoritmo de Deteccao de Tipo de Entrada

se o texto contem caracteres nao-ingleses:
  → Modo Express
senao se numero_palavras == 1:
  → Modo Word
senao se numero_palavras in [2, 3, 4]:
  se contem estrutura de frase completa:
    → Modo Sentence
  senao:
    → Modo Phrase
senao se numero_frases > 1 ou numero_palavras > 20:
  → Modo Paragraph
senao:
  → Modo Sentence

:::tip Deteccao Inteligente A deteccao de entrada e feita localmente de forma instantanea, sem chamada de API. Garantindo que o usuario nunca perceba atraso na etapa de “determinar o tipo de entrada”. :::

Apresentacao da Janela Flutuante

O FloatingPanelController cria um NSPanel (janela flutuante):

Caracteristicas:
- Exibido acima de todos os aplicativos (Level: screenSaver)
- Posicao: logo abaixo do mouse (y offset +20px, evitando obstrucao)
- Estado inicial: skeleton screen (esqueleto de carregamento)
- Dados recebidos: fade-in, destruicao do skeleton
- Interacao: transparencia total do mouse (nao bloqueia aplicativos em segundo plano)
- Formas de fechar: clicar fora, pressionar ESC, fechar automaticamente apos 5 minutos sem acao

Metas de Desempenho

• Consulta ao banco local: <50ms (percentil 99)
• Acerto de cache: <10ms
• Ponta a ponta completo (com API): <2s (percentil 99)
• Tempo de aparecimento da janela flutuante: <300ms (percepcao rapida do usuario)
• Geracao de audio TTS: primeira vez <2s, cache subsequente <100ms

:::note Estrategia de Cache O audio TTS tambem e armazenado em cache local e no KV; a pronuncia de uma mesma palavra e sintetizada apenas uma vez. :::

Privacidade dos Dados

Texto do usuario
  ↓
Aplicativo Mac (criptografia HTTPS)
  ↓
Cloudflare Edge (processamento instantaneo)
  ├─ Requisicao Claude API (temporaria, nao usada para treinamento)
  └─ Resultado em cache no KV (expiracao automatica)
  ↓
Resultado retornado ao Mac
  ↓
Armazenamento local SwiftData (no dispositivo, sincronizacao com D1 opcional)

O conteudo do texto nao e armazenado, a menos que o usuario salve ativamente no caderno de vocabulario. Veja mais detalhes em Privacidade e Seguranca dos Dados.

A filosofia de design da arquitetura do DevLingo e: “Velocidade em primeiro lugar, IA como suporte, privacidade acima de tudo”.