6.1 KiB
D3RO-VOICE — 멀티플랫폼 AI 음성 어시스턴트 모노레포
로컬 우선(Desktop) + 클라우드 동기화(Web · Mobile · Supabase · .NET API · Admin)를 아우르는 멀티플랫폼 AI 음성 어시스턴트.
에이전트 진입점: 작업 전
AGENTS.md와 정본 인프라/기능 지도인docs/map/00-index.md를 먼저 읽는다. 기능 추가·삭제·변경·백로그 이관 시docs/map/10-feature-catalog.md, 해당 플랫폼 표면 문서(04~09),docs/map/11-gap-backlog.md를 반드시 함께 갱신한다 (규칙:docs/map/12-update-protocol.md).
모노레포 표면 구성
apps/desktop— Electron 33+ 데스크톱 앱 (로컬 우선: SoX + faster-whisper Python sidecar + Ollama + SQLite/Drizzle + Cloud Sync)apps/web— Next.js 16 클라우드 웹 콘솔 (/appbasePath, React 19 + MUI 7 + Supabase SSR/Realtime + Web Push)apps/mobile-rn— React Native 0.79 모바일 앱 (클라우드 우선, Android/iOS, 오프라인 내구성 큐, Google Play IAP, FCM/APNs)apps/api-server— ASP.NET Core 10 AI 프록시 및 백오피스 백엔드apps/admin— Next.js 16 관리자 백오피스 콘솔 (RBAC, 감사 로그, 콘텐츠 신고/지원 대응)server/supabase— PostgreSQL + RLS + Auth + Storage + Deno Edge Functions (정본 제품 백엔드)server/cloudflare-worker— 엣지 게이트웨이 및 라우팅 워커site/— 랜딩 · 마케팅 · 법무 · 다운로드 · 초대 핸드오프 정적 사이트packages/*— 공유 패키지 (@d3ro/core,@d3ro/ui,@d3ro/ui-native,@d3ro/i18n,@d3ro/api-client)
빌드 및 검증
npm run dev # Desktop (Electron + Vite) dev
npm run build # Desktop 프로덕션 빌드
npm run typecheck # 워크스페이스 전체 tsc --noEmit
npm run test # 워크스페이스 vitest
npm run lint # 워크스페이스 eslint
npm run typecheck:mobile # Mobile RN tsc --noEmit
npm run test:mobile # Mobile RN Jest
npm run lint:mobile # Mobile RN eslint
npm run check:design # 디자인 토큰 SSOT 검사
코딩 및 보안 규칙 (Non-Negotiable)
- strict mode,
any금지,console.log금지 (logger사용) - 서비스: 싱글톤 +
EventEmitter - IPC:
${feature}:${action}(packages/core/src/ipc-channels.ts정본),D3ROError+ErrorCode+IPCResult - 메인앱=React+MUI, 데스크톱 팝업=Vanilla JS
- 테마 SSOT:
d3roPalette/d3roShadow/d3roTypo/d3roRadius및 CSS 변수만 사용, hex 하드코딩 금지 (theme.ts제외) - i18n:
t()함수 사용, UI 내 한국어/영어 문자열 하드코딩 금지 - 시크릿 하드코딩 절대 금지, Fail-Closed 원칙 준수 (가짜 성공 응답·샘플 데이터 대체 금지)
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유지.
핵심 패턴 (Desktop)
- RecognitionState(9) + AudioState(4) 이중 상태머신
- 이중 조건 플러시 (모델 로딩 + 오디오 버퍼링 병렬)
- 텍스트 삽입: clipboard save→set→Ctrl+V→restore
- 윈도우: 프리로딩 + 2-phase 리사이즈
- 녹음 UI: 9개 웨이브 바, cos 분포, 100ms
업데이트 / 릴리스
자동 업데이트는 electron-updater + Forgejo feed
(git.chanpaca.net/api/packages/yunchan/generic/d3ro-voice/latest). 설치본은 무서명이라
latest.yml을 Ed25519로 서명하고 앱이 받은 설치 파일을 검증한다(update-signature.ts).
릴리스 = npm run release -- patch|minor 한 줄 (main, 깨끗한 트리, .env의 FORGEJO_TOKEN ·
D3RO_UPDATE_SIGNING_KEY). 실패하면 npm run release -- --resume. 채널·최소 지원 버전·
강제 업데이트·rollout·킬 스위치는 release/update-policy.json이 정본. 태그는 불변.
규칙은 AGENTS.md §6.
정본 문서 안내 (구현 전 Read 도구로 참조)
docs/map/00-index.md— 정본 기능·인프라 지도 색인 (01~12)docs/map/10-feature-catalog.md— 플랫폼별 기능 구현 상태 매트릭스docs/map/11-gap-backlog.md— 미해결 갭·백로그·외부 블로커docs/v3/MOBILE_APP_COMPLETION_SSOT.md— 모바일 완성도 정본docs/design/00-master-architecture.md~03-db-and-ui.md— 데스크톱 초기 아키텍처 설계 기록
데스크톱 서비스 목록 (apps/desktop/src/main/services/)
Core: LoggerService, ConfigService, VoiceModeService(오케스트레이터), UnifiedSearchService 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, MeetingDocTemplateService + 다중 문서 생성/편집/내보내기 + 화자 구분
DS 컴포넌트 (packages/ui & packages/ui-native)
CrtDisplay, InstrumentPanel, Led, PhysicalButton, MetalCard, DoubleBezelCard, PhosphorText(13변형), MetalDial, ScreenPanel, ButtonGroup, TactileBadge, StatRing, TiltCard
디자인 토큰 (theme.ts)
d3roPalette(색상) | d3roTypo(13단계) | d3roShadow(10종) | d3roRadius(7종)