---

name: search-guides description: Search app step-by-step guides - adding new providers (5 steps), adding settings (4 steps), adding settings screens (5 steps), Room database migrations, common file locations table, naming conventions, package organization, and design patterns used.

Quick Reference Guides

Adding a New Provider

Step 1: Create Provider Class

Copyapp/src/main/java/com/mrndstvndv/search/provider/{type}/{Name}Provider.kt

Step 2: Implement Provider Interface

Copyclass NewProvider(
    private val context: Context,
    private val settingsRepository: ProviderSettingsRepository
) : Provider {
    
    override val id = "new-provider"
    override val displayName = "New Provider"
    override val refreshSignal = MutableSharedFlow<Unit>()
    
    override fun initialize() { /* Heavy setup */ }
    
    override fun canHandle(query: Query): Boolean {
        return query.text.isNotBlank()
    }
    
    override suspend fun query(query: Query): List<ProviderResult> {
        // Return search results
    }
    
    override fun dispose() { /* Cleanup */ }
}

Step 3: Register in MainActivity (~line 150)

Copyval providers = remember {
    listOf(
        // ... existing providers
        NewProvider(context, settingsRepository)
    )
}

Step 4: Add Toggle in ProvidersSettingsScreen

CopySettingsSwitch(
    title = "New Provider",
    checked = isEnabled,
    onCheckedChange = { /* save state */ }
)

Step 5: Add to DEFAULT_PROVIDER_ORDER

In ProviderRankingRepository:

Copyprivate val DEFAULT_PROVIDER_ORDER = listOf(
    // ... existing IDs
    "new-provider"
)

---

Adding a New Setting

Step 1: Add Key Constant

In ProviderSettingsRepository:

Copyprivate const val KEY_NEW_SETTING = "new_setting"

Step 2: Add StateFlow

Copyprivate val _newSetting = MutableStateFlow(loadNewSetting())
val newSetting: StateFlow<Boolean> = _newSetting.asStateFlow()

Step 3: Add Load/Save Methods

Copyprivate fun loadNewSetting(): Boolean {
    return prefs.getBoolean(KEY_NEW_SETTING, true)
}

fun setNewSetting(value: Boolean) {
    prefs.edit().putBoolean(KEY_NEW_SETTING, value).apply()
    _newSetting.value = value
}

Step 4: Add UI

In the appropriate settings screen:

Copyval newSetting by settingsRepository.newSetting.collectAsState()

SettingsSwitch(
    title = "New Setting",
    description = "Description of what this does",
    checked = newSetting,
    onCheckedChange = { settingsRepository.setNewSetting(it) }
)

---

Adding a New Settings Screen

Step 1: Create Screen File

Copyapp/src/main/java/com/mrndstvndv/search/ui/settings/NewSettingsScreen.kt

Step 2: Implement Composable

Copy@Composable
fun NewSettingsScreen(
    settingsRepository: ProviderSettingsRepository,
    onNavigateBack: () -> Unit
) {
    Column {
        // Back button header
        TopAppBar(
            title = { Text("New Settings") },
            navigationIcon = {
                IconButton(onClick = onNavigateBack) {
                    Icon(Icons.AutoMirrored.Filled.ArrowBack, "Back")
                }
            }
        )
        
        // Settings content
        SettingsGroup(title = "Section") {
            // Settings components...
        }
    }
}

Step 3: Add to Screen Enum

In SettingsActivity.kt:

Copyprivate enum class Screen {
    // ... existing screens
    NewScreen
}

Step 4: Add Navigation Case

CopyScreen.NewScreen -> NewSettingsScreen(
    settingsRepository = settingsRepository,
    onNavigateBack = { currentScreen = Screen.Home }
)

Step 5: Add Navigation Row

In parent screen:

CopySettingsNavigationRow(
    title = "New Settings",
    onClick = { onNavigate(Screen.NewScreen) }
)

---

Database Migrations (Room)

Step 1: Update Entity

In provider/files/index/:

Copy@Entity(tableName = "files")
data class FileEntity(
    @PrimaryKey val path: String,
    val name: String,
    val newColumn: String = ""  // Add new field
)

Step 2: Add Migration

In FileSearchDatabase:

Copyval MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE files ADD COLUMN newColumn TEXT NOT NULL DEFAULT ''"
        )
    }
}

Step 3: Increment Version and Add Migration

Copy@Database(entities = [FileEntity::class], version = 2)
abstract class FileSearchDatabase : RoomDatabase() {
    companion object {
        fun getInstance(context: Context) = Room.databaseBuilder(...)
            .addMigrations(MIGRATION_1_2)
            .build()
    }
}

---

Common File Locations

---

Naming Conventions

---

Package Organization

Copyprovider/
├── Provider.kt           # Base interface
├── ProviderResult.kt     # Result model
├── model/                # Shared models (Query, etc.)
├── {type}/               # Provider implementation
│   ├── {Type}Provider.kt
│   └── {Type}Repository.kt (if needed)

ui/
├── theme/                # Design system
├── components/           # Reusable components
│   └── settings/         # Settings-specific components
└── settings/             # Settings screens

settings/                 # Non-UI settings utilities
├── ProviderSettingsRepository.kt
└── ProviderRankingRepository.kt

---

Design Patterns Used

---

Related Skills

• search-overview - Project structure and architecture
• search-provider - Provider interface details
• search-repository - Repository patterns
• search-ui - UI components and navigation
• search-build - Build configuration