Technical Reference

Database Schema

Pebbl uses Room (SQLite) for local data persistence. Current version: 4

Entity Relationship Diagram

┌─────────────────┐
│  ProjectEntity  │
└────────┬────────┘
         │ 1
         │
         │ *
    ┌────┴────────────────────────┐
    │                             │
    ↓                             ↓
┌────────────────┐        ┌──────────────┐
│VoiceStream     │        │ DraftEntity  │
│Entity          │        └──────────────┘
└────────────────┘

┌─────────────────┐
│ LectureEntity   │
└────────┬────────┘
         │ 1
         │
         │ *
         ↓
┌──────────────────┐
│LectureOutput     │
│Entity            │
└──────────────────┘

┌──────────────────┐
│Achievement       │
│Entity            │
└──────────────────┘

Entities

ProjectEntity

Represents a writing project or assignment.

@Entity(tableName = "projects")
data class ProjectEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val title: String,

    val tags: String = "",  // Comma-separated

    val description: String = "",

    val courseId: String? = null,

    val linkedLectureIds: String = "",  // Comma-separated Long IDs

    val createdAt: Long = System.currentTimeMillis(),

    val updatedAt: Long = System.currentTimeMillis(),

    val isActive: Boolean = true
)

Indexes: None currently (consider adding index on isActive for filtering)

VoiceStreamEntity

Stores conversation exchanges in a voice session.

