d3ro-voice/CLAUDE.md

D3RO-VOICE — 로컬 AI 음성 어시스턴트

Speakly RE 기반 완전 로컬 음성 어시스턴트. Ollama + Whisper + TTS.

기술 스택

Electron 33+ | React 19 + MUI 7 + Vite | TypeScript 5.7+ strict better-sqlite3 + drizzle-orm | faster-whisper (Python sidecar) | Ollama REST uiohook-napi | @nut-tree-fork/nut-js | electron-store | electron-log

빌드

npm run dev        # Electron + Vite dev
npm run build      # 프로덕션 빌드
npm run test       # vitest
npm run typecheck  # tsc --noEmit

코딩 규칙

• strict mode, any 금지, console.log 금지 (logger 사용)
• 서비스: 싱글톤 + EventEmitter
• IPC: ${feature}:${action}, D3ROError + ErrorCode
• 메인앱=React+MUI, 팝업=Vanilla JS
• 테마 SSOT: d3roPalette/d3roShadow만 사용, hex 하드코딩 금지 (theme.ts 제외)
• i18n: t() 함수, 하드코딩 한국어/영어 금지
• Co-Authored-By, Claude 관련 커밋 문구 금지
• Windows 데스크톱 실행: AI 에이전트 서브쉘(가상 데스크톱 exebox)에서 GUI 백그라운드 구동을 반복하지 말고, 사용자가 run-desktop.bat 또는 외부 터미널에서 실행하도록 안내.
• Single Instance Lock: app.setName('d3ro-voice')와 app.setAppUserModelId를 최상단 선언하고 dev 모드 사일런트 종료 방지.
• 오디오 장치 탐색: execSync 동기 블로킹 금지 (반드시 exec 비동기 논블로킹).
• GPU 충돌 방지: app.disableHardwareAcceleration() 및 --disable-gpu 유지.

핵심 패턴 (Speakly 차용)

• RecognitionState(9) + AudioState(4) 이중 상태머신
• 이중 조건 플러시 (모델 로딩 + 오디오 버퍼링 병렬)
• 텍스트 삽입: clipboard save→set→Ctrl+V→restore
• 윈도우: 프리로딩 + 2-phase 리사이즈
• 녹음 UI: 9개 웨이브 바, cos 분포, 100ms

현재 상태

Phase 1~15.5 전체 완료 + 랜딩 페이지(site/). 차단 이슈: @nut-tree-fork/nut-js 포크 사용

설계 문서 (구현 시 Read 도구로 참조)

• docs/design/00-master-architecture.md — 시스템 아키텍처, 초기화/종료, 서비스 목록
• docs/design/01-service-specifications.md — 서비스 인터페이스, 상태머신, 이벤트
• docs/design/02-ipc-and-types.md — IPC 채널 전체, 타입, 에러코드, preload API
• docs/design/03-db-and-ui.md — DB 스키마, React 컴포넌트, 팝업 명세, MUI 테마

서비스 목록 (src/main/services/)

Core: LoggerService, ConfigService, VoiceModeService(오케스트레이터) Audio: AudioCaptureService, LocalSTTService, LocalLLMService, TTSPlaybackService Input: HotkeyService, TextInsertService, SoundEffectService, AutoLaunchService Data: HistoryService, DictionaryService, CustomInstructionService, LicenseService Phase10+: MemoService, VoiceCommandService, ScreenContextService, ChainService, CaptionService Phase12+: FileTranscriptionService, MeetingSummaryService, DictationTemplateService Phase13+: VoiceConversationService, RAGService, VoiceActionService Phase14: MeetingModeService Phase14.5: MeetingDocTemplateService + 다중 문서 생성/편집/내보내기 Phase15: Auto Polish + AI 채팅 + 마인드맵 + 공유 Phase15.5: 화자 구분 (LLM 추정 + pyannote 준비)

DS 컴포넌트 (src/renderer/components/ds/)

CrtDisplay, InstrumentPanel, Led, PhysicalButton, MetalCard, PhosphorText(13변형), MetalDial, ScreenPanel, ButtonGroup

디자인 토큰 (theme.ts)

d3roPalette(색상) | d3roTypo(13단계) | d3roShadow(10종) | d3roRadius(7종)