# 03. YAKKI SMART v2.3 MODULES AND COMPONENTS
**Date:** 2025-11-30
**Last Updated:** 2025-12-05
**Project Version:** 2.3
**Total Modules:** 32
**Kotlin Files:** 602
**Lines of Code:** ~65,000+
**Build Status:** ✅ BUILD SUCCESSFUL (28+ modules compile)
**v2.3 Changes:** Table formatting conversion (Markdown → stable ASCII format)
---
## 📋 TABLE OF CONTENTS
1. [Modular Architecture Overview](#modular-architecture-overview)
2. [Dependency Graph](#dependency-graph)
3. [Detailed Module Description](#detailed-module-description)
- [:app - Main Application](#app---main-application)
- [:conductor - Adaptive Routing](#conductor---adaptive-routing)
- [:smartrag3:* - RAG System (15 modules)](#smartrag3---rag-system-15-modules)
- [:docparser:* - Document Parsing (3 modules)](#docparser---document-parsing-3-modules)
- [:yakki-mail:* - Email Client (4 modules)](#yakki-mail---email-client-4-modules)
- [:yakkibluetooth:* - Bluetooth LE Audio (2 modules)](#yakkibluetooth---bluetooth-le-audio-2-modules)
- [:latency - Latency Measurement](#latency---latency-measurement)
- [:llmorchestrator - LLM Orchestration](#llmorchestrator---llm-orchestration)
- [:archivelib - Archive Operations](#archivelib---archive-operations)
- [:readability - Content Extraction](#readability---content-extraction)
- [:smartrag-v2 - Legacy RAG (DEPRECATED)](#smartrag-v2---legacy-rag-deprecated)
4. [Dependency Matrix](#dependency-matrix)
5. [Module Working Recommendations](#module-working-recommendations)
---
## MODULAR ARCHITECTURE OVERVIEW
### Organization Principles
YAKKI SMART uses **multi-module architecture** with the following principles:
1. **Clean Architecture**: Separation into Domain, Data, Presentation layers
2. **Feature Modules**: Independent modules for separate functions
3. **Library Modules**: Reusable libraries (docparser, smartrag3, yakki-mail)
4. **Dependency Inversion**: Upper-level modules depend on abstractions
5. **Single Responsibility**: Each module solves one task
### Naming Patterns
```
:app # Main application (Android)
:module-name # Standalone module (conductor, latency)
:library:submodule # Library with submodules (smartrag3:core, docparser:pdf)
:feature:ui # Feature module with UI (yakki-mail:ui)
:feature:core:component # Three-level hierarchy (yakki-mail:core:security)
```
### Code Distribution by Modules
```
📊 Module Size (LOC):
:app ~25,000 ████████████████████████████ (38%)
:smartrag3:* ~8,000 ████████████ (12%)
:yakkibluetooth:* ~4,000 ██████ (6%)
:conductor ~3,500 █████ (5%)
:docparser:* ~2,000 ███ (3%)
:smartrag-v2 ~1,500 ██ (2%)
:yakki-mail:* ~1,500 ██ (2%)
:latency ~800 █ (1%)
:llmorchestrator ~500 █ (1%)
:archivelib ~300 █ (<1%)
:readability ~1,000 █ (2%)
```
---
## DEPENDENCY GRAPH
### Mermaid Diagram
```mermaid
graph TD
%% Main App
APP[:app]
%% Core Infrastructure
CONDUCTOR[:conductor]
LATENCY[:latency]
LLMORCH[:llmorchestrator]
%% SmartRAG3 Modules
RAG3_CORE[:smartrag3:core]
RAG3_COMMON[:smartrag3:common]
RAG3_DOMAIN[:smartrag3:domain]
RAG3_DATA[:smartrag3:data]
RAG3_DI[:smartrag3:di]
RAG3_EMBED[:smartrag3:embeddings]
RAG3_LANG[:smartrag3:language]
RAG3_PARSE[:smartrag3:parsing]
RAG3_INGEST[:smartrag3:ingestion]
RAG3_ENT[:smartrag3:entities]
RAG3_DS[:smartrag3:datasources]
RAG3_NER[:smartrag3:ner]
RAG3_SEC[:smartrag3:security]
%% DocParser Modules
DOCPARSE_CORE[:docparser:core]
DOCPARSE_PDF[:docparser:pdf]
DOCPARSE_OFFICE[:docparser:office]
%% Yakki Mail Modules
MAIL_MODELS[:yakki-mail:core:models]
MAIL_PROTOCOL[:yakki-mail:core:protocol]
MAIL_AUTH[:yakki-mail:core:auth]
MAIL_SEC[:yakki-mail:core:security]
%% Bluetooth Modules
BT_CORE[:yakkibluetooth:core]
BT_LEAUDIO[:yakkibluetooth:leaudio]
%% Utility Modules
ARCHIVE[:archivelib]
READABILITY[:readability]
RAG2[:smartrag-v2 DEPRECATED]
%% Dependencies: :app
APP --> CONDUCTOR
APP --> LATENCY
APP --> RAG3_CORE
APP --> RAG3_DOMAIN
APP --> RAG3_DI
APP --> RAG3_DATA
APP --> RAG3_LANG
APP --> RAG3_PARSE
APP --> RAG3_INGEST
APP --> RAG3_DS
APP --> DOCPARSE_CORE
APP --> BT_CORE
%% Dependencies: :conductor
CONDUCTOR --> LATENCY
CONDUCTOR --> RAG3_CORE
%% Dependencies: :smartrag3:data
RAG3_DATA --> RAG3_CORE
RAG3_DATA --> RAG3_COMMON
RAG3_DATA --> RAG3_DOMAIN
RAG3_DATA --> ARCHIVE
%% Dependencies: :smartrag3:domain
RAG3_DOMAIN --> RAG3_CORE
RAG3_DOMAIN --> RAG3_COMMON
%% Dependencies: :smartrag3:di
RAG3_DI --> RAG3_DATA
RAG3_DI --> RAG3_DOMAIN
RAG3_DI --> RAG3_EMBED
RAG3_DI --> RAG3_LANG
RAG3_DI --> RAG3_PARSE
%% Dependencies: :smartrag3:embeddings
RAG3_EMBED --> RAG3_CORE
RAG3_EMBED --> RAG3_COMMON
%% Dependencies: :smartrag3:language
RAG3_LANG --> RAG3_CORE
RAG3_LANG --> RAG3_COMMON
%% Dependencies: :smartrag3:parsing
RAG3_PARSE --> RAG3_CORE
RAG3_PARSE --> RAG3_COMMON
RAG3_PARSE --> DOCPARSE_CORE
%% Dependencies: :smartrag3:ingestion
RAG3_INGEST --> RAG3_CORE
RAG3_INGEST --> RAG3_COMMON
RAG3_INGEST --> RAG3_LANG
%% Dependencies: :smartrag3:entities
RAG3_ENT --> RAG3_CORE
%% Dependencies: :smartrag3:datasources
RAG3_DS --> RAG3_CORE
RAG3_DS --> RAG3_ENT
RAG3_DS --> RAG3_NER
%% Dependencies: :smartrag3:ner
RAG3_NER --> RAG3_CORE
RAG3_NER --> RAG3_ENT
%% Dependencies: :smartrag3:security
RAG3_SEC --> RAG3_CORE
%% Dependencies: :docparser modules
DOCPARSE_PDF --> DOCPARSE_CORE
DOCPARSE_OFFICE --> DOCPARSE_CORE
%% Dependencies: :yakki-mail modules
MAIL_PROTOCOL --> MAIL_MODELS
MAIL_AUTH --> MAIL_MODELS
MAIL_SEC --> MAIL_MODELS
MAIL_SEC --> RAG3_SEC
%% Dependencies: :yakkibluetooth
BT_LEAUDIO --> BT_CORE
%% Styling
classDef appModule fill:#e1f5e1,stroke:#4caf50,stroke-width:3px
classDef infraModule fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
classDef ragModule fill:#fff3e0,stroke:#ff9800,stroke-width:2px
classDef libraryModule fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
classDef deprecatedModule fill:#ffebee,stroke:#f44336,stroke-width:2px,stroke-dasharray: 5 5
class APP appModule
class CONDUCTOR,LATENCY,LLMORCH infraModule
class RAG3_CORE,RAG3_COMMON,RAG3_DOMAIN,RAG3_DATA,RAG3_DI,RAG3_EMBED,RAG3_LANG,RAG3_PARSE,RAG3_INGEST,RAG3_ENT,RAG3_DS,RAG3_NER,RAG3_SEC ragModule
class DOCPARSE_CORE,DOCPARSE_PDF,DOCPARSE_OFFICE,MAIL_MODELS,MAIL_PROTOCOL,MAIL_AUTH,MAIL_SEC,BT_CORE,BT_LEAUDIO,ARCHIVE,READABILITY libraryModule
class RAG2 deprecatedModule
```
### ASCII Graph (simplified)
```
┌──────────┐
│ :app │ (Main Application)
└─────┬────┘
│
┌─────────────────────────────┼─────────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ :conductor │ │ :smartrag3:* │ │ :docparser:* │
│ (Routing) │ │ (15 modules) │ │ (3 modules) │
└──────┬───────┘ └──────┬───────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ :latency │ │ :archivelib │
│ (HTTP TTFB) │ │ (ZIP utils) │
└──────────────┘ └──────────────┘
┌──────────────────────────────────────────────────────────────┐
│ Library Modules (Standalone, Reusable) │
├──────────────────────────────────────────────────────────────┤
│ :yakkibluetooth:* (2 modules) - Bluetooth LE Audio │
│ :yakki-mail:* (4 modules) - Email client backend │
│ :readability (1 module) - Web content extraction │
│ :llmorchestrator (1 module) - LLM routing (partial) │
└──────────────────────────────────────────────────────────────┘
┌──────────────┐
│:smartrag-v2 │ (DEPRECATED - migrate to smartrag3)
└──────────────┘
```
---
## DETAILED MODULE DESCRIPTION
---
### :app - Main Application
**Purpose:** Main Android application module containing all UI, scenarios, and business logic.
**Technologies:**
- Kotlin 2.2.20
- Jetpack Compose (Material 3)
- Hilt Dependency Injection (KSP 2.2.20-2.0.3)
- Coroutines 1.10.1
- Gemini SDK 0.9.0
- Room 2.8.2
**Size:**
- LOC: ~25,000+
- Kotlin files: 137 (key files)
- ViewModels: 12
- Services: 30+
- Scenarios: 4 (Translator, Document Analyzer, Chat, SMS)
**Key Components:**
#### 1. Scenarios (Usage Scenarios)
**Translator Scenario (v4.3.0)** - Real-time voice translator
- `TranslatorScenario.kt` (533 lines) - Main UI
- `TranslatorViewModel.kt` (1269 lines) - Business logic with detailed changelog
- `StreamingPipelineExecutor.kt` - Pipeline orchestration
- Streaming STT (Deepgram, Google Cloud, Device)
- DeepInfra translation (Qwen 2.5 72B + DeepSeek V2.5)
- Priority-based provider selection with automatic fallback
- TTS queue for sequential playback
- Quality assessment (COMET-QE)
- Translation history management
- Wake word detection (Picovoice)
- Voice commands (Round 5 security)
**Document Analyzer Scenario** - AI document analysis
- `DocumentAnalyzerScreen.kt` (520 lines) - Material 3 UI
- `DocumentAnalyzerViewModel.kt` (165 lines)
- `DocumentAnalyzerService.kt` - Gemini 2.0 Flash integration
- 8 document types (Contract, Invoice, Email, Resume, Medical, Receipt, Legal, Generic)
- Template-based extraction (Strategy pattern)
- RAG integration for saving results
**Chat with RAG** - Chat with context
- `ChatScreen.kt` - Material 3 UI
- `ChatViewModel.kt` - State management
- Long press to copy messages
- SmartRAG v3 integration (in progress)
**SMS Integration** - Read and send SMS
- `SendSmsScreen.kt` (209 lines)
- `SendSmsViewModel.kt` (72 lines)
- `SmsSender.kt` (246 lines) - Domain service
- Automatic splitting of long messages (>160 chars)
- Persona linking
#### 2. Services
**Speech-to-Text (STT):**
- `DeviceSTTService.kt` - Android Speech Recognizer
- `GoogleCloudSTTService.kt` - Google Cloud STT (125+ languages)
- `WhisperSTTService.kt` - Whisper API integration
- `DeepgramSTTService.kt` - Deepgram streaming STT
- `AssemblyAISTTService.kt` - AssemblyAI STT (structure)
**Text-to-Speech (TTS):**
- `DeviceTTSService.kt` - Android TTS
- TTS queue system for sequential playback
**Translation:**
- `OpenAICompatibleQwenService.kt` (297 lines) - DeepInfra Qwen 2.5 72B (PRIMARY for real-time)
- `GeminiTranslationService.kt` - Gemini API (EMERGENCY fallback)
- `GPT4oMiniTranslationService.kt` - OpenAI GPT-4o Mini (legacy)
- Priority chain: qwen-deepinfra → deepseek-deepinfra → gemini-translation
**Quality Assessment:**
- `QualityAssessmentService.kt` - COMET-QE integration
- ⚠️ **CRITICAL:** Hardcoded HuggingFace token (line 140) - NEEDS FIX
**Other:**
- `RemoteConfigService.kt` - Firebase Remote Config
- `BluetoothService.kt` - Bluetooth integration
- `AudioStreamProvider.kt` - Audio streaming
#### 3. Domain Layer
**Models:**
- `DomainError.kt` - 17 error types (YS-XXXX codes)
- `TranslationState.kt` - State machine for translation pipeline
- `AppTier.kt` - Quality tiers (Device, Cloud, Premium)
**Orchestrators:**
- `StreamingPipelineExecutor.kt` - Main translation pipeline
- `SmartTranslationBuffer.kt` - Buffer management
- `AdaptiveTierController.kt` - Adaptive quality control
- `STTConductor.kt` - STT provider routing
**Rules (Language-specific):**
- `EnglishRules.kt` - English sentence detection
- `RussianRules.kt` - Russian sentence detection
- `ChineseRules.kt` - Chinese sentence detection
#### 4. UI Components
**Material 3 Components:**
- `StreamingSTTView.kt` - Streaming STT display
- `ModelBadge.kt` - Model/Provider badge
- `TTSReplayButton.kt` - TTS replay control
- `ErrorView.kt` - Error display
- `ChatBubble.kt` - Chat message bubble
- `LanguageSelector.kt` - Language selection
**Screens:**
- `SimpleTranslatorScreen.kt` - Simplified translator UI
- `ProviderTestScreen.kt` - Provider testing UI
- `TranslatorSettingsScreen.kt` - Settings UI
- `GlobalHistoryScreen.kt` - Translation history
- `FavoritesScreen.kt` - Favorites management
- `AboutScreen.kt` - About page
- `BluetoothSettingsScreen.kt` - Bluetooth settings
- `AudioDeviceSettingsScreen.kt` - Audio settings
- `RAGKnowledgeScreen.kt` - RAG knowledge base UI
#### 5. Localization (i18n)
**UiString System** - Type-safe localization:
- `UiString.kt` - Sealed interface (100+ lines)
- `LocalizationProvider.kt` - Centralized translations
- 4 preset languages (EN, RU, ES, ZH)
- Dynamic language addition via Gemini API
- DataStore persistence
**DomainErrorLocalization** - Error localization:
- Mapping DomainError → LocalizationKey
- Multi-language error messages
#### 6. Dependency Injection (Hilt)
**Modules:**
- `AppModule.kt` - Core dependencies
- `ViewModelModule.kt` - ViewModels
- `ServiceModule.kt` - Services (STT, TTS, Translation)
- `STTModule.kt` - STT providers
- `DocParserModule.kt` - Document parsers
- `SmartRAGModule.kt` - RAG integration
- `StorageModule.kt` - Storage providers
#### 7. Navigation
- `AppRoutes.kt` - Navigation routes
- `MainScaffold.kt` - Main UI scaffold
- `NavigationDrawerContent.kt` - Drawer menu
- `TranslatorNavHost.kt` - Translator navigation
**Dependencies:**
- `:conductor` - Adaptive routing
- `:latency` - Latency measurement
- `:smartrag3:*` - RAG system (core, domain, data, di, language, parsing, ingestion, datasources)
- `:docparser:core` - Document parsing interfaces
- `:yakkibluetooth:core` - Bluetooth LE Audio
**Readiness Status:** 82% (Production-ready with technical debt)
**Technical Debt:**
```
🔴 CRITICAL - Security (1 issue)
├─ Issue: Hardcoded HuggingFace API token
├─ Location: QualityAssessmentService.kt:140
└─ Fix Time: 5 minutes
🔴 CRITICAL - Deprecated APIs (11 issues)
├─ Issue: @Deprecated translateSafe, recognizeSafe, synthesizeSafe
├─ Impact: Type safety violations, exception-based flow
└─ Fix Time: 2 days
🟡 MEDIUM - TODO markers (15 issues)
├─ Topics: Analytics, GoogleCloudSTT, voice command parsing
└─ Fix Time: Varies (1-5 days each)
🟢 LOW - Hardcoded values (5 issues)
├─ Issue: Language pairs, TTS speed, quality thresholds
└─ Fix Time: 1 day (move to RemoteConfig)
🟢 LOW - Empty implementations (3 issues)
├─ Issue: Settings placeholders, AudioRecorderService
└─ Fix Time: 3-5 days
```
**Implemented Features:**
- ✅ Translator Scenario (v4.3.0) - Full streaming translation pipeline
- ✅ DeepInfra integration (Qwen 2.5 72B + DeepSeek V2.5)
- ✅ Google Cloud STT integration (setup ready)
- ✅ Priority-based provider selection with automatic fallback
- ✅ TTS queue system for sequential audio playback
- ✅ Wake word detection (Picovoice)
- ✅ Quality assessment (COMET-QE)
- ✅ STT Conductor with adaptive tier escalation
- ✅ Voice command handler (Round 5 security)
- ✅ CAPTCHA challenge system
- ✅ Translation history management
- ✅ Noise level monitoring
- ✅ Localization system (4 languages + dynamic)
- ✅ Document Analyzer scenario (8 document types)
- ✅ SMS sending/reading integration
- ✅ Chat with RAG (UI ready)
- ✅ Scenario management system
- ✅ Permission handling system
- ✅ Centralized error handling (DomainError + ErrorHandler)
**Missing Features:**
- ❌ Multilingual Conference (specified, not implemented)
- ❌ Meeting Summary scenario
- ❌ Lecture Notes scenario
- ❌ Tour Guide scenario
- ❌ Life Coach scenario
- ❌ YouTube scenario (not specified)
- ❌ Full settings implementation
- ❌ Analytics & monitoring
- ❌ Monetization system
**Compilation:** ✅ BUILD SUCCESSFUL (with pre-existing errors in DomainErrorLocalization.kt, unrelated to recent changes)
---
### :conductor - Adaptive Routing
**Purpose:** Intelligent request routing to LLM using AI, RAG and latency metrics.
**Technologies:**
- Kotlin 2.2.20
- Gemini SDK 0.9.0 (Gemini 2.5 Flash Lite)
- Koin DI
- OkHttp3
- Coroutines
**Size:**
- LOC: ~3,500
- Kotlin files: 25+
**Key Components:**
#### 1. SimpleConductor (v1.1.0)
**File:** `SimpleConductor.kt` (150+ lines)
**Features:**
- LLM-based routing (Gemini 2.5 Flash Lite)
- Multi-model support (6 Azure OpenAI regions)
- Cost-aware selection
- Retry logic with exponential backoff
- Circuit Breaker pattern
- Typed error handling (ConductorError)
**Workflow:**
```
User Query → SimpleConductor → Gemini Analysis → Route to Best Model → Response
```
#### 2. UIConductorOrchestratorV2 (Voice Commands)
**Files:** `UIConductorOrchestratorV2.kt`, `UIConductorOrchestratorV2_1.kt`
**Features:**
- Voice command processing (Round 5 security)
- Fuzzy logic for commands
- CAPTCHA challenge generator
- Tool registry and definitions
- VoiceCommandHandler integration
**Security Features:**
- Fuzzy matching to reduce recognition errors
- CAPTCHA for critical actions (Delete, Settings)
- Confidence scoring
- Ambiguity detection
#### 3. TierSelector (Adaptive Quality)
**File:** `TierSelector.kt`
**Status:** MVP (logging only)
**Planned:**
- Automatic quality tier selection (Device, Cloud, Premium)
- Based on latency, cost, quality metrics
#### 4. Latency Integration
**File:** `LatencyIntegration.kt`
**Features:**
- HTTP latency measurement (TTFB)
- Server health checks
- Region-based selection
- Real-time metrics collection
#### 5. RAG Integration
**File:** `ConductorRAG.kt`
**Features:**
- Metrics storage in SmartRAG
- Best server selection based on history
- Performance analysis
#### 6. Pipeline Builders
**Files:** `TemporaryPipelineBuilder.kt`, `AdminPipelineBuilder.kt`
**Features:**
- Dynamic pipeline creation
- Voice command → Action conversion
- Admin tools for debugging
**Dependencies:**
- `:latency` - HTTP latency measurement
- `:smartrag3:core` - RAG storage (optional)
**Readiness Status:** 87% (Production-ready)
**Technical Debt:**
```
🟡 MEDIUM - Gemini SDK Mocks (25 locations)
├─ Issue: Waiting for Gemini SDK 1.0.0+ with function calling
├─ Impact: Using string-based mocks instead of SDK types
└─ Fix Time: After SDK 1.0.0+ release (Q1 2026)
🟢 LOW - TODO markers (10 locations)
├─ Topics: UIActionExecutor delegation, typed arrays, nested objects
└─ Fix Time: 1-2 weeks
```
**Implemented Features:**
- ✅ SimpleConductor with Circuit Breaker (v1.1.0)
- ✅ Gemini 2.5 Flash Lite integration
- ✅ Retry logic with exponential backoff
- ✅ Typed error handling (ConductorError)
- ✅ TierSelector for adaptive quality (MVP - logging only)
- ✅ UIConductorOrchestratorV2 for voice commands
- ✅ Tool registry and definitions
- ✅ VoiceCommandHandler with fuzzy logic
- ✅ CAPTCHA challenge generator
- ✅ Pipeline builder (temporary + admin)
- ✅ Latency measurement integration
- ✅ RAG integration for metrics
**Missing Features:**
- ❌ Gemini SDK 1.0.0+ function calling (currently mocked)
- ❌ Full UI action executor implementation
- ❌ Action cancellation (TODO:311)
**Testing:**
- Unit tests with MockWebServer3
- Test coverage: 87%
- Files: `ConductorRAGTest.kt`, `SimpleConductorTest.kt`
**Compilation:** ✅ BUILD SUCCESSFUL
---
### :smartrag3:* - RAG System (15 modules)
**Purpose:** Next-generation Retrieval-Augmented Generation system for personalized context, entity graph, and semantic search.
**Total Size:** ~8,000 LOC
**Status:** ✅ ALL 7 PHASES COMPLETE - All 15 modules compiled successfully
**Architecture:** Clean Architecture + Koin DI (library module pattern)
---
#### :smartrag3:core
**Purpose:** Core entities, ObjectBox setup, HNSW indexing.
**Technologies:**
- ObjectBox 4.0 (NoSQL database with HNSW)
- Kotlin 2.2.20
**Size:** ~1,000 LOC
**Key Components:**
- `Document.kt` - ObjectBox entity for documents
- `Chunk.kt` - ObjectBox entity for chunks
- `Embedding.kt` - Vector embeddings storage
- `SmartRAGDatabase.kt` - ObjectBox setup
- `HNSWIndex.kt` - HNSW indexing configuration
**Features:**
- HNSW (Hierarchical Navigable Small World) for fast vector search
- Cosine similarity for search
- Persistent storage (ObjectBox files)
**Dependencies:** None (base module)
**Status:** ✅ Complete
---
#### :smartrag3:common
**Purpose:** Common utilities, wrappers, error types.
**Size:** ~300 LOC
**Key Components:**
- `SmartRAGResult.kt` - Result wrapper (Success/Failure)
- `SmartRAGError.kt` - Error types
- `Extensions.kt` - Kotlin extensions
**Dependencies:** None
**Status:** ✅ Complete
---
#### :smartrag3:domain
**Purpose:** Use cases, repository interfaces (Clean Architecture).
**Size:** ~500 LOC
**Key Components:**
- `AddDocumentUseCase.kt` - Add documents
- `SearchDocumentsUseCase.kt` - Search documents
- `GetPersonaDataUseCase.kt` - Get Persona data
- `RAGRepository.kt` - Repository interface
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
**Status:** ✅ Complete
---
#### :smartrag3:data
**Purpose:** Repository implementation, ZSTD compression, int8 quantization, persistent storage.
**Technologies:**
- ZSTD compression (LZ77-based, 3x better than GZIP)
- int8 quantization (8x memory reduction)
- External storage for RAG indices
**Size:** ~1,500 LOC
**Key Components:**
- `RAGRepositoryImpl.kt` - Main repository
- `ZSTDCompressor.kt` - ZSTD compression
- `Int8Quantizer.kt` - Vector quantization
- `RAGIndexManager.kt` - **NEW (2025-11-30)** External storage management
- `RAGMigrationManager.kt` - **NEW (2025-11-30)** ZIP backup on reinstall
**Persistent RAG Features (NEW - Phase 1):**
- Store indices outside internal storage (survives app reinstall)
- Metadata file `index.json` for validation
- ZIP backup on app deletion
- Migration manager for recovery
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
- `:smartrag3:domain`
- `:archivelib` - ZIP backup
**Status:** ✅ Complete + NEW Persistent RAG (2025-11-30)
**Technical Debt:** None
---
#### :smartrag3:di
**Purpose:** Koin dependency injection modules.
**Size:** ~200 LOC
**Key Components:**
- `SmartRAGModules.kt` - Koin modules definition
- Modules for: core, data, domain, embeddings, language, parsing
**Dependencies:**
- `:smartrag3:data`
- `:smartrag3:domain`
- `:smartrag3:embeddings`
- `:smartrag3:language`
- `:smartrag3:parsing`
**Status:** ✅ Complete
---
#### :smartrag3:embeddings
**Purpose:** On-device embedding generation (ONNX Runtime + EmbeddingGemma 300M).
**Technologies:**
- ONNX Runtime 1.19.2 (Android)
- EmbeddingGemma 300M (planned)
**Size:** ~800 LOC
**Key Components:**
- `EmbeddingGemmaProvider.kt` - Main provider
- `OnnxQuantizationService.kt` - int8 quantization
- `LRUEmbeddingCache.kt` - LRU cache for embeddings
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
**Status:** ⚠️ Structure Only (ONNX stub implementation)
**Technical Debt:**
```
🔴 CRITICAL - ONNX Stub (8 locations)
├─ Issue: EmbeddingGemmaProvider returns zeros instead of actual embeddings
├─ Impact: On-device embedding generation non-functional
├─ Impact: Semantic search doesn't work (vector search broken)
└─ Fix Time: 2-3 weeks (ONNX Runtime 1.19.2 + Gemma 300M integration)
```
**Impact:** On-device embedding generation non-functional, semantic search doesn't work
**Recommendation:** Integrate actual ONNX Runtime 1.19.2 with Gemma 300M model
---
#### :smartrag3:language
**Purpose:** Language detection, language-specific chunking, tokenizers.
**Technologies:**
- CLD3 (Compact Language Detector 3) - Google
- ICU (International Components for Unicode) for tokenization
**Size:** ~1,000 LOC
**Key Components:**
- `FastTextDetector.kt` - Language detection (CLD3 fallback)
- `DocumentProcessor.kt` - Language-aware chunking
- `ChineseTokenizer.kt`, `ArabicTokenizer.kt`, etc. - Language-specific tokenizers
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
**Status:** ✅ Complete (CLD3 fallback works)
**Technical Debt:**
```
🟠 HIGH - FastText JNI (6 locations)
├─ Issue: FastTextDetector falls back to CLD3
├─ Impact: 107 languages instead of 176, slightly lower accuracy
└─ Fix Time: 1-2 weeks (JNI wrapper) OR accept CLD3 as solution
🟡 MEDIUM - Embeddings Disabled (7 locations)
├─ Issue: DocumentProcessor has embeddings commented out
├─ Blocked: Waiting for ONNX fix (P0-4)
└─ Fix Time: 1 day (after ONNX implementation)
```
**Recommendation:**
- Implement JNI wrapper OR accept CLD3 as primary solution
- Re-enable embeddings after ONNX implementation
---
#### :smartrag3:parsing
**Purpose:** Document parsing (text, PDF, Office), integration with :docparser.
**Size:** ~500 LOC
**Key Components:**
- `TextParser.kt` - Plain text parsing
- `DocumentChunker.kt` - Chunking strategy
- Integration with `:docparser:core`
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
- `:docparser:core`
**Status:** ✅ Complete
---
#### :smartrag3:ingestion
**Purpose:** ML Kit Document Scanner + OCR, ingestion pipeline.
**Technologies:**
- ML Kit Document Scanner (Google)
- WorkManager for background processing
**Size:** ~600 LOC
**Key Components:**
- `DocumentScanner.kt` - ML Kit scanner integration
- `IngestionWorker.kt` - Background ingestion
- `WorkerNotificationHelper.kt` - Notification management
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:common`
- `:smartrag3:language`
**Status:** ⚠️ Partial (ML Kit stub)
**Technical Debt:**
```
🟠 HIGH - ML Kit Integration (5 locations)
├─ Issue: ActivityResult API integration not implemented
├─ Impact: Document scanner UI not functional
└─ Fix Time: 3-5 days
🟢 LOW - Missing Icons (4 locations)
├─ Issue: Notification icons (upload, processing, success, error) not created
└─ Fix Time: 1 hour (create 4 icons in Android Studio)
```
**Recommendation:** Implement proper Activity Result API integration
---
#### :smartrag3:entities
**Purpose:** Persona entities, ObjectBox relations.
**Size:** ~400 LOC
**Key Components:**
- `Persona.kt` - Main persona entity (ObjectBox)
- `EmailMessage.kt` - Email messages
- `SmsMessage.kt` - SMS messages
- ToOne/ToMany relations
**Dependencies:**
- `:smartrag3:core`
**Status:** ✅ Complete
---
#### :smartrag3:datasources
**Purpose:** Data adapters for on-device sync (SMS, Contacts).
**Size:** ~600 LOC
**Key Components:**
- `SmsAdapter.kt` (259 lines) - Read SMS from Telephony provider
- `ContactsAdapter.kt` - Read Contacts
- Incremental sync (fetch only new data)
- Persona linking
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:entities`
- `:smartrag3:ner`
**Status:** ✅ Complete
**Features:**
- ✅ Read SMS (INBOX, SENT filtering)
- ✅ Fetch by timestamp (incremental sync)
- ✅ Get message by ID
- ✅ Count messages
- ✅ Link to Persona
---
#### :smartrag3:ner
**Purpose:** Named Entity Recognition (email, phone extraction).
**Size:** ~300 LOC
**Key Components:**
- `EntityExtractor.kt` - Regex-based extraction
- `EntityLinker.kt` - Link entities to Persona
**Dependencies:**
- `:smartrag3:core`
- `:smartrag3:entities`
**Status:** ✅ Complete
---
#### :smartrag3:security
**Purpose:** Keystore, credentials management, biometric auth.
**Technologies:**
- Android Keystore (hardware-backed)
- EncryptedSharedPreferences
- BiometricPrompt
**Size:** ~400 LOC
**Key Components:**
- `KeystoreManager.kt` - Android Keystore wrapper
- `CredentialManager.kt` - Secure storage
- `TokenManager.kt` - OAuth tokens
- Biometric authentication support
**Dependencies:**
- `:smartrag3:core`
**Status:** ✅ Complete
**Integration:** Used by `:yakki-mail:core:security`
---
### SmartRAG3 - Summary
**Overall Status:** 75% readiness (all modules compiled, partial app integration)
**Compilation:** ✅ BUILD SUCCESSFUL - All 15 modules
**Implemented Features:**
- ✅ Phase 1: Core - ObjectBox 4.0 + HNSW indexing
- ✅ Phase 2: Storage - RAGRepositoryImpl with ZSTD + int8 quantization
- ✅ Phase 3: Embeddings - ONNX Runtime + EmbeddingGemma 300M (structure)
- ✅ Phase 4: Language - CLD3 detection + language-specific chunking
- ✅ Phase 5: Parsing - Text parsing + docparser integration
- ✅ Phase 6: Ingestion - ML Kit Scanner + OCR (structure)
- ✅ Phase 7: Entity Graph - Persona entities + SMS/Contacts adapters + NER
- ✅ **NEW:** Phase 1 Persistent RAG - External storage with migration (2025-11-30)
**Missing Features:**
- ❌ Actual ONNX model files (TODO: copy from assets)
- ❌ FastText native JNI wrapper (pending)
- ❌ ML Kit Document Scanner integration (ActivityResult API)
- ❌ Full app integration (modules ready, need DI wiring)
**Technical Debt Summary:**
```
SmartRAG v3 Technical Debt Overview:
🔴 CRITICAL (1 issue)
└─ ONNX stub implementation (8 locations in EmbeddingGemmaProvider)
→ Blocks: Semantic search, embeddings generation
→ Fix time: 2-3 weeks
🟠 HIGH (2 issues)
├─ FastText JNI fallback to CLD3 (6 locations in FastTextDetector)
│ → Impact: 107 vs 176 languages
│ → Fix time: 1-2 weeks OR accept CLD3
└─ ML Kit integration missing (5 locations in DocumentScanner)
→ Impact: Document scanner UI non-functional
→ Fix time: 3-5 days
🟡 MEDIUM (1 issue)
└─ Embeddings disabled (7 locations in DocumentProcessor)
→ Blocked by: ONNX stub fix
→ Fix time: 1 day after ONNX
🟢 LOW (1 issue)
└─ Missing notification icons (4 locations)
→ Fix time: 1 hour
```
**Estimated Fix Time:** 4-6 weeks for full feature implementation
---
### :docparser:* - Document Parsing (3 modules)
**Purpose:** Universal document parsing library (standalone, reusable).
**Total Size:** ~2,000 LOC
**Status:** 95% readiness (Production-ready)
**Architecture:** Dynamic Feature Modules (base APK <20MB, parsers loaded on-demand)
---
#### :docparser:core
**Purpose:** Interfaces, models, base classes.
**Size:** ~50 KB (included in base APK)
**Key Components:**
- `IDocumentParser.kt` - Parser interface
- `ParsedDocument.kt` - Data model
- `DocumentParserFactory.kt` - Auto-selection factory
- `ParserError.kt` - Error types
**Dependencies:** None
**Status:** ✅ Complete
---
#### :docparser:pdf
**Purpose:** PDF parser (Dynamic Feature Module).
**Technologies:**
- PDFBox Android 2.0.27.0
**Size:** ~5-10 MB (loaded on-demand)
**Key Components:**
- `PdfParser.kt` - Main PDF parser
- Text extraction
- Metadata extraction (title, author, dates, page count)
- Memory-efficient streaming
**Dependencies:**
- `:docparser:core`
**Status:** ✅ Production-ready
---
#### :docparser:office
**Purpose:** Office parser (Dynamic Feature Module).
**Technologies:**
- Apache POI 5.2.5 (Android-compatible via JitPack)
**Size:** ~15-20 MB (loaded on-demand)
**Key Components:**
- `OfficeParser.kt` - Main parser
- **DOCX** support (text, tables, headings, metadata)
- **XLSX** support (sheets as tables, metadata)
- **PPTX** support (slide-by-slide text, metadata)
- Modern formats only (legacy DOC/XLS/PPT excluded)
**Dependencies:**
- `:docparser:core`
**Status:** ✅ Production-ready
---
### DocParser - Summary
**Total Size:** <25 MB (dynamic loading)
**Compilation:** ✅ BUILD SUCCESSFUL
**Integration:**
- ✅ Hilt DI integration (DocParserModule)
- ✅ Used by :smartrag3:parsing
- ✅ Used by Document Analyzer scenario
**Technical Debt:**
```
🟢 LOW - Dynamic Loading
├─ Issue: TODO: Implement dynamic feature loading (currently static)
├─ Impact: Parsers included in base APK (~25MB) instead of on-demand
└─ Priority: Low (works fine as-is, optimization only)
```
**Commit:** `7b471b1` - "feat(docparser): Add Office parser and factory"
---
### :yakki-mail:* - Email Client (4 modules)
**Purpose:** Standalone email client library (backend + UI).
**Total Size:** ~1,500 LOC
**Status:** 35% readiness (Backend structure only, UI not started)
**Architecture:** Multi-module library (models, protocol, auth, security)
---
#### :yakki-mail:core:models
**Purpose:** Domain models for email client.
**Size:** ~300 LOC
**Key Components:**
- `Email.kt` - Email message model
- `Account.kt` - Email account
- `Folder.kt` - Folder (INBOX, SENT, etc.)
- `EmailAddress.kt` - Email address parser
- `Attachment.kt` - Attachment model
**Dependencies:** None
**Status:** ✅ Complete
---
#### :yakki-mail:core:protocol
**Purpose:** IMAP/SMTP/POP3 protocol implementation.
**Technologies:**
- Jakarta Mail 2.0.1
- Kotlin Coroutines for async operations
**Size:** ~600 LOC
**Key Components:**
- `ImapClient.kt` - IMAP client structure
- `SmtpClient.kt` - SMTP client structure
- `Pop3Client.kt` - POP3 client (optional)
- Folder management
- Message fetching
- Sending emails
**Dependencies:**
- `:yakki-mail:core:models`
**Status:** ⚠️ Structure Only
**Technical Debt:**
```
🟠 HIGH - Attachment handling
├─ Issue: TODO: Attachment handling not implemented
├─ Location: SmtpClient.kt:186
└─ Fix Time: 2-3 days
```
---
#### :yakki-mail:core:auth
**Purpose:** OAuth2 + Basic authentication.
**Size:** ~200 LOC
**Key Components:**
- `OAuth2Flow.kt` - OAuth2 authorization flow
- `BasicAuthProvider.kt` - Basic auth
**Dependencies:**
- `:yakki-mail:core:models`
**Status:** ⚠️ Structure Only
**Missing:** OAuth2 flow implementation
---
#### :yakki-mail:core:security
**Purpose:** Integration with :smartrag3:security.
**Size:** ~400 LOC
**Key Components:**
- `MailCredentialManager.kt` - Secure credentials storage
- `AccountKeystore.kt` - Android Keystore integration
- Biometric authentication support
**Dependencies:**
- `:yakki-mail:core:models`
- `:smartrag3:security`
**Status:** ✅ Complete
---
### Yakki Mail - Summary
**Status:** Backend structure created, UI not started
**Compilation:** ✅ BUILD SUCCESSFUL
**Implemented Features:**
- ✅ Email, Account, Folder models
- ✅ ImapClient structure (Jakarta Mail 2.0.1)
- ✅ SmtpClient structure
- ✅ MailCredentialManager
- ✅ AccountKeystore with biometric support
- ✅ Integration with :smartrag3:security
**Missing Features:**
- ❌ UI screens (not implemented)
- ❌ Room cache (not implemented)
- ❌ OAuth2 flow (not implemented)
- ❌ Push notifications (IMAP IDLE)
- ❌ HTML rendering
- ❌ Attachment handling
**Technical Debt:**
```
🟠 HIGH - Missing UI Layer
├─ Issue: Complete UI layer not started
├─ Scope: Email list, compose, detail, account setup screens
└─ Fix Time: 6-9 weeks (Phase 2-4 development plan)
🟠 HIGH - Attachment handling
├─ Issue: Attachment handling not implemented
├─ Location: SmtpClient.kt:186
└─ Fix Time: 2-3 days
```
**Development Plan (4 phases):**
- Phase 1: Backend Core ✅ Structure created
- Phase 2: UI Foundation ❌ Not started
- Phase 3: Advanced Features ❌ Not started
- Phase 4: Publishing & Polish ❌ Not started
**Goal:** Standalone library + UI for YAKKI app
---
### :yakkibluetooth:* - Bluetooth LE Audio (2 modules)
**Purpose:** Bluetooth LE Audio support (Android 13+).
**Total Size:** ~4,000 LOC
**Status:** 45% readiness (Partial implementation)
---
#### :yakkibluetooth:core
**Purpose:** Base Bluetooth functionality.
**Size:** ~2,000 LOC
**Key Components:**
- `ModernBluetoothDevice.kt` - Modern Bluetooth device wrapper
- `BluetoothScanner.kt` - LE device scanner
- `BluetoothPermissionHelper.kt` - Permission handling
- `BluetoothDeviceExt.kt` - Extensions
**Dependencies:** None
**Status:** ✅ Functional
---
#### :yakkibluetooth:leaudio
**Purpose:** LE Audio support (CIS, BIS, Auracast).
**Size:** ~2,000 LOC
**Key Components:**
- `LeAudioDevice.kt` - LE Audio device models
- `CISManager.kt` - Connected Isochronous Stream manager
- `BISManager.kt` - Broadcast Isochronous Stream manager
- `AuracastManager.kt` - Auracast broadcast manager
- `LeAudioProfiles.kt` - BAP, TMAP, HAP, CSIP profiles
**Dependencies:**
- `:yakkibluetooth:core`
**Status:** ⚠️ Structure Only (LE Audio stubs)
**Technical Debt:**
```
🟠 HIGH - LE Audio Stubs (15 TODO markers)
├─ Issue: CIS/BIS/Auracast not implemented, only structure exists
├─ Examples: CISManager.kt:36,52 | BISManager.kt:41,57,74 | AuracastManager.kt:290,300,311,319,320
├─ Impact: LE Audio features advertised but non-functional
└─ Fix Time: 3-4 weeks OR mark as experimental
```
**Examples:**
- TODO: Implement actual CIS establishment (CISManager.kt:36, 52)
- TODO: Implement actual BIG creation (BISManager.kt:41, 57, 74)
- TODO: Start BLE advertising (AuracastManager.kt:290, 300)
- TODO: Parse broadcast metadata (AuracastManager.kt:311, 319, 320)
- TODO: Handle LE Audio characteristics (LeAudioDevice.kt:263)
**Impact:** LE Audio features advertised but non-functional
**Recommendation:** Complete implementation OR clearly mark as experimental
**Requirements:** Android LE Audio stack expertise
---
### YakkiBluetooth - Summary
**Compilation:** ✅ BUILD SUCCESSFUL
**Implemented Features:**
- ✅ LeAudio device models and profiles
- ✅ CIS/BIS manager structures
- ✅ Auracast manager (structure)
- ✅ Bluetooth scanner with LE Audio detection
- ✅ Modern Bluetooth device wrapper
- ✅ Audio sharing manager (structure)
- ✅ Companion device unlock manager (structure)
**Missing Features:**
- ❌ Actual CIS establishment (leaudio/streams/CISManager.kt)
- ❌ Actual BIG creation/synchronization (leaudio/streams/BISManager.kt)
- ❌ BLE advertising implementation (leaudio/auracast/AuracastManager.kt)
- ❌ GATT characteristics handling (leaudio/LeAudioDevice.kt)
- ❌ Watch unlock trigger (companion/unlock/WatchUnlockManager.kt)
---
### :latency - Latency Measurement
**Purpose:** HTTP latency measurement (TTFB - Time To First Byte).
**Technologies:**
- OkHttp3
- Kotlin Coroutines
**Size:** ~800 LOC
**Key Components:**
- `LatencyMeasurer.kt` - Main API
- `TTFBProbe.kt` - TTFB measurement
- `NetworkTimings.kt` - Network timing breakdown
- `StatisticsEngine.kt` - Statistical analysis (mean, median, p95, p99)
- `AnomalyDetector.kt` - Anomaly detection
**Models:**
- `LatencyResult.kt` - Measurement result
- `LatencyStats.kt` - Statistics
- `MeasurementConfig.kt` - Configuration
**Dependencies:** None
**Readiness Status:** 90% (Production-ready)
**Compilation:** ✅ BUILD SUCCESSFUL
**Usage:**
- Used by `:conductor` for server selection
- Real-time metrics collection
- Region-based routing
**Technical Debt:** None
---
### :llmorchestrator - LLM Orchestration
**Purpose:** Advanced LLM orchestration and routing.
**Size:** ~500 LOC
**Key Components:**
- `LLMOrchestrator.kt` - Main orchestrator (structure)
- `AgentConfig.kt` - Agent configuration models
**Dependencies:** None (planned: :smartrag3:*)
**Readiness Status:** 60% (Structure only)
**Technical Debt:**
```
🟡 MEDIUM - Partial Implementation (4 TODO markers)
├─ Issue: SmartRAG integration and translation worker not implemented
├─ Locations: LLMOrchestrator.kt:24, 99, 115, 157
└─ Fix Time: 2-3 weeks OR deprecate module
```
**Examples:**
- TODO: Add SmartRAG (LLMOrchestrator.kt:24)
- TODO: Implement RAG search (LLMOrchestrator.kt:99, 157)
- TODO: Implement translation worker (LLMOrchestrator.kt:115)
**Compilation:** ✅ BUILD SUCCESSFUL
**Recommendation:** Complete implementation OR deprecate module
---
### :archivelib - Archive Operations
**Purpose:** Universal archive library (ZIP archiving/unarchiving, standalone).
**Technologies:**
- Java ZIP API
- Kotlin Coroutines
**Size:** ~300 LOC
**Key Components:**
- `ZipUnarchiver.kt` - ZIP extraction
- Zip bomb protection
- Size quotas
- Proper error handling
**Dependencies:** None
**Readiness Status:** 95% (Production-ready)
**Compilation:** ✅ BUILD SUCCESSFUL
**Usage:**
- Used by `:smartrag3:data` for ZIP backup (RAGMigrationManager)
**Technical Debt:** None
---
### :readability - Content Extraction
**Purpose:** Web article extraction (Readability4J wrapper).
**Technologies:**
- Readability4J (Mozilla Readability algorithm)
**Size:** ~1,000 LOC
**Key Components:**
- `ArticleExtractor.kt` - Main extractor
- HTML to clean text conversion
- Metadata extraction (partial)
**Dependencies:** None
**Readiness Status:** 80% (Functional)
**Compilation:** ✅ BUILD SUCCESSFUL
**Missing Features:**
- ❌ Full metadata extraction
**Technical Debt:** None
---
### :smartrag-v2 - Legacy RAG (DEPRECATED)
**Purpose:** Legacy RAG system (SQLite FTS5 + RustVectorEngine).
**Size:** ~1,500 LOC
**Key Components:**
- `SQLiteManager.kt` - SQLite FTS5 storage
- `RustVectorEngine.kt` - Vector search (NOT IMPLEMENTED)
- `EmbeddingCache.kt` - Embedding cache (structure)
- `SearchStrategies.kt` - Search strategies (structure)
**Dependencies:** None
**Readiness Status:** 15% (Deprecated placeholder)
**Technical Debt:**
```
🔴 CRITICAL - NotImplementedError (6 methods)
├─ Issue: RustVectorEngine throws NotImplementedError for all vector operations
├─ Impact: Vector search completely non-functional
├─ Solution: DEPRECATE - Remove after :smartrag3 migration
└─ Fix Time: N/A (deprecated, remove module entirely)
```
**Impact:** Vector search completely non-functional
**Recommendation:** **DEPRECATE** - Remove after :smartrag3 migration complete (1 week migration time)
**Compilation:** ✅ BUILD SUCCESSFUL (but non-functional)
---
## DEPENDENCY MATRIX
### Module → Dependencies
```
📦 :app (10+ dependencies)
├─ :conductor
├─ :latency
├─ :smartrag3:* (multiple modules)
├─ :docparser:core
└─ :yakkibluetooth:core
📦 :conductor (2 dependencies)
├─ :latency
└─ :smartrag3:core (optional)
📦 :smartrag3:core (0 dependencies)
└─ None (base module)
📦 :smartrag3:common (0 dependencies)
└─ None (base module)
📦 :smartrag3:domain (2 dependencies)
├─ :smartrag3:core
└─ :smartrag3:common
📦 :smartrag3:data (4 dependencies)
├─ :smartrag3:core
├─ :smartrag3:common
├─ :smartrag3:domain
└─ :archivelib
📦 :smartrag3:di (5 dependencies)
├─ :smartrag3:data
├─ :smartrag3:domain
├─ :smartrag3:embeddings
├─ :smartrag3:language
└─ :smartrag3:parsing
📦 :smartrag3:embeddings (2 dependencies)
├─ :smartrag3:core
└─ :smartrag3:common
📦 :smartrag3:language (2 dependencies)
├─ :smartrag3:core
└─ :smartrag3:common
📦 :smartrag3:parsing (3 dependencies)
├─ :smartrag3:core
├─ :smartrag3:common
└─ :docparser:core
📦 :smartrag3:ingestion (3 dependencies)
├─ :smartrag3:core
├─ :smartrag3:common
└─ :smartrag3:language
📦 :smartrag3:entities (1 dependency)
└─ :smartrag3:core
📦 :smartrag3:datasources (3 dependencies)
├─ :smartrag3:core
├─ :smartrag3:entities
└─ :smartrag3:ner
📦 :smartrag3:ner (2 dependencies)
├─ :smartrag3:core
└─ :smartrag3:entities
📦 :smartrag3:security (1 dependency)
└─ :smartrag3:core
📦 :docparser:core (0 dependencies)
└─ None (base module)
📦 :docparser:pdf (1 dependency)
└─ :docparser:core
📦 :docparser:office (1 dependency)
└─ :docparser:core
📦 :yakki-mail:core:models (0 dependencies)
└─ None (base module)
📦 :yakki-mail:core:protocol (1 dependency)
└─ :yakki-mail:core:models
📦 :yakki-mail:core:auth (1 dependency)
└─ :yakki-mail:core:models
📦 :yakki-mail:core:security (2 dependencies)
├─ :yakki-mail:core:models
└─ :smartrag3:security
📦 :yakkibluetooth:core (0 dependencies)
└─ None (base module)
📦 :yakkibluetooth:leaudio (1 dependency)
└─ :yakkibluetooth:core
📦 :latency (0 dependencies)
└─ None (standalone utility)
📦 :llmorchestrator (0 dependencies)
└─ Planned: :smartrag3:* (not yet implemented)
📦 :archivelib (0 dependencies)
└─ None (standalone utility)
📦 :readability (0 dependencies)
└─ None (standalone utility)
📦 :smartrag-v2 (0 dependencies)
└─ DEPRECATED - Remove after :smartrag3 migration
```
### Dependency → Used By Modules
```
🔑 :smartrag3:core (12 modules depend on it)
├─ :app
├─ :conductor
├─ :smartrag3:domain
├─ :smartrag3:data
├─ :smartrag3:embeddings
├─ :smartrag3:language
├─ :smartrag3:parsing
├─ :smartrag3:ingestion
├─ :smartrag3:entities
├─ :smartrag3:datasources
├─ :smartrag3:ner
└─ :smartrag3:security
🔑 :smartrag3:common (6 modules depend on it)
├─ :smartrag3:domain
├─ :smartrag3:data
├─ :smartrag3:embeddings
├─ :smartrag3:language
├─ :smartrag3:parsing
└─ :smartrag3:ingestion
🔑 :docparser:core (4 modules depend on it)
├─ :app
├─ :smartrag3:parsing
├─ :docparser:pdf
└─ :docparser:office
🔑 :latency (2 modules depend on it)
├─ :app
└─ :conductor
🔑 :archivelib (1 module depends on it)
└─ :smartrag3:data
🔑 :smartrag3:security (1 module depends on it)
└─ :yakki-mail:core:security
```
---
## MODULE WORKING RECOMMENDATIONS
### 1. How to Add a New Module
#### Step 1: Create Structure
```bash
# Create directory
mkdir -p module-name/src/main/kotlin/com/yakkismart/modulename
# Create build.gradle.kts
touch module-name/build.gradle.kts
```
#### Step 2: Configure build.gradle.kts
```kotlin
plugins {
alias(libs.plugins.kotlin.android)
alias(libs.plugins.ksp) // If Hilt/Room needed
}
android {
namespace = "com.yakkismart.modulename"
compileSdk = 36
defaultConfig {
minSdk = 33
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
}
dependencies {
// Core dependencies
implementation(libs.androidx.core.ktx)
implementation(libs.kotlinx.coroutines.core)
// Add module-specific dependencies
// implementation(project(":other-module"))
}
```
#### Step 3: Add to settings.gradle.kts
```kotlin
include(":module-name")
```
#### Step 4: Sync project
```bash
./gradlew sync
```
### 2. How to Manage Versions
All dependency versions in **libs.versions.toml**:
```toml
[versions]
kotlin = "2.2.20"
agp = "8.13.0"
hilt = "2.57.2"
# ... other versions
[libraries]
androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidxCore" }
# ... other libraries
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
# ... other plugins
```
**Usage:**
```kotlin
dependencies {
implementation(libs.androidx.core.ktx)
implementation(libs.hilt.android)
ksp(libs.hilt.compiler)
}
```
### 3. Best Practices
#### 3.1. Naming Conventions
```
✅ GOOD:
:app # Main application
:feature-name # Feature module (kebab-case)
:library:submodule # Library with submodules
❌ BAD:
:AppModule # CamelCase not used
:feature_name # snake_case not used
```
#### 3.2. Module Structure
```
module-name/
├── src/
│ ├── main/
│ │ ├── kotlin/com/yakkismart/modulename/
│ │ │ ├── *.kt # Kotlin files
│ │ │ └── *.kt.md # MANDATORY documentation
│ │ ├── res/ # Resources (if needed)
│ │ └── AndroidManifest.xml # Manifest (if needed)
│ └── test/
│ └── kotlin/ # Unit tests
├── build.gradle.kts # Build script
└── README.md # Module README (optional)
```
#### 3.3. Documentation Requirements
**EVERY .kt file MUST have:**
1. **File Header:**
```kotlin
/**
* File: FileName.kt
* Path: module/src/main/kotlin/com/yakkismart/path/FileName.kt
* Ver: X.Y.Z | Date: YYYY-MM-DD
* Desc: [One sentence description]
*/
```
2. **Companion .md file** (same directory, same name):
```markdown
# FileName.kt
## Purpose
[What this file does]
## API
[Public functions, classes]
## Dependencies
[What it depends on]
## Usage Example
[How to use]
```
#### 3.4. Dependency Management
**Library modules:**
- ✅ Use Koin DI (don't impose Hilt on consumers)
- ✅ Minimal Android dependencies
- ✅ Standalone, reusable
**App module:**
- ✅ Use Hilt DI
- ✅ Depends on library modules
**Example:**
```kotlin
// Library module (:smartrag3:core) - Koin
val smartRAGModule = module {
single { RAGRepository(get()) }
}
// App module (:app) - Hilt
@Module
@InstallIn(SingletonComponent::class)
object AppModule {
@Provides
fun provideRAGRepository(...): RAGRepository = ...
}
```
#### 3.5. Testing
**Each module should have:**
- Unit tests (>70% coverage goal)
- Integration tests (where applicable)
**Example:**
```kotlin
// module/src/test/kotlin/ExampleTest.kt
@Test
fun `test feature works correctly`() {
// Given
val input = ...
// When
val result = feature.process(input)
// Then
assertEquals(expected, result)
}
```
### 4. Troubleshooting
#### Error: "Unresolved reference"
**Cause:** Module not added to settings.gradle.kts
**Solution:**
```kotlin
// settings.gradle.kts
include(":missing-module")
```
#### Error: "Circular dependency"
**Cause:** Modules depend on each other cyclically
**Solution:** Refactoring - create common base module
#### Error: "Duplicate class"
**Cause:** One class in multiple modules
**Solution:** Move to common module (e.g., :core or :common)
### 5. Module Migration Checklist
When migrating code to new module:
- [ ] Create module structure
- [ ] Add to settings.gradle.kts
- [ ] Configure build.gradle.kts
- [ ] Move .kt files
- [ ] Create .md documentation
- [ ] Update package names
- [ ] Update imports in dependent modules
- [ ] Add unit tests
- [ ] Sync & Build
- [ ] Verify runtime operation
---
## CONCLUSION
YAKKI SMART uses **modern multi-module architecture** with 32 modules:
✅ **Production Ready:**
- :app (82%) - Main application
- :conductor (87%) - Adaptive routing
- :docparser:* (95%) - Document parsing
- :latency (90%) - Latency measurement
- :archivelib (95%) - Archive utilities
- :readability (80%) - Content extraction
✅ **Partially Implemented:**
- :smartrag3:* (75%) - 15 modules compiled, need ONNX + app integration
- :yakkibluetooth:* (45%) - Core works, LE Audio stubs
- :yakki-mail:* (35%) - Backend structure, UI not started
- :llmorchestrator (60%) - Structure only
❌ **Deprecated:**
- :smartrag-v2 (15%) - Migrate to :smartrag3
**Overall Project Status:** 75% production readiness
**Recommended Next Steps:**
1. ✅ Fix hardcoded HF token (CRITICAL - 5 min)
2. ✅ Complete :smartrag3 app integration (2-3 days)
3. ✅ Test DeepInfra integration (1 hour)
4. Implement ONNX embeddings (2-3 weeks)
5. Complete :yakki-mail UI (6-9 weeks)
6. Implement LE Audio features (3-4 weeks)
7. Deprecate :smartrag-v2 (1 week)
---
**Document Created:** 2025-11-30
**Sources:**
- `docs/analysis/2025-11-30_project_audit_report.json`
- `FEATURES_STATUS.md`
- `settings.gradle.kts`
- Actual project structure (602 .kt files, ~65,000 LOC)
**Document Version:** 1.0