Architecture Overview

Pebbl follows modern Android development best practices with a clean, maintainable architecture.

Technology Stack

Core Android

Technology	Version	Purpose
Kotlin	2.0.21	Primary programming language
Android SDK	Min 24, Target 36	Platform framework
Jetpack Compose	2024.09.00	Declarative UI framework
Material 3	Latest	Design system

Architecture Components

Component	Version	Purpose
Room	2.6.1	Local SQLite database ORM
ViewModel	2.8.0	UI state management
Navigation Compose	2.7.7	Type-safe navigation
DataStore	1.1.1	Key-value preferences

Networking & AI

Library	Version	Purpose
Retrofit	2.9.0	HTTP client
OkHttp	4.12.0	HTTP engine & interceptors
Gson	2.10.1	JSON serialization

Speech Recognition

Library	Version	Purpose
Vosk SDK	0.3.38	Offline speech-to-text

Async & Reactive

Component	Version	Purpose
Kotlin Coroutines	1.8.0	Async/await pattern
Flow & StateFlow	Core	Reactive data streams

Build Tools

Tool	Version	Purpose
Gradle	8.13.0	Build system
KSP	2.0.21-1.0.29	Annotation processing for Room
AGP	8.5.1	Android Gradle Plugin

Project Structure

Pebbl/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/fouwaz/Pebbl/
│   │   │   │   ├── data/                    # Data Layer
│   │   │   │   │   ├── local/               # Local data sources
│   │   │   │   │   │   ├── entity/          # Room database entities
│   │   │   │   │   │   │   ├── ProjectEntity.kt
│   │   │   │   │   │   │   ├── VoiceStreamEntity.kt
│   │   │   │   │   │   │   ├── DraftEntity.kt
│   │   │   │   │   │   │   ├── LectureEntity.kt
│   │   │   │   │   │   │   ├── LectureOutputEntity.kt
│   │   │   │   │   │   │   └── AchievementEntity.kt
│   │   │   │   │   │   ├── dao/              # Data Access Objects
│   │   │   │   │   │   │   ├── ProjectDao.kt
│   │   │   │   │   │   │   ├── VoiceStreamDao.kt
│   │   │   │   │   │   │   ├── DraftDao.kt
│   │   │   │   │   │   │   ├── LectureDao.kt
│   │   │   │   │   │   │   ├── LectureOutputDao.kt
│   │   │   │   │   │   │   └── AchievementDao.kt
│   │   │   │   │   │   ├── preferences/      # DataStore preferences
│   │   │   │   │   │   └── VoiceStreamDatabase.kt
│   │   │   │   │   ├── remote/               # Remote data sources
│   │   │   │   │   │   ├── api/
│   │   │   │   │   │   │   └── OpenRouterService.kt
│   │   │   │   │   │   └── model/            # API models
│   │   │   │   │   │       ├── ChatRequest.kt
│   │   │   │   │   │       ├── ChatResponse.kt
│   │   │   │   │   │       └── ChatMessage.kt
│   │   │   │   │   └── repository/           # Repository implementations
│   │   │   │   │       └── AiRepository.kt
│   │   │   │   ├── domain/                   # Domain Layer
│   │   │   │   │   └── model/                # Domain models (UI-friendly)
│   │   │   │   │       ├── Project.kt
│   │   │   │   │       ├── FinalDraftConfig.kt
│   │   │   │   │       ├── PebbleType.kt
│   │   │   │   │       └── LectureOutputType.kt
│   │   │   │   ├── speech/                   # Speech Recognition
│   │   │   │   │   └── VoiceRecognitionManager.kt
│   │   │   │   ├── ui/                       # Presentation Layer
│   │   │   │   │   ├── screens/              # Compose screens
│   │   │   │   │   │   ├── ProjectListScreen.kt
│   │   │   │   │   │   ├── NewProjectScreen.kt
│   │   │   │   │   │   ├── VoiceSessionScreen.kt
│   │   │   │   │   │   ├── DraftViewScreen.kt
│   │   │   │   │   │   ├── LectureRecordingScreen.kt
│   │   │   │   │   │   ├── LectureOutputViewScreen.kt
│   │   │   │   │   │   ├── PebbleCollectionScreen.kt
│   │   │   │   │   │   └── WelcomeScreen.kt
│   │   │   │   │   ├── viewmodel/            # ViewModels
│   │   │   │   │   │   ├── ProjectViewModel.kt
│   │   │   │   │   │   ├── VoiceSessionViewModel.kt
│   │   │   │   │   │   ├── LectureRecordingViewModel.kt
│   │   │   │   │   │   └── LectureOutputViewModel.kt
│   │   │   │   │   ├── navigation/           # Navigation setup
│   │   │   │   │   │   ├── Screen.kt
│   │   │   │   │   │   └── Navigation.kt
│   │   │   │   │   ├── theme/                # Material 3 theming
│   │   │   │   │   │   ├── Color.kt
│   │   │   │   │   │   ├── Theme.kt
│   │   │   │   │   │   └── Type.kt
│   │   │   │   │   ├── components/           # Reusable UI components
│   │   │   │   │   │   ├── MilestoneCelebrationDialog.kt
│   │   │   │   │   │   └── RecentPebblesRow.kt
│   │   │   │   │   ├── share/                # Share functionality
│   │   │   │   │   └── util/                 # UI utilities
│   │   │   │   ├── MainActivity.kt
│   │   │   │   └── VoiceStreamApplication.kt
│   │   │   ├── res/                          # Resources
│   │   │   │   ├── drawable/                 # Icons, images
│   │   │   │   ├── values/
│   │   │   │   │   ├── strings.xml
│   │   │   │   │   ├── colors.xml
│   │   │   │   │   └── themes.xml
│   │   │   │   └── mipmap/                   # App icons
│   │   │   ├── assets/                       # Static assets
│   │   │   │   └── vosk-model-small-en-us-0.15/  # Speech model
│   │   │   └── AndroidManifest.xml
│   │   └── test/                             # Unit tests
│   └── build.gradle.kts                      # App-level build config
├── gradle/                                   # Gradle wrapper
│   ├── libs.versions.toml                    # Version catalog
│   └── wrapper/
├── build.gradle.kts                          # Project-level build config
├── settings.gradle.kts                       # Settings
├── local.properties                          # API keys (not in VCS)
├── README.md
└── docs.md                                   # This file

