작동 원리 개요

DevLingo의 핵심은 지능적인 “계층적 조회” 시스템입니다: 로컬 빠른 조회에서 시작하여 단계적으로 AI 추론으로 에스컬레이션합니다. 이를 통해 대부분의 조회는 밀리초 내에 완료되며, 복잡한 조회도 2초를 넘지 않습니다.

전체 워크플로우

사용자가 아무 앱에서나 텍스트를 선택
    ↓
[트리거] ⌘⇧D 단축키 누르기
    ↓
[추출] TextExtractor가 다음을 가져옴:
    • 선택된 텍스트 자체
    • 앞뒤 50자 컨텍스트 (AI가 문맥을 이해하기 위해)
    • 현재 앱 bundleIdentifier (Xcode / Slack / GitHub 등)
    ↓
[분류] InputTypeDetector가 입력 유형을 판별:
    • 한국어 → Express 모드
    • 단일 단어 → Word 모드
    • 2-4 단어이며 문장 구조 없음 → Phrase 모드
    • 완전한 문장 ≤20단어 → Sentence 모드
    • 여러 문장 또는 >20단어 → Paragraph 모드
    ↓
[조회] LookupCoordinator 계층적 조회 (아래 상세 설명)
    ↓
[렌더링] FloatingPanelController:
    • 마우스 아래에 NSPanel 플로팅 창 팝업
    • skeleton screen (로딩 애니메이션) 표시
    • 모드에 따라 해당 View 서브클래스 선택 (WordView / PhraseView / SentenceView 등)
    • 데이터 도착 후 부드럽게 페이드인
    ↓
[상호작용] 사용자가 다음을 할 수 있음:
    • 재생 버튼을 클릭하여 발음 듣기
    • 단어를 클릭하여 재귀적 조회
    • "단어장"에 저장 (SwiftData)
    • 플로팅 창을 닫고 작업 계속

계층적 조회 시스템

이것이 DevLingo 성능의 핵심입니다. 우선순위에 따라 순차적으로 조회하며, 결과를 찾으면 즉시 반환합니다:

1계층: 로컬 기술 용어 사전 (<50ms)

영어 입력의 경우 먼저 로컬 SQLite 데이터베이스에서 조회합니다. 85개 이상의 일반적인 개발 용어가 사전 로드되어 있습니다:

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

개발 어휘 조회의 약 30% 적중률. 초고속 응답.

2계층: 로컬 개발 구문 사전 (<100ms)

2-4단어 구문의 경우 로컬 구문 데이터베이스를 조회합니다 (50개 이상 사전 로드):

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

구문 조회의 약 20% 적중률.

3계층: SwiftData 캐시 (<10ms)

사용자가 이전에 조회한 단어, 구문, 문장은 로컬 SwiftData에 캐시됩니다. 찾으면 즉시 반환합니다.

사용자가 "idempotent"를 조회한 적 있음 → 다음 조회 <10ms

약 50% 적중률 (사용 이력에 따라 다름).

4계층: Claude API (0.5-2s)

앞의 세 계층에서 모두 미스나면 Claude API를 호출하여 구조화된 응답을 가져옵니다.

요청: {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "ko-KR"
}

응답: {
  "type": "phrase", // compound verb
  "definition_en": "...",
  "definition_ko": "...",
  "examples": [...],
  "pronunciation": {...},
  "register": "technical",
  "l1_tips": "..."
}

:::note 계층적 설계의 이유

95%의 자주 사용하는 어휘가 처음 세 계층에 적중, <100ms로 반환
5%의 드문 또는 새로운 어휘만 Claude API가 필요하지만 1-2초면 충분
네트워크 없을 때도 로컬 사전과 캐시를 조회할 수 있음
사용자 할당량 절약 Claude API는 사용 횟수에 따라 과금되며, 계층화로 95%의 API 호출을 줄임 :::

백엔드 아키텍처

DevLingo 백엔드는 Cloudflare Workers 엣지 노드에 배포되어 API 요청을 처리합니다.

Mac 앱
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (Hono 라우팅)
  ├─ Auth Middleware (JWT 검증)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (AI 요청 프록시)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (발음 합성 프록시)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (사용자 데이터베이스)

핵심 구성 요소

Hono 프레임워크: 경량 HTTP 프레임워크, Cloudflare Workers에 최적화
D1 데이터베이스: Cloudflare의 SQLite, 사용자 단어장 및 동기화 데이터 저장
KV 스토리지: 세션 토큰, 속도 제한 캐시, API 응답 캐시
Claude API 프록시: Mac 앱이 Workers를 통해 Claude 요청을 프록시하여 로컬에 API 키를 노출하지 않음

텍스트 추출과 컨텍스트

TextExtractor는 AXUIElement (macOS 접근성 API)를 활용하여 다음을 가져옵니다:

사용자가 Slack에서 "idempotent"를 선택

추출 결과:
{
  "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."
}

이 컨텍스트가 Claude에 전송되어 AI가 이해합니다: “idempotent는 여기서 API 설계 맥락”이지 다른 것이 아닙니다.

입력 유형 감지 알고리즘

if 텍스트에 한국어 포함:
  → Express 모드
elif 단어 수 == 1:
  → Word 모드
elif 단어 수 in [2, 3, 4]:
  if 완전한 문장 구조 포함:
    → Sentence 모드
  else:
    → Phrase 모드
elif 문장 수 > 1 or 단어 수 > 20:
  → Paragraph 모드
else:
  → Sentence 모드

:::tip 스마트 감지 입력 감지는 로컬에서 즉시 완료되며 API 호출이 없습니다. 사용자가 “입력 유형 판별” 단계의 지연을 절대 느끼지 못하도록 합니다. :::

플로팅 창 표시

FloatingPanelController가 NSPanel(플로팅 창)을 생성합니다:

특성:
• 모든 앱 위에 표시 (Level: screenSaver)
• 위치: 마우스 바로 아래 (y offset +20px, 가림 방지)
• 초기 상태: skeleton screen (로딩 스켈레톤)
• 데이터 도착: 페이드인, skeleton 제거
• 상호작용: 마우스 완전 투과 (백그라운드 앱 차단 안 함)
• 닫기 방식: 외부 클릭, ESC 키, 5분 무조작 시 자동 닫기

성능 목표

로컬 사전 조회: <50ms (99 백분위수)
캐시 적중: <10ms
전체 엔드투엔드 (API 포함): <2s (99 백분위수)
플로팅 창 나타나는 시간: <300ms (사용자 체감 빠름)
TTS 오디오 생성: 첫 번째 <2s, 이후 캐시 <100ms

:::note 캐시 전략 TTS 오디오도 로컬과 KV에 캐시되어 같은 단어의 발음은 한 번만 합성합니다. :::

데이터 프라이버시

사용자 텍스트
  ↓
Mac 앱 (HTTPS 암호화)
  ↓
Cloudflare Edge (즉시 처리)
  ├─ Claude API 요청 (임시, 학습에 사용되지 않음)
  └─ 결과 KV에 캐시 (자동 만료)
  ↓
결과가 Mac으로 반환
  ↓
로컬 SwiftData 저장 (기기 내, 선택적 D1 클라우드 동기화)

텍스트 내용은 사용자가 직접 단어장에 저장하지 않는 한 저장되지 않습니다. 자세한 내용은 데이터 프라이버시와 보안을 참조하세요.

DevLingo의 아키텍처 설계 철학은: “빠른 것이 우선, AI는 보조, 프라이버시가 최우선”입니다.