Gambaran Umum Cara Kerja

Inti dari DevLingo adalah sistem “pencarian berlapis” yang cerdas: dimulai dari pencarian cepat lokal, lalu secara bertahap ditingkatkan ke penalaran AI. Dengan demikian, sebagian besar pencarian selesai dalam hitungan milidetik, dan pencarian kompleks pun tidak lebih dari 2 detik.

Alur Kerja Lengkap

Pengguna memilih teks di aplikasi mana saja
    ↓
[Pemicu] Menekan hotkey ⌘⇧D
    ↓
[Ekstraksi] TextExtractor mendapatkan:
    • Teks yang dipilih
    • 50 karakter konteks sebelum dan sesudah (untuk pemahaman AI)
    • bundleIdentifier aplikasi saat ini (Xcode / Slack / GitHub dll.)
    ↓
[Klasifikasi] InputTypeDetector menentukan jenis input:
    • Bahasa ibu → Mode Express
    • Satu kata → Mode Word
    • 2-4 kata tanpa struktur kalimat → Mode Phrase
    • Kalimat lengkap ≤20 kata → Mode Sentence
    • Multi-kalimat atau >20 kata → Mode Paragraph
    ↓
[Pencarian] LookupCoordinator pencarian berlapis (detail di bawah)
    ↓
[Render] FloatingPanelController:
    • Memunculkan jendela mengambang NSPanel di bawah kursor
    • Menampilkan skeleton screen (animasi loading)
    • Memilih subclass View sesuai mode (WordView / PhraseView / SentenceView dll.)
    • Setelah data tiba, hasil ditampilkan dengan transisi halus
    ↓
[Interaksi] Pengguna dapat:
    • Mengklik tombol putar untuk mendengar pengucapan
    • Mengklik kata untuk pencarian rekursif
    • Menyimpan ke "Buku Kata" (SwiftData)
    • Menutup jendela mengambang dan melanjutkan pekerjaan

Sistem Pencarian Berlapis

Ini adalah kunci performa DevLingo. Pencarian dilakukan secara berurutan berdasarkan prioritas, langsung mengembalikan hasil begitu ditemukan:

Lapisan 1: Pustaka Kosakata Teknis Lokal (<50ms)

Untuk input bahasa Inggris, pertama-tama dicari di database SQLite lokal. Tersedia 85+ istilah pengembangan umum yang sudah dimuat sebelumnya:

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

Tingkat kecocokan sekitar 30% dari pencarian kosakata pengembangan. Respons sangat cepat.

Lapisan 2: Pustaka Frasa Pengembangan Lokal (<100ms)

Untuk frasa 2-4 kata, dicari di database frasa lokal (50+ frasa yang sudah dimuat):

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

Tingkat kecocokan sekitar 20% dari pencarian frasa.

Lapisan 3: Cache SwiftData (<10ms)

Kosakata, frasa, dan kalimat yang sebelumnya pernah dicari pengguna di-cache secara lokal di SwiftData. Jika ditemukan, langsung dikembalikan.

Pengguna pernah mencari "idempotent" → pencarian berikutnya <10ms

Tingkat kecocokan sekitar 50% (tergantung riwayat penggunaan).

Lapisan 4: Claude API (0.5-2 detik)

Jika tiga lapisan sebelumnya tidak menemukan hasil, Claude API dipanggil untuk mendapatkan respons terstruktur.

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

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

:::note Mengapa desain berlapis

• 95% kosakata umum cocok dengan tiga lapisan pertama, <100ms untuk mengembalikan hasil
• 5% kosakata langka atau baru memerlukan Claude API, tetapi hanya 1-2 detik
• Tanpa jaringan tetap dapat mencari di pustaka lokal dan cache
• Menghemat kuota pengguna — Harga Claude API dihitung per penggunaan, desain berlapis mengurangi 95% panggilan API :::

Arsitektur Backend

Backend DevLingo di-deploy di node edge Cloudflare Workers, memproses permintaan API.

Aplikasi Mac
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (Routing Hono)
  ├─ Auth Middleware (Verifikasi JWT)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (proksi permintaan AI)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (proksi sintesis pengucapan)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (database pengguna)

Komponen Utama

• Framework Hono: Framework HTTP ringan, dioptimalkan untuk Cloudflare Workers
• Database D1: SQLite on Cloudflare, menyimpan buku kata pengguna, data sinkronisasi
• Penyimpanan KV: Token sesi, cache rate limiting, cache respons API
• Proksi Claude API: Aplikasi Mac memproksikan permintaan ke Claude melalui Workers, menghindari paparan API key di lokal

Ekstraksi Teks dan Konteks

TextExtractor menggunakan AXUIElement (API Aksesibilitas macOS) untuk mendapatkan:

Pengguna memilih "idempotent" di Slack

Hasil ekstraksi:
{
  "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."
}

Konteks ini dikirim ke Claude, membantu AI memahami: “idempotent di sini adalah konteks desain API”, bukan yang lain.

Algoritma Deteksi Jenis Input

if teks mengandung karakter bahasa ibu:
  → Mode Express
elif jumlah kata == 1:
  → Mode Word
elif jumlah kata in [2, 3, 4]:
  if mengandung struktur kalimat lengkap:
    → Mode Sentence
  else:
    → Mode Phrase
elif jumlah kalimat > 1 or jumlah kata > 20:
  → Mode Paragraph
else:
  → Mode Sentence

:::tip Deteksi Cerdas Deteksi input selesai secara instan di lokal, tanpa panggilan API. Memastikan pengguna tidak pernah merasakan penundaan pada langkah “menentukan jenis input”. :::

Tampilan Jendela Mengambang

FloatingPanelController membuat NSPanel (jendela mengambang):

Karakteristik:
• Ditampilkan di atas semua aplikasi (Level: screenSaver)
• Posisi: tepat di bawah kursor (y offset +20px, menghindari penghalangan)
• Status awal: skeleton screen (kerangka loading)
• Data tiba: fade in, menghapus skeleton
• Interaksi: meneruskan klik mouse sepenuhnya (tidak memblokir aplikasi di belakang)
• Cara menutup: klik di luar, tekan ESC, otomatis tertutup setelah 5 menit tidak ada aktivitas

Target Performa

• Pencarian pustaka lokal: <50ms (persentil ke-99)
• Cache hit: <10ms
• End-to-end lengkap (termasuk API): <2 detik (persentil ke-99)
• Waktu kemunculan jendela mengambang: <300ms (persepsi pengguna: cepat)
• Generasi audio TTS: Pertama kali <2 detik, selanjutnya dari cache <100ms

:::note Strategi Cache Audio TTS juga di-cache secara lokal dan di KV, pengucapan kata yang sama hanya disintesis sekali. :::

Privasi Data

Teks pengguna
  ↓
Aplikasi Mac (enkripsi HTTPS)
  ↓
Cloudflare Edge (diproses secara instan)
  ├─ Permintaan Claude API (sementara, tidak digunakan untuk pelatihan)
  └─ Hasil di-cache ke KV (kedaluwarsa otomatis)
  ↓
Hasil dikembalikan ke Mac
  ↓
Penyimpanan SwiftData lokal (di perangkat, sinkronisasi cloud ke D1 opsional)

Konten teks tidak disimpan, kecuali pengguna secara aktif menyimpannya ke buku kata. Lihat detail di Privasi Data dan Keamanan.

Filosofi desain arsitektur DevLingo adalah: “Kecepatan utama, AI sebagai pelengkap, privasi yang diutamakan”.