@Entity(
    tableName = "voice_streams",
    foreignKeys = [
        ForeignKey(
            entity = ProjectEntity::class,
            parentColumns = ["id"],
            childColumns = ["projectId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index("projectId")]
)
data class VoiceStreamEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val projectId: Long,

    val transcribedText: String,

    val aiQuestion1: String? = null,
    val aiQuestion2: String? = null,
    val aiQuestion3: String? = null,

    val selectedQuestionIndex: Int? = null,

    val sequenceNumber: Int,

    val timestamp: Long = System.currentTimeMillis()
)

Foreign Keys: Cascading delete when project deleted Indexes: projectId for efficient queries

DraftEntity

Stores generated academic drafts with versioning.

@Entity(
    tableName = "drafts",
    foreignKeys = [
        ForeignKey(
            entity = ProjectEntity::class,
            parentColumns = ["id"],
            childColumns = ["projectId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index("projectId")]
)
data class DraftEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val projectId: Long,

    val content: String,

    val version: Int = 1,

    val createdAt: Long = System.currentTimeMillis(),

    val updatedAt: Long = System.currentTimeMillis(),

    val isCurrent: Boolean = true
)

Versioning: Each generation creates new version, previous marked isCurrent = false

LectureEntity

Represents a recorded lecture with transcription.

@Entity(tableName = "lectures")
data class LectureEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val title: String,

    val transcription: String,

    val durationSeconds: Int,

    val wordCount: Int,

    val courseId: String? = null,

    val projectId: Long? = null,

    val audioUrl: String? = null,  // Future: path to audio file

    val recordedAt: Long = System.currentTimeMillis()
)

LectureOutputEntity

Stores AI-generated outputs for lectures.

@Entity(
    tableName = "lecture_outputs",
    foreignKeys = [
        ForeignKey(
            entity = LectureEntity::class,
            parentColumns = ["id"],
            childColumns = ["lectureId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index("lectureId")]
)
data class LectureOutputEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val lectureId: Long,

    val outputType: LectureOutputType,  // OVERVIEW, NOTES, SUMMARY, FLASHCARDS

    val content: String,

    val createdAt: Long = System.currentTimeMillis()
)

Output Types:

enum class LectureOutputType {
    OVERVIEW,
    NOTES,
    SUMMARY,
    FLASHCARDS,
    DETAILED_NOTES
}

AchievementEntity

Tracks unlocked achievements/pebbles.

@Entity(tableName = "achievements")
data class AchievementEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,

    val type: PebbleType,

    val unlockedAt: Long = System.currentTimeMillis(),

    val totalCount: Int = 1  // Can unlock same achievement multiple times
)

Database Migrations

Version 1 → 2: Added LectureEntity and LectureOutputEntity

Version 2 → 3: Added AchievementEntity, courseId to projects/lectures

Version 3 → 4: Added linkedLectureIds to ProjectEntity

API Integration

OpenRouter Service

Pebbl uses OpenRouter as a unified gateway to access AI models.

Configuration

object RetrofitClient {
    private const val BASE_URL = "https://openrouter.ai/api/v1/"

    private val okHttpClient = OkHttpClient.Builder()
        .addInterceptor { chain ->
            val request = chain.request().newBuilder()
                .addHeader("Authorization", "Bearer ${BuildConfig.OPENROUTER_API_KEY}")
                .addHeader("HTTP-Referer", "https://Pebbl.app")
                .addHeader("X-Title", "Pebbl")
                .build()
            chain.proceed(request)
        }
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .writeTimeout(30, TimeUnit.SECONDS)
        .build()

    val apiService: OpenRouterService = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .client(okHttpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build()
        .create(OpenRouterService::class.java)
}

Service Interface

interface OpenRouterService {
    @POST("chat/completions")
    suspend fun chat(@Body request: ChatRequest): ChatResponse
}

Request Model

data class ChatRequest(
    val model: String,
    val messages: List<ChatMessage>,
    val temperature: Double = 0.7,
    @SerializedName("max_tokens")
    val maxTokens: Int? = null,
    @SerializedName("top_p")
    val topP: Double? = null,
    @SerializedName("frequency_penalty")
    val frequencyPenalty: Double? = null,
    @SerializedName("presence_penalty")
    val presencePenalty: Double? = null
)

data class ChatMessage(
    val role: String,  // "system", "user", "assistant"
    val content: String
)

Response Model

data class ChatResponse(
    val id: String,
    val model: String,
    val created: Long,
    val choices: List<ChatChoice>,
    val usage: Usage?
)

data class ChatChoice(
    val index: Int,
    val message: ChatMessage,
    @SerializedName("finish_reason")
    val finishReason: String
)

data class Usage(
    @SerializedName("prompt_tokens")
    val promptTokens: Int,
    @SerializedName("completion_tokens")
    val completionTokens: Int,
    @SerializedName("total_tokens")
    val totalTokens: Int
)

Error Handling

sealed class ApiResult<out T> {
    data class Success<T>(val data: T) : ApiResult<T>()
    data class Error(val exception: Exception) : ApiResult<Nothing>()
    object Loading : ApiResult<Nothing>()
}

// Usage in repository
suspend fun safeApiCall(
    apiCall: suspend () -> ChatResponse
): ApiResult<String> {
    return try {
        ApiResult.Loading
        val response = apiCall()
        if (response.error != null) {
            ApiResult.Error(Exception(response.error.message))
        } else {
            ApiResult.Success(response.choices.first().message.content)
        }
    } catch (e: HttpException) {
        ApiResult.Error(Exception("HTTP ${e.code()}: ${e.message()}"))
    } catch (e: IOException) {
        ApiResult.Error(Exception("Network error: ${e.message}"))
    } catch (e: Exception) {
        ApiResult.Error(e)
    }
}

AI Model

Model Used: google/gemini-2.5-flash-lite

Characteristics:

• Fast response times (1-3 seconds)

• Cost-effective

• Good instruction following

• Supports long context (up to 32K tokens)

Alternative Models (can be configured):

• google/gemini-2.5-pro - Higher quality, slower

• anthropic/claude-3-haiku - Fast, concise

• openai/gpt-4o-mini - Balanced quality/speed

API Call Examples

Generate Follow-Up Questions

suspend fun generateFollowUpQuestions(
    transcribedText: String
): Result<List<String>> {
    val request = ChatRequest(
        model = "google/gemini-2.5-flash-lite",
        messages = listOf(
            ChatMessage(
                role = "system",
                content = """You are a thoughtful academic assistant helping
                students deepen their thinking through strategic questions."""
            ),
            ChatMessage(
                role = "user",
                content = """Based on this student's initial thoughts:

                "$transcribedText"

                Generate exactly 3 follow-up questions that:
                1. Probe deeper into their main argument
                2. Challenge assumptions or explore counterarguments
                3. Ask for specific evidence or examples

                Format: Return ONLY the 3 questions, numbered 1-3,
                one per line."""
            )
        ),
        temperature = 0.6,
        maxTokens = 300
    )

    return try {
        val response = apiService.chat(request)
        val content = response.choices.first().message.content
        val questions = parseQuestions(content)
        Result.success(questions)
    } catch (e: Exception) {
        Result.failure(e)
    }
}

Generate Draft

suspend fun generateDraft(
    conversation: List<Pair<String, String?>>,
    config: FinalDraftConfig
): Result<String> {
    val conversationText = buildConversationString(conversation)

    val systemPrompt = when (config.tone) {
        DraftTone.ACADEMIC -> "You are an academic writing assistant..."
        DraftTone.NEUTRAL -> "You are a neutral writing assistant..."
        DraftTone.CONVERSATIONAL -> "You are a friendly writing assistant..."
    }

    val request = ChatRequest(
        model = "google/gemini-2.5-flash-lite",
        messages = listOf(
            ChatMessage(role = "system", content = systemPrompt),
            ChatMessage(
                role = "user",
                content = """Convert this conversation into a ${config.wordGoal}-word
                essay with ${config.refinementLevel} refinement:

                $conversationText

                ${if (config.includeSummary) "Include a summary section." else ""}
                ${if (config.includeHighlights) "Include key takeaways." else ""}
                """
            )
        ),
        temperature = 0.2,  // Lower for more consistent output
        maxTokens = (config.wordGoal * 1.5).toInt()  // Words * ~1.5 tokens/word
    )

    return try {
        val response = apiService.chat(request)
        Result.success(response.choices.first().message.content)
    } catch (e: Exception) {
        Result.failure(e)
    }
}

Voice Recognition

Pebbl uses Vosk for offline speech recognition, ensuring privacy and no internet dependency during recording.

Vosk Model

Model: vosk-model-small-en-us-0.15

• Size: ~40MB

• Language: US English

• Accuracy: ~85-90% in quiet environments

• Speed: Real-time on most devices

Alternative Models (can be downloaded separately):

• vosk-model-en-us-0.22 (Large, 1.8GB, higher accuracy)

• vosk-model-small-en-in-0.4 (Indian English)

• Other languages available on Vosk website

VoiceRecognitionManager

Core class managing speech recognition lifecycle.

Initialization

class VoiceRecognitionManager(
    private val context: Context
) {
    private var model: Model? = null
    private var recognizer: Recognizer? = null
    private var audioRecorder: AudioRecord? = null

    suspend fun initialize(): Boolean = withContext(Dispatchers.IO) {
        try {
            // Extract model from assets to files dir
            val modelPath = extractModelFromAssets()

            // Load Vosk model
            StorageService.unpack(
                context.assets,
                "vosk-model-small-en-us-0.15",
                modelPath,
                { /* progress callback */ }
            )

            model = Model(modelPath)
            recognizer = Recognizer(model, 16000.0f)

            true
        } catch (e: Exception) {
            Log.e("VoiceRecognition", "Initialization failed", e)
            false
        }
    }
}

Recording

fun startListening(
    onPartialResult: (String) -> Unit,
    onFinalResult: (String) -> Unit,
    onAmplitude: (Float) -> Unit
) {
    val bufferSize = AudioRecord.getMinBufferSize(
        16000,
        AudioFormat.CHANNEL_IN_MONO,
        AudioFormat.ENCODING_PCM_16BIT
    )

    audioRecorder = AudioRecord(
        MediaRecorder.AudioSource.MIC,
        16000,
        AudioFormat.CHANNEL_IN_MONO,
        AudioFormat.ENCODING_PCM_16BIT,
        bufferSize
    )

    audioRecorder?.startRecording()

    CoroutineScope(Dispatchers.IO).launch {
        val buffer = ShortArray(bufferSize)

        while (isRecording) {
            val read = audioRecorder?.read(buffer, 0, buffer.size) ?: 0

            if (read > 0) {
                // Calculate amplitude (RMS)
                val rms = calculateRMS(buffer, read)
                onAmplitude(rms)

                // Feed to recognizer
                val byteBuffer = shortArrayToByteArray(buffer)
                if (recognizer?.acceptWaveForm(byteBuffer, read) == true) {
                    val result = recognizer?.result
                    onFinalResult(parseResult(result))
                } else {
                    val partial = recognizer?.partialResult
                    onPartialResult(parsePartialResult(partial))
                }
            }
        }
    }
}

Amplitude Calculation (for visualization)

private fun calculateRMS(buffer: ShortArray, read: Int): Float {
    var sum = 0.0
    for (i in 0 until read) {
        val sample = buffer[i].toDouble()
        sum += sample * sample
    }
    val rms = sqrt(sum / read)

    // Normalize to 0-1 range
    return (rms / Short.MAX_VALUE).toFloat()
}

Cleanup

fun stopListening() {
    isRecording = false
    audioRecorder?.stop()
    audioRecorder?.release()
    audioRecorder = null
}

fun cleanup() {
    stopListening()
    recognizer?.close()
    model?.close()
    recognizer = null
    model = null
}

Permissions

Required in AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Runtime permission request in MainActivity.kt:

val recordAudioPermission = Manifest.permission.RECORD_AUDIO

if (checkSelfPermission(recordAudioPermission) != PackageManager.PERMISSION_GRANTED) {
    requestPermissions(arrayOf(recordAudioPermission), REQUEST_RECORD_AUDIO)
}

AI Models

Prompt Engineering

Pebbl uses carefully crafted prompts to ensure consistent, high-quality outputs.

Follow-Up Questions Prompt Template

val systemPrompt = """
You are a thoughtful academic assistant helping students deepen their thinking
through strategic follow-up questions. Your questions should:

1. Probe deeper into their main argument or thesis
2. Identify gaps in reasoning or missing evidence
3. Challenge assumptions constructively
4. Explore counterarguments or alternative perspectives
5. Encourage critical thinking

Always maintain an encouraging, non-judgmental tone.
"""

val userPrompt = """
A student spoke these initial thoughts on their topic:

"$transcribedText"

Generate exactly 3 follow-up questions that will help them develop
a stronger, more nuanced argument. Each question should:
- Be specific to their content (not generic)
- Open up a new dimension of thinking
- Be answerable in 1-2 minutes of speech

Format your response as exactly 3 numbered questions, one per line:
1. [First question]
2. [Second question]
3. [Third question]
"""

Draft Generation Prompt Template

val systemPrompt = when (tone) {
    DraftTone.ACADEMIC -> """
        You are an expert academic writing assistant. Transform student
        conversations into scholarly essays with:
        - Formal academic tone and vocabulary
        - Clear thesis statements
        - Well-structured paragraphs with topic sentences
        - Proper transitions between ideas
        - Evidence-based arguments
        - Appropriate citation placeholders [Citation needed]
    """

    DraftTone.NEUTRAL -> """
        You are a writing assistant. Transform student conversations into
        clear, balanced essays with:
        - Objective, informative tone
        - Logical organization
        - Clear explanations
        - Smooth flow between ideas
    """

    DraftTone.CONVERSATIONAL -> """
        You are a friendly writing assistant. Transform student conversations
        into engaging, approachable essays with:
        - Natural, conversational tone
        - Personal pronouns when appropriate
        - Engaging examples
        - Clear but informal language
    """
}

val refinementInstructions = when (refinementLevel) {
    RefinementLevel.LIGHT_POLISH -> """
        Maintain the student's original structure and ideas. Only:
        - Fix grammar and spelling
        - Improve sentence clarity
        - Ensure coherent flow
    """

    RefinementLevel.MODERATE -> """
        Improve structure while preserving core ideas:
        - Reorganize for better flow
        - Strengthen topic sentences
        - Add transitions
        - Clarify arguments
        - Remove redundancy
    """

    RefinementLevel.STRUCTURED -> """
        Fully restructure into polished academic essay:
        - Create strong introduction with clear thesis
        - Organize into logical sections
        - Develop comprehensive body paragraphs
        - Add compelling conclusion
        - Ensure sophisticated transitions
        - Maintain argumentative thread throughout
    """
}

val userPrompt = """
Convert this conversation between a student and AI assistant into
a ${wordGoal}-word essay:

$conversationText

Requirements:
- Target length: ${wordGoal} words (±10%)
- Tone: ${tone.name}
- Refinement: ${refinementLevel.name}
${if (includeSummary) "- Include: Executive summary at beginning" else ""}
${if (includeHighlights) "- Include: Key takeaways section at end" else ""}

$refinementInstructions

Return only the essay text, no meta-commentary.
"""

Lecture Output Prompts

Overview Prompt:

"""
Generate a concise overview (exactly 10-11 lines) of this lecture transcription:

"$transcription"

The overview should:
- Highlight main topics covered
- Identify key concepts introduced
- Note important themes or arguments
- Be scannable and easy to review quickly

Format as 10-11 complete sentences, each on its own line.
"""

Detailed Notes Prompt:

"""
Create comprehensive structured notes from this lecture transcription:

"$transcription"

Format the notes using markdown with:
- # Main Topics (h1 headings)
- ## Subtopics (h2 headings)
- ### Key Concepts (h3 headings)
- Bullet points for details
- **Bold** for important terms
- *Italics* for definitions

The notes should:
- Capture all important information
- Show relationships between concepts
- Be study-friendly and well-organized
- Include examples mentioned in the lecture

Return only the markdown-formatted notes.
"""

Summary Prompt:

"""
Write a comprehensive summary of this lecture:

"$transcription"

Structure your summary as:

1. **Main Theme**: One paragraph explaining the central focus

2. **Key Points**: 3-5 paragraphs, each covering a major topic with:
   - Clear explanation
   - Supporting details
   - Examples from the lecture

3. **What This Means**: Reflection paragraph explaining significance and
   how concepts connect

4. **Takeaways**: 3-5 bullet points of most important lessons

Use clear, student-friendly language. Return only the summary.
"""

Flashcards Prompt:

"""
Create study flashcards from this lecture transcription:

"$transcription"

Generate 10-15 flashcard pairs in this format:

Q: [Question testing comprehension, not just recall]
A: [Clear, concise answer]

---

Q: [Next question]
A: [Next answer]

Questions should:
- Test understanding, not just memorization
- Cover key concepts from the lecture
- Vary in difficulty
- Be specific to lecture content
- Use clear, unambiguous phrasing

Return only the flashcard pairs in the format above.
"""

---

Component Reference

ViewModels

ViewModels manage UI state and business logic, surviving configuration changes.

ProjectViewModel

Manages project list and CRUD operations.

File: ui/viewmodel/ProjectViewModel.kt

State:

data class ProjectListState(
    val projects: List<Project> = emptyList(),
    val isLoading: Boolean = false,
    val error: String? = null
)

Public API:

class ProjectViewModel(
    private val projectDao: ProjectDao,
    private val draftDao: DraftDao
) : ViewModel() {

    val state: StateFlow<ProjectListState>

    fun loadProjects()

    fun createProject(title: String, tags: String): Long

    fun deleteProject(projectId: Long)

    fun updateProject(project: Project)
}

Usage Example:

@Composable
fun ProjectListScreen(
    viewModel: ProjectViewModel = viewModel()
) {
    val state by viewModel.state.collectAsState()

    LaunchedEffect(Unit) {
        viewModel.loadProjects()
    }

    when {
        state.isLoading -> LoadingIndicator()
        state.error != null -> ErrorMessage(state.error!!)
        else -> ProjectList(state.projects)
    }
}

VoiceSessionViewModel

Manages voice recording and conversation flow for essay development.

File: ui/viewmodel/VoiceSessionViewModel.kt

State:

data class VoiceSessionState(
    val isRecording: Boolean = false,
    val currentTranscription: String = "",
    val conversationHistory: List<VoiceStreamEntity> = emptyList(),
    val aiQuestions: List<String> = emptyList(),
    val isGeneratingQuestions: Boolean = false,
    val error: String? = null
)

Public API:

class VoiceSessionViewModel(
    private val voiceStreamDao: VoiceStreamDao,
    private val aiRepository: AiRepository,
    private val voiceRecognitionManager: VoiceRecognitionManager
) : ViewModel() {

    val state: StateFlow<VoiceSessionState>

    suspend fun initialize()

    fun startRecording()

    fun stopRecording()

    suspend fun generateFollowUpQuestions()

    fun selectQuestion(index: Int)

    suspend fun saveExchange()
}

LectureRecordingViewModel

Manages lecture recording, transcription, and AI output generation.

File: ui/viewmodel/LectureRecordingViewModel.kt

State:

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()
}

data class LectureRecordingUiState(
    val recordingState: LectureRecordingState = LectureRecordingState.Idle,
    val transcription: String = "",
    val duration: Int = 0,  // seconds
    val amplitude: Float = 0f
)

Public API:

class LectureRecordingViewModel(
    private val lectureDao: LectureDao,
    private val lectureOutputDao: LectureOutputDao,
    private val aiRepository: AiRepository,
    private val voiceRecognitionManager: VoiceRecognitionManager
) : ViewModel() {

    val uiState: StateFlow<LectureRecordingUiState>

    suspend fun initializeRecording()

    fun startRecording()

    fun pauseRecording()

    fun resumeRecording()

    suspend fun stopRecording(): Long  // Returns lectureId

    private suspend fun generateAllOutputs(lectureId: Long)
}

State Flow:

Idle → Initializing → Ready → Recording ⇄ Paused → Processing
→ GeneratingOutputs(0.0) → GeneratingOutputs(0.25) → ...
→ GeneratingOutputs(1.0) → Complete

LectureOutputViewModel

Manages display of lecture analysis outputs.

File: ui/viewmodel/LectureOutputViewModel.kt

State:

data class LectureOutputState(
    val lecture: LectureEntity? = null,
    val overview: String = "",
    val notes: String = "",
    val summary: String = "",
    val flashcards: String = "",
    val selectedTab: Int = 0,  // 0=Overview, 1=Notes, 2=Summary, 3=Flashcards
    val isLoading: Boolean = false
)

Public API:

class LectureOutputViewModel(
    private val lectureDao: LectureDao,
    private val lectureOutputDao: LectureOutputDao
) : ViewModel() {

    val state: StateFlow<LectureOutputState>

    fun loadLecture(lectureId: Long)

    fun selectTab(tabIndex: Int)
}

Repositories

AiRepository

Central repository for all AI API calls.

File: data/repository/AiRepository.kt

Constructor:

class AiRepository(
    private val apiService: OpenRouterService
) {
    private val model = "google/gemini-2.5-flash-lite"
}

Methods:

// Generate 3 follow-up questions
suspend fun generateFollowUpQuestions(
    transcribedText: String
): Result<List<String>>

// Convert conversation to essay
suspend fun generateDraft(
    conversation: List<Pair<String, String?>>,
    config: FinalDraftConfig
): Result<String>

// Generate all lecture outputs in one call
suspend fun generateAllOutputs(
    transcription: String
): Result<LectureOutputs>

// Individual lecture output methods
suspend fun generateOverview(transcription: String): Result<String>
suspend fun generateNotes(transcription: String): Result<String>
suspend fun generateSummary(transcription: String): Result<String>
suspend fun generateFlashcards(transcription: String): Result<String>
suspend fun generateDetailedNotes(transcription: String): Result<String>

Data Classes:

data class LectureOutputs(
    val overview: String,
    val notes: String,
    val summary: String,
    val flashcards: String = ""
)

data class FinalDraftConfig(
    val wordGoal: Int = 500,
    val tone: DraftTone = DraftTone.ACADEMIC,
    val refinementLevel: RefinementLevel = RefinementLevel.MODERATE,
    val includeSummary: Boolean = false,
    val includeHighlights: Boolean = false
)

enum class DraftTone {
    NEUTRAL,
    ACADEMIC,
    CONVERSATIONAL
}

enum class RefinementLevel {
    LIGHT_POLISH,
    MODERATE,
    STRUCTURED
}

Error Handling:

private suspend fun <T> safeApiCall(
    block: suspend () -> T
): Result<T> {
    return try {
        Result.success(block())
    } catch (e: HttpException) {
        Result.failure(Exception("HTTP ${e.code()}: ${e.message()}"))
    } catch (e: IOException) {
        Result.failure(Exception("Network error: Check connection"))
    } catch (e: Exception) {
        Result.failure(e)
    }
}

DAOs

Data Access Objects provide type-safe database queries.

ProjectDao

File: data/local/dao/ProjectDao.kt

@Dao
interface ProjectDao {
    @Query("SELECT * FROM projects WHERE isActive = 1 ORDER BY updatedAt DESC")
    fun getAllActiveProjects(): Flow<List<ProjectEntity>>

    @Query("SELECT * FROM projects WHERE id = :id")
    suspend fun getProjectById(id: Long): ProjectEntity?

    @Insert
    suspend fun insertProject(project: ProjectEntity): Long

    @Update
    suspend fun updateProject(project: ProjectEntity)

    @Delete
    suspend fun deleteProject(project: ProjectEntity)

    @Query("UPDATE projects SET isActive = 0 WHERE id = :id")
    suspend fun archiveProject(id: Long)
}

VoiceStreamDao

File: data/local/dao/VoiceStreamDao.kt

@Dao
interface VoiceStreamDao {
    @Query("SELECT * FROM voice_streams WHERE projectId = :projectId ORDER BY sequenceNumber ASC")
    fun getStreamsByProject(projectId: Long): Flow<List<VoiceStreamEntity>>

    @Query("SELECT MAX(sequenceNumber) FROM voice_streams WHERE projectId = :projectId")
    suspend fun getMaxSequenceNumber(projectId: Long): Int?

    @Insert
    suspend fun insertStream(stream: VoiceStreamEntity): Long

    @Update
    suspend fun updateStream(stream: VoiceStreamEntity)

    @Query("DELETE FROM voice_streams WHERE projectId = :projectId")
    suspend fun deleteAllForProject(projectId: Long)
}

DraftDao

File: data/local/dao/DraftDao.kt

@Dao
interface DraftDao {
    @Query("SELECT * FROM drafts WHERE projectId = :projectId AND isCurrent = 1 LIMIT 1")
    suspend fun getCurrentDraft(projectId: Long): DraftEntity?

    @Query("SELECT * FROM drafts WHERE projectId = :projectId ORDER BY version DESC")
    fun getAllDrafts(projectId: Long): Flow<List<DraftEntity>>

    @Transaction
    suspend fun insertNewDraft(draft: DraftEntity) {
        // Mark all existing drafts as not current
        markAllAsNotCurrent(draft.projectId)
        // Insert new draft
        insertDraft(draft)
    }

    @Query("UPDATE drafts SET isCurrent = 0 WHERE projectId = :projectId")
    suspend fun markAllAsNotCurrent(projectId: Long)

    @Insert
    suspend fun insertDraft(draft: DraftEntity): Long
}

LectureDao

File: data/local/dao/LectureDao.kt

@Dao
interface LectureDao {
    @Query("SELECT * FROM lectures ORDER BY recordedAt DESC")
    fun getAllLectures(): Flow<List<LectureEntity>>

    @Query("SELECT * FROM lectures WHERE id = :id")
    suspend fun getLectureById(id: Long): LectureEntity?

    @Query("SELECT * FROM lectures WHERE projectId = :projectId")
    fun getLecturesByProject(projectId: Long): Flow<List<LectureEntity>>

    @Insert
    suspend fun insertLecture(lecture: LectureEntity): Long

    @Delete
    suspend fun deleteLecture(lecture: LectureEntity)
}

LectureOutputDao

File: data/local/dao/LectureOutputDao.kt

@Dao
interface LectureOutputDao {
    @Query("SELECT * FROM lecture_outputs WHERE lectureId = :lectureId")
    fun getOutputsForLecture(lectureId: Long): Flow<List<LectureOutputEntity>>

    @Query("SELECT * FROM lecture_outputs WHERE lectureId = :lectureId AND outputType = :type LIMIT 1")
    suspend fun getOutputByType(lectureId: Long, type: LectureOutputType): LectureOutputEntity?

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertOutput(output: LectureOutputEntity): Long

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(outputs: List<LectureOutputEntity>)

    @Query("DELETE FROM lecture_outputs WHERE lectureId = :lectureId")
    suspend fun deleteAllForLecture(lectureId: Long)
}

AchievementDao

File: data/local/dao/AchievementDao.kt

@Dao
interface AchievementDao {
    @Query("SELECT * FROM achievements ORDER BY unlockedAt DESC")
    fun getAllAchievements(): Flow<List<AchievementEntity>>

    @Query("SELECT * FROM achievements WHERE type = :type LIMIT 1")
    suspend fun getAchievementByType(type: PebbleType): AchievementEntity?

    @Query("SELECT * FROM achievements ORDER BY unlockedAt DESC LIMIT :limit")
    fun getRecentAchievements(limit: Int = 3): Flow<List<AchievementEntity>>

    @Insert
    suspend fun unlockAchievement(achievement: AchievementEntity): Long

    @Transaction
    suspend fun incrementAchievement(type: PebbleType) {
        val existing = getAchievementByType(type)
        if (existing != null) {
            updateCount(type, existing.totalCount + 1)
        } else {
            unlockAchievement(AchievementEntity(type = type))
        }
    }

    @Query("UPDATE achievements SET totalCount = :newCount WHERE type = :type")
    suspend fun updateCount(type: PebbleType, newCount: Int)
}

UI Screens

ProjectListScreen

File: ui/screens/ProjectListScreen.kt

Purpose: Main home screen showing all projects

Features:

• List of all active projects

• Recent pebbles row at top

• Floating action button to create new project

• Project cards with title, tags, timestamps

• Actions: Start session, view draft, delete

Composable Signature:

@Composable
fun ProjectListScreen(
    viewModel: ProjectViewModel = viewModel(),
    onNavigateToNewProject: () -> Unit,
    onNavigateToVoiceSession: (Long) -> Unit,
    onNavigateToDraft: (Long) -> Unit,
    onNavigateToPebbles: () -> Unit
)

Key Components:

• RecentPebblesRow: Shows last 3 achievements

• ProjectCard: Individual project display

• DeleteConfirmationDialog: Confirm before deleting

VoiceSessionScreen

File: ui/screens/VoiceSessionScreen.kt

Purpose: Record thoughts and engage in AI conversation

Features:

• Large microphone button (start/stop recording)

• Live transcription display

• Three AI-generated questions

• Conversation history scrollable list

• Progress indicator during AI processing

Composable Signature:

@Composable
fun VoiceSessionScreen(
    projectId: Long,
    viewModel: VoiceSessionViewModel = viewModel(),
    onNavigateToD raft: (Long) -> Unit,
    onNavigateBack: () -> Unit
)

UI States:

• Idle: "Tap microphone to start"

• Recording: Animated mic icon, live text

• Processing: "AI is thinking..." with spinner

• Questions displayed: Three clickable cards

DraftViewScreen

File: ui/screens/DraftViewScreen.kt

Purpose: View and configure generated drafts

Features:

• Scrollable draft text display

• Configuration panel (expandable)

• Word goal slider

• Tone selector (chips or dropdown)

• Refinement level selector

• Optional sections checkboxes

• "Regenerate" button

• Export/share button

Composable Signature:

@Composable
fun DraftViewScreen(
    projectId: Long,
    viewModel: DraftViewModel = viewModel(),
    onNavigateBack: () -> Unit
)

Configuration Panel:

@Composable
fun DraftConfigPanel(
    config: FinalDraftConfig,
    onConfigChange: (FinalDraftConfig) -> Unit
) {
    Column {
        // Word goal slider
        Text("Word Goal: ${config.wordGoal}")
        Slider(
            value = config.wordGoal.toFloat(),
            onValueChange = { onConfigChange(config.copy(wordGoal = it.toInt())) },
            valueRange = 100f..5000f
        )

        // Tone selector
        ToneSelector(
            selected = config.tone,
            onSelect = { onConfigChange(config.copy(tone = it)) }
        )

        // Refinement level
        RefinementSelector(
            selected = config.refinementLevel,
            onSelect = { onConfigChange(config.copy(refinementLevel = it)) }
        )

        // Optional sections
        CheckboxRow("Include Summary", config.includeSummary) {
            onConfigChange(config.copy(includeSummary = it))
        }
        CheckboxRow("Include Key Takeaways", config.includeHighlights) {
            onConfigChange(config.copy(includeHighlights = it))
        }
    }
}

LectureRecordingScreen

File: ui/screens/LectureRecordingScreen.kt

Purpose: Record lectures with real-time transcription

Features:

• Record/pause/resume/stop buttons

• Duration timer (MM:SS format)

• Live transcription text (scrollable)

• Amplitude waveform visualization

• Status indicators (initializing, recording, processing)

Composable Signature:

@Composable
fun LectureRecordingScreen(
    viewModel: LectureRecordingViewModel = viewModel(),
    onNavigateToOutput: (Long) -> Unit,
    onNavigateBack: () -> Unit
)

Amplitude Visualization:

@Composable
fun AmplitudeVisualizer(amplitude: Float) {
    Canvas(modifier = Modifier.fillMaxWidth().height(100.dp)) {
        val barWidth = 4.dp.toPx()
        val spacing = 2.dp.toPx()
        val numBars = (size.width / (barWidth + spacing)).toInt()

        for (i in 0 until numBars) {
            val height = size.height * amplitude * Random.nextFloat()
            drawRoundRect(
                color = Color.Blue,
                topLeft = Offset(i * (barWidth + spacing), size.height - height),
                size = Size(barWidth, height),
                cornerRadius = CornerRadius(barWidth / 2)
            )
        }
    }
}

LectureOutputViewScreen

File: ui/screens/LectureOutputViewScreen.kt

Purpose: Display AI-generated lecture analysis

Features:

• Tab layout (Overview, Notes, Summary, Flashcards)

• Formatted markdown rendering

• Copy to clipboard

• Share functionality

• Flashcard flip animation (future)

Composable Signature:

@Composable
fun LectureOutputViewScreen(
    lectureId: Long,
    viewModel: LectureOutputViewModel = viewModel(),
    onNavigateBack: () -> Unit
)

Tab Structure:

@Composable
fun OutputTabs(
    selectedTab: Int,
    onTabSelected: (Int) -> Unit
) {
    TabRow(selectedTabIndex = selectedTab) {
        Tab(selected = selectedTab == 0, onClick = { onTabSelected(0) }) {
            Text("Overview")
        }
        Tab(selected = selectedTab == 1, onClick = { onTabSelected(1) }) {
            Text("Notes")
        }
        Tab(selected = selectedTab == 2, onClick = { onTabSelected(2) }) {
            Text("Summary")
        }
        Tab(selected = selectedTab == 3, onClick = { onTabSelected(3) }) {
            Text("Flashcards")
        }
    }
}

Markdown Rendering:

@Composable
fun MarkdownText(content: String) {
    // Currently using basic Text composable
    // Future: Consider using Markdown library like Markwon or CommonMark

    Text(
        text = content,
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp)
            .verticalScroll(rememberScrollState()),
        style = MaterialTheme.typography.bodyMedium
    )
}

PebbleCollectionScreen

File: ui/screens/PebbleCollectionScreen.kt

Purpose: Display all achievements (locked and unlocked)

Features:

• Grid layout of pebble cards

• Visual distinction (color vs grayscale)

• Unlock date for earned pebbles

• Unlock condition for locked pebbles

• Total count for repeated achievements

Composable Signature:

@Composable
fun PebbleCollectionScreen(
    viewModel: AchievementViewModel = viewModel(),
    onNavigateBack: () -> Unit
)

Pebble Card:

@Composable
fun PebbleCard(
    type: PebbleType,
    isUnlocked: Boolean,
    unlockedAt: Long? = null,
    totalCount: Int = 0
) {
    Card(
        modifier = Modifier.padding(8.dp),
        colors = CardDefaults.cardColors(
            containerColor = if (isUnlocked)
                Color(type.color)
            else
                Color.LightGray
        )
    ) {
        Column(modifier = Modifier.padding(16.dp)) {
            Icon(
                imageVector = type.icon,
                contentDescription = type.displayName,
                tint = if (isUnlocked) Color.White else Color.Gray
            )

            Spacer(modifier = Modifier.height(8.dp))

            Text(
                text = type.displayName,
                style = MaterialTheme.typography.titleMedium,
                color = if (isUnlocked) Color.White else Color.DarkGray
            )

            Text(
                text = type.description,
                style = MaterialTheme.typography.bodySmall,
                color = if (isUnlocked) Color.White else Color.Gray
            )

            if (isUnlocked && unlockedAt != null) {
                Text(
                    text = "Unlocked: ${formatDate(unlockedAt)}",
                    style = MaterialTheme.typography.labelSmall
                )
            }

            if (totalCount > 1) {
                Text(
                    text = "×$totalCount",
                    style = MaterialTheme.typography.labelLarge
                )
            }
        }
    }
}