Merge branch 'main' into settings-to-profile

Author: rainxchzed

CLAUDE.md

@@ -30,36 +30,45 @@ Package: `zed.rainxch.githubstore`
 ## Project Structure
 
 ```
-composeApp/                          # Main app module
+composeApp/                          # Main app module (entry points, navigation, DI wiring)
   src/commonMain/                    # Shared UI & app wiring
   src/androidMain/                   # Android entry point (MainActivity)
   src/jvmMain/                       # Desktop entry point (DesktopApp.kt)
 core/
-  domain/                            # Shared interfaces, models, utils
-  data/                              # Shared repos, networking, database, DI
-  presentation/                      # Shared theming & UI utilities
+  domain/                            # Shared interfaces, models, use cases (no framework deps)
+  data/                              # Shared repos, networking (Ktor), database (Room), DI
+  presentation/                      # Shared theming (Material 3) & reusable UI components
 feature/
-  {apps,auth,details,dev-profile,    # Each feature has 3 sub-modules:
-   favourites,home,search,             domain/ - interfaces & models
-   settings,starred}/                  data/   - implementations & DI
-                                       presentation/ - screens & ViewModels
+  apps/                              # Installed applications management
+  auth/                              # GitHub OAuth device flow authentication
+  details/                           # Repository details, releases, readme, downloads
+  dev-profile/                       # Developer/user profile display
+  favourites/                        # Saved favorite repositories (presentation-only)
+  home/                              # Main discovery screen (trending, hot, popular)
+  search/                            # Repository search with filters
+  settings/                          # App settings (theme, account, appearance)
+  starred/                           # Starred repositories (presentation-only)
 build-logic/convention/              # Custom Gradle convention plugins
 ```
 
+Each feature has up to 3 sub-modules: `domain/` (interfaces & models), `data/` (implementations & DI), `presentation/` (screens & ViewModels). Some features (favourites, starred) are presentation-only and use core repositories directly.
+
 ## Architecture
 
 **Clean Architecture + MVVM** with strict layer separation per feature module:
 
 - **Domain** - Repository interfaces, models, use cases (no framework dependencies)
-- **Data** - Repository implementations, Ktor API clients, Room DAOs, DTOs
+- **Data** - Repository implementations, Ktor API clients, Room DAOs, DTOs, mappers
 - **Presentation** - ViewModels with `StateFlow`/`Channel`, Compose screens
 
 ### State Management Pattern
 
+Every screen follows the same State/Action/Event pattern:
+
 ```kotlin
 class XViewModel : ViewModel() {
     private val _state = MutableStateFlow(XState())
-    val state = _state.asStateFlow()
+    val state = _state.asStateFlow()  // or .stateIn() with WhileSubscribed
 
     private val _events = Channel<XEvent>()
     val events = _events.receiveAsFlow()
@@ -68,15 +77,34 @@ class XViewModel : ViewModel() {
 }
 ```
 
-Each screen uses a `State` data class, sealed `Action` class for user input, and sealed `Event` class for one-off effects.
+- `State` - data class holding all UI state
+- `Action` - sealed interface for user input (clicks, refreshes, etc.)
+- `Event` - sealed interface for one-off effects (navigation, toasts, scroll)
 
 ### Navigation
 
-Type-safe navigation using `@Serializable` sealed interface `GithubStoreGraph` in `composeApp/src/commonMain/.../app/navigation/`.
+Type-safe navigation using `@Serializable` sealed interface `GithubStoreGraph`:
+
+```
+HomeScreen, SearchScreen, AuthenticationScreen, SettingsScreen,
+FavouritesScreen, StarredReposScreen, AppsScreen
+DetailsScreen(repositoryId, owner, repo)
+DeveloperProfileScreen(username)
+```
+
+Routes defined in `composeApp/.../app/navigation/GithubStoreGraph.kt`, wired in `AppNavigation.kt`.
 
 ### Dependency Injection
 
-**Koin** - modules defined in each feature's `data/di/` directory, registered in `composeApp/.../app/di/initKoin.kt`. ViewModels injected via `koinViewModel()`.
+**Koin** - modules defined in each feature's `data/di/SharedModule.kt`, registered in `composeApp/.../app/di/initKoin.kt`. ViewModels injected via `koinViewModel()`.
+
+### Core Modules
+
+| Module | Purpose | Key Contents |
+|--------|---------|--------------|
+| `core/domain` | Shared contracts | Repository interfaces (`FavouritesRepository`, `StarredRepository`, `InstalledAppsRepository`, `ThemesRepository`), models (`GithubRepoSummary`, `GithubRelease`, `InstalledApp`, `ProxyConfig`), system interfaces (`Downloader`, `Installer`, `PackageMonitor`) |
+| `core/data` | Shared implementations | `HttpClientFactory` (Ktor + interceptors), `AppDatabase` (Room), `ProxyManager`, `TokenStore`, `LocalizationManager`, platform-specific clients (OkHttp for Android, CIO for Desktop) |
+| `core/presentation` | Shared UI | `GithubStoreTheme` (Material 3), reusable components (`RepositoryCard`, `GithubStoreButton`), formatting utils |
 
 ## Tech Stack
 
