Development Guide

Setting Up Development Environment

Requirements

• Java Development Kit: JDK 11 or higher

• Android Studio: Latest stable version (Hedgehog or newer recommended)

• Android SDK: API levels 24-36

• Git: For version control

Steps

1. Install Android Studio

   • Download from developer.android.com

   • Install with default settings

   • Open SDK Manager

   • Install Android SDK Platform 36

   • Install Android SDK Build-Tools 34.0.0+

2. Clone Repository

   git clone https://github.com/yourusername/Pebbl.git
   cd Pebbl

3. Configure local.properties

   sdk.dir=C\:\\Users\\YourUsername\\AppData\\Local\\Android\\Sdk
   OPENROUTER_API_KEY=your_api_key_here

4. Sync Gradle

   • Open project in Android Studio

   • Wait for Gradle sync to complete

   • Resolve any dependency issues

5. Run on Emulator/Device

   • Create AVD (Android Virtual Device) with API 24+

   • Or connect physical device with USB debugging

   • Click Run (Shift+F10)

Building the App

Debug Build

./gradlew assembleDebug

Output: app/build/outputs/apk/debug/app-debug.apk

Release Build

./gradlew assembleRelease

For signed release:

1. Create keystore:

   keytool -genkey -v -keystore Pebbl-release.keystore \
     -alias Pebbl -keyalg RSA -keysize 2048 -validity 10000

2. Add to local.properties:

   KEYSTORE_FILE=../Pebbl-release.keystore
   KEYSTORE_PASSWORD=your_password
   KEY_ALIAS=Pebbl
   KEY_PASSWORD=your_key_password

3. Update build.gradle.kts:

   android {
       signingConfigs {
           create("release") {
               storeFile = file(properties["KEYSTORE_FILE"] as String)
               storePassword = properties["KEYSTORE_PASSWORD"] as String
               keyAlias = properties["KEY_ALIAS"] as String
               keyPassword = properties["KEY_PASSWORD"] as String
           }
       }
   
       buildTypes {
           release {
               signingConfig = signingConfigs.getByName("release")
               // ...
           }
       }
   }

4. Build signed release:

   ./gradlew assembleRelease

Output: app/build/outputs/apk/release/app-release.apk

Running Tests

Unit Tests

Located in app/src/test/

Run all tests:

./gradlew test

Run specific test:

./gradlew test --tests com.fouwaz.Pebbl.data.repository.AiRepositoryTest

Instrumented Tests

Located in app/src/androidTest/

Run on connected device:

./gradlew connectedAndroidTest

Example Unit Test

class AiRepositoryTest {

    private lateinit var repository: AiRepository
    private lateinit var mockApiService: OpenRouterService

    @Before
    fun setup() {
        mockApiService = mockk()
        repository = AiRepository(mockApiService)
    }

    @Test
    fun `generateFollowUpQuestions returns 3 questions on success`() = runTest {
        // Arrange
        val transcription = "I think climate change is important because..."
        val mockResponse = ChatResponse(
            id = "test-id",
            model = "test-model",
            choices = listOf(
                ChatChoice(
                    index = 0,
                    message = ChatMessage(
                        role = "assistant",
                        content = "1. What evidence?\n2. What about economy?\n3. Solutions?"
                    ),
                    finishReason = "stop"
                )
            ),
            usage = null
        )

        coEvery { mockApiService.chat(any()) } returns mockResponse

        // Act
        val result = repository.generateFollowUpQuestions(transcription)

        // Assert
        assertTrue(result.isSuccess)
        assertEquals(3, result.getOrNull()?.size)
    }
}

Code Style

Kotlin Style Guide

Follow Kotlin Coding Conventions

Key points:

• Naming: camelCase for functions/variables, PascalCase for classes

• Indentation: 4 spaces (no tabs)

• Line length: Max 120 characters

• Imports: No wildcard imports, organize alphabetically

• Trailing commas: Use in multi-line parameter lists

Compose Best Practices

• State Hoisting: Lift state to composable callers

• Reusability: Create small, focused composables

• remember: Use for expensive computations

• LaunchedEffect: For side effects tied to lifecycle

• derivedStateOf: For derived state calculations

Example Well-Formatted Code

@Composable
fun ProjectCard(
    project: Project,
    onStartSession: () -> Unit,
    onViewDraft: () -> Unit,
    onDelete: () -> Unit,
    modifier: Modifier = Modifier,
) {
    Card(
        modifier = modifier
            .fillMaxWidth()
            .padding(horizontal = 16.dp, vertical = 8.dp),
        elevation = CardDefaults.cardElevation(defaultElevation = 2.dp),
    ) {
        Column(
            modifier = Modifier
                .padding(16.dp)
                .fillMaxWidth(),
        ) {
            Text(
                text = project.title,
                style = MaterialTheme.typography.titleLarge,
                fontWeight = FontWeight.Bold,
            )

            if (project.tags.isNotEmpty()) {
                Spacer(modifier = Modifier.height(8.dp))
                Text(
                    text = project.tags,
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.secondary,
                )
            }

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

            Row(
                horizontalArrangement = Arrangement.spacedBy(8.dp),
            ) {
                Button(onClick = onStartSession) {
                    Text("Start Session")
                }

                OutlinedButton(onClick = onViewDraft) {
                    Text("View Draft")
                }

                IconButton(onClick = onDelete) {
                    Icon(Icons.Default.Delete, contentDescription = "Delete")
                }
            }
        }
    }
}