name: search-dataflow description: Search app data flow - query flow diagram (user input → debounce → alias check → provider dispatch → aggregate → rank → UI), state management patterns (mutableStateOf, mutableStateListOf, StateFlow, SharedFlow), settings JSON persistence in SharedPreferences.

Data Flow

Query Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SEARCH QUERY FLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌───────────────┐                                                         │
│   │  User Types   │                                                         │
│   │  in SearchBar │                                                         │
│   └───────┬───────┘                                                         │
│           │                                                                 │
│           ▼                                                                 │
│   ┌───────────────────────┐                                                 │
│   │  Query Object Created │  Query(text, timestamp)                         │
│   └───────────┬───────────┘                                                 │
│               │                                                             │
│               ▼                                                             │
│   ┌───────────────────────┐                                                 │
│   │   Debounce (50ms)     │  Prevents excessive queries while typing        │
│   └───────────┬───────────┘                                                 │
│               │                                                             │
│       ┌───────┴───────────────────────┐                                     │
│       │                               │                                     │
│       ▼                               ▼                                     │
│ ┌─────────────────┐         ┌─────────────────────────┐                     │
│ │  Alias Check    │         │  Provider Dispatch      │                     │
│ │                 │         │                         │                     │
│ │ Does query      │         │ For each enabled        │                     │
│ │ match an alias? │         │ provider where          │                     │
│ │                 │         │ canHandle(query) = true │                     │
│ └────────┬────────┘         └────────────┬────────────┘                     │
│          │                               │                                  │
│          │ yes                           │                                  │
│          ▼                               ▼                                  │
│ ┌─────────────────┐         ┌─────────────────────────┐                     │
│ │ buildAliasResult│         │ supervisorScope {       │                     │
│ │ ()              │         │   async { p.query(q) }  │  Parallel execution │
│ │                 │         │ }                       │                     │
│ └────────┬────────┘         └────────────┬────────────┘                     │
│          │                               │                                  │
│          └───────────┬───────────────────┘                                  │
│                      │                                                      │
│                      ▼                                                      │
│          ┌───────────────────────┐                                          │
│          │  Aggregate Results    │  Combine all provider results            │
│          └───────────┬───────────┘                                          │
│                      │                                                      │
│                      ▼                                                      │
│          ┌───────────────────────┐                                          │
│          │   Apply Ranking       │                                          │
│          │                       │                                          │
│          │ 1. Frequency-based    │  (if enabled)                            │
│          │ 2. Provider order     │  (fallback)                              │
│          └───────────┬───────────┘                                          │
│                      │                                                      │
│                      ▼                                                      │
│          ┌───────────────────────┐                                          │
│          │ Update StateList      │  providerResults.clear() + addAll()      │
│          └───────────┬───────────┘                                          │
│                      │                                                      │
│                      ▼                                                      │
│          ┌───────────────────────┐                                          │
│          │  ItemsList Recomposes │  UI updates with new results             │
│          └───────────────────────┘                                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

State Management

State Management Guidelines

1. Settings → StateFlow in Repository:

   val setting: StateFlow<T> = repository.setting
   val value by setting.collectAsState()
   

2. Local UI State → mutableStateOf:

   var isExpanded by remember { mutableStateOf(false) }
   

3. Observable Lists → mutableStateListOf:

   val results = remember { mutableStateListOf<ProviderResult>() }
   

4. One-shot Events → SharedFlow:

   val refreshSignal = MutableSharedFlow<Unit>()
   

Settings Persistence

Settings are stored as JSON in SharedPreferences:

// Example: WebSearchSettings storage

// Data class
data class WebSearchSettings(
    val defaultSiteId: String,
    val sites: List<WebSearchSite>,
    val quicklinks: List<Quicklink>
)

// Persistence in ProviderSettingsRepository
private val prefs = context.getSharedPreferences("provider_settings", MODE_PRIVATE)

fun saveWebSearchSettings(settings: WebSearchSettings) {
    prefs.edit().putString(KEY_WEB_SEARCH, Json.encodeToString(settings)).apply()
    _webSearchSettings.value = settings
}

Key Files

Related Skills

• search-provider - Provider interface and lifecycle
• search-repository - Repository layer patterns