@@ -103,20 +131,20 @@ Custom Gradle plugins in `build-logic/convention/` standardize module setup:
 
 | Plugin | Use For |
 |--------|---------|
-| `convention.kmp.library` | KMP shared library modules |
-| `convention.cmp.library` | Compose Multiplatform library modules |
-| `convention.cmp.feature` | Feature presentation modules |
+| `convention.kmp.library` | KMP shared library modules (domain, data) |
+| `convention.cmp.library` | Compose Multiplatform library modules (core/presentation) |
+| `convention.cmp.feature` | Feature presentation modules (auto-adds Compose + Koin + core:presentation) |
 | `convention.cmp.application` | Main app module |
 | `convention.room` | Room database modules |
-| `convention.buildkonfig` | Build-time config (API keys) |
+| `convention.buildkonfig` | Build-time config (API keys from local.properties) |
 
 ## Adding a New Feature
 
 1. Create `feature/<name>/domain/`, `feature/<name>/data/`, `feature/<name>/presentation/`
 2. Add `build.gradle.kts` in each using the appropriate convention plugin
 3. Add `include` entries in `settings.gradle.kts`
 4. Define domain interfaces/models in `domain/`
-5. Implement repository + Koin DI module in `data/di/`
+5. Implement repository + Koin DI module in `data/di/SharedModule.kt`
 6. Create ViewModel (State/Action/Event pattern) and Screen in `presentation/`
 7. Add navigation route to `GithubStoreGraph.kt` and wire in `AppNavigation.kt`
 8. Register the Koin module in `initKoin.kt`
@@ -131,7 +159,8 @@ Custom Gradle plugins in `build-logic/convention/` standardize module setup:
 
 - Packages follow `zed.rainxch.{module}.{layer}` pattern
 - Private state properties use underscore prefix: `_state`
-- Sealed classes for type-safe navigation routes, actions, events
+- Sealed classes/interfaces for type-safe navigation routes, actions, events
 - Repository pattern: interface in `domain/`, implementation in `data/`
 - Composition over inheritance via Koin DI
 - Source sets: `commonMain` for shared, `androidMain` for Android, `jvmMain` for Desktop
+- Feature CLAUDE.md files exist in each `feature/` directory for module-specific guidance

core/data/build.gradle.kts

@@ -24,13 +24,13 @@ kotlin {
 
         androidMain {
             dependencies {
-
+                implementation(libs.ktor.client.okhttp)
             }
         }
 
         jvmMain {
             dependencies {
-
+                implementation(libs.ktor.client.cio)
             }
         }
     }

core/data/src/androidMain/kotlin/zed/rainxch/core/data/network/HttpClientFactory.android.kt

@@ -0,0 +1,73 @@
+package zed.rainxch.core.data.network
+
+import io.ktor.client.*
+import io.ktor.client.engine.okhttp.*
+import java.net.InetSocketAddress
+import java.net.Proxy
+import okhttp3.Credentials
+import zed.rainxch.core.domain.model.ProxyConfig
+import java.net.PasswordAuthentication
+import java.net.ProxySelector
+
+actual fun createPlatformHttpClient(proxyConfig: ProxyConfig): HttpClient {
+    return HttpClient(OkHttp) {
+        engine {
+            when (proxyConfig) {
+                is ProxyConfig.None -> {
+                    proxy = Proxy.NO_PROXY
+                }
+
+                is ProxyConfig.System -> {
+                    config {
+                        proxySelector(ProxySelector.getDefault())
+                    }
+                }
+
+                is ProxyConfig.Http -> {
+                    proxy = Proxy(
+                        Proxy.Type.HTTP,
+                        InetSocketAddress(proxyConfig.host, proxyConfig.port)
+                    )
+                    if (proxyConfig.username != null) {
+                        config {
+                            proxyAuthenticator { _, response ->
+                                response.request.newBuilder()
+                                    .header(
+                                        "Proxy-Authorization",
+                                        Credentials.basic(
+                                            proxyConfig.username!!,
+                                            proxyConfig.password.orEmpty()
+                                        )
+                                    )
+                                    .build()
+                            }
+                        }
+                    }
+                }
+
+                is ProxyConfig.Socks -> {
+                    proxy = Proxy(
+                        Proxy.Type.SOCKS,
+                        InetSocketAddress(proxyConfig.host, proxyConfig.port)
+                    )
+
+                    if (proxyConfig.username != null) {
+                        java.net.Authenticator.setDefault(object : java.net.Authenticator() {
+                            override fun getPasswordAuthentication(): PasswordAuthentication? {
+                                if (requestingHost == proxyConfig.host &&
+                                    requestingPort == proxyConfig.port
+                                ) {
+                                    return PasswordAuthentication(
+                                        proxyConfig.username,
+                                        proxyConfig.password.orEmpty().toCharArray()
+                                    )
+                                }
+                                return null
+                            }
+                        })
+                    }
+                }
+            }
+        }
+    }
+}