Design Patterns

MVVM (Model-View-ViewModel)

Separation of Concerns

┌─────────────┐
│    View     │  Jetpack Compose UI
│  (Screen)   │  - Observes StateFlow
└──────┬──────┘  - Emits user events
       │
       ↓
┌─────────────┐
│  ViewModel  │  State Management
│             │  - Exposes StateFlow
└──────┬──────┘  - Business logic orchestration
       │
       ↓
┌─────────────┐
│ Repository  │  Data Abstraction
│             │  - Combines data sources
└──────┬──────┘  - Caching logic
       │
       ↓
┌─────────────┐
│    Model    │  Data Layer
│ (Entity/DAO)│  - Room database
└─────────────┘  - API services

Benefits:

• Testable business logic (ViewModels)

• Reactive UI updates (StateFlow)

• Lifecycle-aware components

• Clear data flow

Repository Pattern

Abstracts data sources from ViewModels:

class AiRepository(
    private val apiService: OpenRouterService
) {
    suspend fun generateFollowUpQuestions(
        transcribedText: String
    ): Result<List<String>> {
        return try {
            val response = apiService.chat(buildRequest(transcribedText))
            Result.success(parseQuestions(response))
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
}

Benefits:

• Single source of truth

• Easy to mock for testing

• Centralized error handling

• Can switch data sources without changing ViewModels

Sealed Classes for State

Type-safe state representation prevents impossible states:

sealed class LectureRecordingState {
    object Idle : LectureRecordingState()
    object Initializing : LectureRecordingState()
    object Ready : LectureRecordingState()
    object Recording : LectureRecordingState()
    object Paused : LectureRecordingState()
    object Processing : LectureRecordingState()
    data class GeneratingOutputs(val progress: Float) : LectureRecordingState()
    data class Complete(val lectureId: Long) : LectureRecordingState()
    data class Error(val message: String) : LectureRecordingState()
}

Benefits:

• Exhaustive when expressions

• Impossible to have invalid state combinations

• Clear state transitions

• Type-safe data associated with states

Dependency Injection (Manual)

Currently using manual DI via Application class:

class VoiceStreamApplication : Application() {
    val database: VoiceStreamDatabase by lazy {
        Room.databaseBuilder(
            applicationContext,
            VoiceStreamDatabase::class.java,
            "voice_stream_db"
        ).build()
    }
}

Access in Activities:

val db = (application as VoiceStreamApplication).database

Note: Consider migrating to Hilt/Dagger for larger-scale DI needs.