core/data/src/commonMain/kotlin/zed/rainxch/core/data/di/SharedModule.kt

@@ -13,6 +13,8 @@ import zed.rainxch.core.data.local.db.dao.InstalledAppDao
 import zed.rainxch.core.data.local.db.dao.StarredRepoDao
 import zed.rainxch.core.data.local.db.dao.UpdateHistoryDao
 import zed.rainxch.core.data.logging.KermitLogger
+import zed.rainxch.core.data.network.GitHubClientProvider
+import zed.rainxch.core.data.network.ProxyManager
 import zed.rainxch.core.data.network.createGitHubHttpClient
 import zed.rainxch.core.data.repository.AuthenticationStateImpl
 import zed.rainxch.core.data.repository.FavouritesRepositoryImpl
@@ -93,6 +95,14 @@ val coreModule = module {
 }
 
 val networkModule = module {
+    single<GitHubClientProvider> {
+        GitHubClientProvider(
+            tokenStore = get(),
+            rateLimitRepository = get(),
+            proxyConfigFlow = ProxyManager.currentProxyConfig
+        )
+    }
+
     single<HttpClient> {
         createGitHubHttpClient(
             tokenStore = get(),

core/data/src/commonMain/kotlin/zed/rainxch/core/data/network/GitHubClientProvider.kt

@@ -0,0 +1,60 @@
+package zed.rainxch.core.data.network
+
+import io.ktor.client.HttpClient
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import zed.rainxch.core.data.data_source.TokenStore
+import zed.rainxch.core.domain.model.ProxyConfig
+import zed.rainxch.core.domain.repository.RateLimitRepository
+
+class GitHubClientProvider(
+    private val tokenStore: TokenStore,
+    private val rateLimitRepository: RateLimitRepository,
+    proxyConfigFlow: StateFlow<ProxyConfig>
+) {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+    private var currentClient: HttpClient? = null
+    private val mutex = Mutex()
+
+    private val _client: StateFlow<HttpClient> = proxyConfigFlow
+        .map { proxyConfig ->
+            mutex.withLock {
+                currentClient?.close()
+                val newClient = createGitHubHttpClient(
+                    tokenStore = tokenStore,
+                    rateLimitRepository = rateLimitRepository,
+                    proxyConfig = proxyConfig
+                )
+                currentClient = newClient
+                newClient
+            }
+        }
+        .stateIn(
+            scope = scope,
+            started = SharingStarted.Eagerly,
+            initialValue = createGitHubHttpClient(
+                tokenStore = tokenStore,
+                rateLimitRepository = rateLimitRepository,
+                proxyConfig = proxyConfigFlow.value
+            ).also { currentClient = it }
+        )
+
+    /** Get the current HttpClient (always up to date with proxy settings) */
+    val client: HttpClient get() = _client.value
+
+    fun close() {
+        currentClient?.close()
+        scope.cancel()
+    }
+}

core/data/src/commonMain/kotlin/zed/rainxch/core/data/network/HttpClientFactory.kt

@@ -9,24 +9,29 @@ import io.ktor.client.statement.HttpResponse
 import io.ktor.http.*
 import io.ktor.serialization.kotlinx.json.*
 import io.ktor.util.network.UnresolvedAddressException
+import kotlinx.coroutines.flow.Flow
 import kotlinx.serialization.json.Json
 import zed.rainxch.core.data.data_source.TokenStore
 import zed.rainxch.core.data.network.interceptor.RateLimitInterceptor
+import zed.rainxch.core.domain.model.ProxyConfig
 import zed.rainxch.core.domain.model.RateLimitException
 import zed.rainxch.core.domain.repository.RateLimitRepository
 import java.io.IOException
 import kotlin.coroutines.cancellation.CancellationException
 
+expect fun createPlatformHttpClient(proxyConfig: ProxyConfig): HttpClient
+
 fun createGitHubHttpClient(
     tokenStore: TokenStore,
-    rateLimitRepository: RateLimitRepository
+    rateLimitRepository: RateLimitRepository,
+    proxyConfig: ProxyConfig = ProxyConfig.None
 ): HttpClient {
     val json = Json {
         ignoreUnknownKeys = true
         isLenient = true
     }
 
-    return HttpClient {
+    return createPlatformHttpClient(proxyConfig).config {
         install(RateLimitInterceptor) {
             this.rateLimitRepository = rateLimitRepository
         }
@@ -45,23 +50,17 @@ fun createGitHubHttpClient(
             maxRetries = 3
             retryIf { _, response ->
                 val code = response.status.value
-
                 if (code == 403) {
                     val remaining = response.headers["X-RateLimit-Remaining"]?.toIntOrNull()
-                    if (remaining == 0) {
-                        return@retryIf false
-                    }
+                    if (remaining == 0) return@retryIf false
                 }
-
                 code in 500..<600
             }
-
             retryOnExceptionIf { _, cause ->
                 cause is HttpRequestTimeoutException ||
                         cause is UnresolvedAddressException ||
                         cause is IOException
             }
-
             exponentialDelay()
         }