816 lines
31 KiB
Markdown
816 lines
31 KiB
Markdown
# Phase 2: Authentication Foundation - Pattern Map
|
|
|
|
**Mapped:** 2026-04-27
|
|
**Files analyzed:** 56 new/modified files or file groups
|
|
**Analogs found:** 48 / 56
|
|
|
|
## File Classification
|
|
|
|
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
|
|-------------------|------|-----------|----------------|---------------|
|
|
| `gradle/libs.versions.toml` | config | build-config | `gradle/libs.versions.toml` | exact |
|
|
| `shared/build.gradle.kts` | config | build-config | `server/build.gradle.kts` + `shared/build.gradle.kts` | role-match |
|
|
| `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/Constants.kt` | config | transform | `shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt` | role-match |
|
|
| `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/User.kt` | model | request-response | `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` `Health` DTO | partial |
|
|
| `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/MeResponse.kt` | model | request-response | `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` `Health` DTO | partial |
|
|
| `shared/src/commonTest/kotlin/dev/ulfrx/recipe/shared/dto/MeResponseSerializationTest.kt` | test | transform | `shared/src/commonTest/kotlin/dev/ulfrx/recipe/SharedCommonTest.kt` | role-match |
|
|
| `server/build.gradle.kts` | config | build-config | `server/build.gradle.kts` | exact |
|
|
| `server/src/main/resources/application.conf` | config | request-response | `server/src/main/resources/application.conf` | exact |
|
|
| `server/src/main/resources/db/migration/V1__users.sql` | migration | CRUD | `server/src/main/resources/db/migration/.gitkeep` + `Database.kt` Flyway path | partial |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/AuthConfig.kt` | config | request-response | `server/src/main/resources/application.conf` + `Database.kt` config reads | role-match |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/AuthPlugin.kt` | middleware | request-response | `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` plugin install pattern | role-match |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/PrincipalResolver.kt` | service | CRUD | `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` fail-loud DB boundary | partial |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/UsersTable.kt` | model | CRUD | `V1__users.sql` planned migration + Exposed DSL decision | no existing analog |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/MeRoute.kt` | route | request-response | `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` `configureRouting()` | exact |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` | controller | request-response | `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` | exact |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` | service | file-I/O | `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` | exact |
|
|
| `server/src/test/kotlin/dev/ulfrx/recipe/auth/JwtAuthTest.kt` | test | request-response | `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` | exact |
|
|
| `server/src/test/kotlin/dev/ulfrx/recipe/auth/JwtTestSupport.kt` | test utility | transform | `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` | partial |
|
|
| `composeApp/build.gradle.kts` | config | build-config | `composeApp/build.gradle.kts` | exact |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.kt` | service | event-driven | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt` expect-free common seam style | partial |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/OidcResult.kt` | model | event-driven | `shared` DTO style + `kotlin.test` examples | partial |
|
|
| `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.android.kt` | service | event-driven | `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainActivity.kt` | role-match |
|
|
| `composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.ios.kt` | service | event-driven | `composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt` | role-match |
|
|
| `composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.jvm.kt` | service | transform | `composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt` | role-match |
|
|
| `composeApp/src/webMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.wasmJs.kt` | service | transform | `composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt` | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthState.kt` | model | event-driven | `shared` model/test shape | partial |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt` | service | event-driven | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt` Koin singleton hook | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/TokenStore.kt` | service | file-I/O | `tools/verify-shared-pure.sh` persistence-boundary guard | partial |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt` | service | request-response | no Ktor client analog; use research Ktor bearer pattern | no existing analog |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/MeClient.kt` | service | request-response | `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` client GET pattern | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthModule.kt` | provider | dependency-injection | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt` | exact |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt` | provider | dependency-injection | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt` | exact |
|
|
| `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/auth/SettingsFactory.android.kt` | service | file-I/O | `MainApplication.kt` Android context injection | role-match |
|
|
| `composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/auth/SettingsFactory.ios.kt` | service | file-I/O | `KoinIos.kt` iOS actual bridge | partial |
|
|
| `composeApp/src/*Main/kotlin/dev/ulfrx/recipe/auth/HttpClientEngine.*.kt` | utility | request-response | platform `main.kt` target-specific files | role-match |
|
|
| `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainActivity.kt` | controller | event-driven | `MainActivity.kt` | exact |
|
|
| `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt` | provider | dependency-injection | `MainApplication.kt` | exact |
|
|
| `composeApp/src/androidMain/AndroidManifest.xml` | config | event-driven | `AndroidManifest.xml` | exact |
|
|
| `iosApp/iosApp/Info.plist` | config | event-driven | `Info.plist` | exact |
|
|
| `iosApp/iosApp/iOSApp.swift` | controller | event-driven | `iOSApp.swift` | exact |
|
|
| `iosApp/Podfile` | config | build-config | no existing Podfile; use `composeApp/build.gradle.kts` iOS framework block | no existing analog |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/theme/RecipeTheme.kt` | component | transform | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt` `MaterialTheme` wrapper | exact |
|
|
| `composeApp/src/commonMain/composeResources/values/strings.xml` | config | transform | `composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml` | partial |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/SplashScreen.kt` | component | event-driven | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt` | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/LoginScreen.kt` | component | event-driven | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt` | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/LoginViewModel.kt` | controller | event-driven | no ViewModel analog; use Koin/viewmodel deps and UI-SPEC method-per-action contract | no existing analog |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/PostLoginPlaceholderScreen.kt` | component | event-driven | `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt` | role-match |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/PostLoginViewModel.kt` | controller | event-driven | no ViewModel analog; use same shape as `LoginViewModel` | no existing analog |
|
|
| `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt` | test | event-driven | `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/ComposeAppCommonTest.kt` | role-match |
|
|
| `docs/authentik-setup.md` | docs | manual-UAT | `README.md` local development pattern if present; otherwise phase docs style | partial |
|
|
|
|
## Pattern Assignments
|
|
|
|
### Shared DTO + Constants Files
|
|
|
|
Applies to:
|
|
- `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/Constants.kt`
|
|
- `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/User.kt`
|
|
- `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/MeResponse.kt`
|
|
- `shared/src/commonTest/kotlin/dev/ulfrx/recipe/shared/dto/MeResponseSerializationTest.kt`
|
|
|
|
**Analog:** `shared/build.gradle.kts`, `shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt`, `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt`, `shared/src/commonTest/kotlin/dev/ulfrx/recipe/SharedCommonTest.kt`
|
|
|
|
**Shared purity pattern** (`shared/build.gradle.kts` lines 16-20):
|
|
```kotlin
|
|
sourceSets {
|
|
commonMain.dependencies {
|
|
// Phase 1: intentionally empty. Domain models + DTOs land Phase 2+.
|
|
// D-19 / INFRA-06: No Ktor, Compose, SQLDelight, Koin, or Kermit here - EVER.
|
|
}
|
|
}
|
|
```
|
|
|
|
**Public constant pattern** (`shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt` lines 1-3):
|
|
```kotlin
|
|
package dev.ulfrx.recipe
|
|
|
|
public const val SERVER_PORT: Int = 8080
|
|
```
|
|
|
|
**Serializable DTO pattern** (`server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` lines 12, 19-22):
|
|
```kotlin
|
|
import kotlinx.serialization.Serializable
|
|
|
|
@Serializable
|
|
private data class Health(
|
|
val status: String,
|
|
)
|
|
```
|
|
|
|
**Test skeleton pattern** (`shared/src/commonTest/kotlin/dev/ulfrx/recipe/SharedCommonTest.kt` lines 1-10):
|
|
```kotlin
|
|
package dev.ulfrx.recipe
|
|
|
|
import kotlin.test.Test
|
|
import kotlin.test.assertEquals
|
|
|
|
class SharedCommonTest {
|
|
@Test
|
|
fun example() {
|
|
assertEquals(3, 1 + 2)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Planner note:** New shared symbols must be `public` because `shared` has `explicitApi()` enabled at `shared/build.gradle.kts` lines 9-10. Keep only Kotlin stdlib and `kotlinx.serialization` imports in shared DTOs.
|
|
|
|
### Gradle Catalog + Module Build Files
|
|
|
|
Applies to:
|
|
- `gradle/libs.versions.toml`
|
|
- `shared/build.gradle.kts`
|
|
- `server/build.gradle.kts`
|
|
- `composeApp/build.gradle.kts`
|
|
|
|
**Analog:** existing build files
|
|
|
|
**Version catalog organization** (`gradle/libs.versions.toml` lines 1-24, 27-43, 68-79):
|
|
```toml
|
|
[versions]
|
|
kotlin = "2.3.20"
|
|
kotlinx-serialization = "1.7.3"
|
|
ktor = "3.4.1"
|
|
|
|
[libraries]
|
|
compose-runtime = { module = "org.jetbrains.compose.runtime:runtime", version.ref = "composeMultiplatform" }
|
|
ktor-serverCore = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor" }
|
|
|
|
[plugins]
|
|
kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
|
|
```
|
|
|
|
**Server dependency pattern** (`server/build.gradle.kts` lines 1-8, 27-39):
|
|
```kotlin
|
|
plugins {
|
|
alias(libs.plugins.kotlinJvm)
|
|
alias(libs.plugins.kotlinSerialization)
|
|
alias(libs.plugins.ktor)
|
|
alias(libs.plugins.flywayPlugin)
|
|
application
|
|
id("recipe.quality")
|
|
}
|
|
|
|
dependencies {
|
|
implementation(libs.ktor.serverCore)
|
|
implementation(libs.ktor.serverNetty)
|
|
implementation(libs.ktor.serverContentNegotiation)
|
|
implementation(libs.ktor.serializationKotlinxJson)
|
|
implementation(projects.shared)
|
|
testImplementation(libs.ktor.serverTestHost)
|
|
testImplementation(libs.kotlin.testJunit)
|
|
}
|
|
```
|
|
|
|
**Compose dependency pattern** (`composeApp/build.gradle.kts` lines 48-69):
|
|
```kotlin
|
|
sourceSets {
|
|
commonMain.dependencies {
|
|
implementation(project.dependencies.platform(libs.koin.bom))
|
|
implementation(libs.koin.core)
|
|
implementation(libs.koin.compose)
|
|
implementation(libs.koin.composeViewmodel)
|
|
implementation(libs.kermit)
|
|
implementation(libs.compose.runtime)
|
|
implementation(libs.compose.foundation)
|
|
implementation(libs.compose.material3)
|
|
implementation(libs.compose.components.resources)
|
|
implementation(projects.shared)
|
|
}
|
|
androidMain.dependencies {
|
|
implementation(libs.compose.uiToolingPreview)
|
|
implementation(libs.androidx.activity.compose)
|
|
implementation(libs.koin.android)
|
|
}
|
|
}
|
|
```
|
|
|
|
**No version literal guard** (`tools/verify-no-version-literals.sh` lines 1-20):
|
|
```bash
|
|
VIOLATIONS=$(grep -rn -E 'version[[:space:]]*=[[:space:]]*"[0-9]' --include='*.gradle.kts' . 2>/dev/null \
|
|
| grep -v 'build-logic/build.gradle.kts' \
|
|
| grep -vE ':[0-9]+:version[[:space:]]*=[[:space:]]*"[0-9]' \
|
|
|| true)
|
|
```
|
|
|
|
**Planner note:** Put new dependency versions in `gradle/libs.versions.toml`; do not add library versions directly in `*.gradle.kts` except for explicitly justified test-only literals already called out by the plan.
|
|
|
|
### Client Koin + Logging + Auth Module
|
|
|
|
Applies to:
|
|
- `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthModule.kt`
|
|
- `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`
|
|
- Auth singleton wiring in `AuthSession.kt`
|
|
|
|
**Analog:** `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`, `Koin.kt`, `Logging.kt`, platform bootstraps
|
|
|
|
**Koin module placeholder pattern** (`AppModule.kt` lines 1-9):
|
|
```kotlin
|
|
package dev.ulfrx.recipe.di
|
|
|
|
import org.koin.dsl.module
|
|
|
|
// Phase 2 adds authModule; Phase 4 adds syncModule; Phase 5 adds catalogModule; etc.
|
|
val appModule =
|
|
module {
|
|
// intentionally empty in Phase 1
|
|
}
|
|
```
|
|
|
|
**Koin startup pattern** (`Koin.kt` lines 1-10):
|
|
```kotlin
|
|
package dev.ulfrx.recipe.di
|
|
|
|
import org.koin.core.KoinApplication
|
|
import org.koin.core.context.startKoin
|
|
import org.koin.dsl.KoinAppDeclaration
|
|
|
|
fun initKoin(config: KoinAppDeclaration? = null): KoinApplication =
|
|
startKoin {
|
|
config?.invoke(this)
|
|
modules(appModule)
|
|
}
|
|
```
|
|
|
|
**Client logging bootstrap** (`Logging.kt` lines 1-8):
|
|
```kotlin
|
|
package dev.ulfrx.recipe.logging
|
|
|
|
import co.touchlab.kermit.Logger
|
|
|
|
fun configureLogging() {
|
|
Logger.setTag("recipe")
|
|
// Platform log writers (OSLog iOS, LogCat Android, System.out JVM/Wasm) install by default.
|
|
}
|
|
```
|
|
|
|
**Platform init order** (`MainApplication.kt` lines 8-15, `KoinIos.kt` lines 5-8):
|
|
```kotlin
|
|
class MainApplication : Application() {
|
|
override fun onCreate() {
|
|
super.onCreate()
|
|
configureLogging()
|
|
initKoin {
|
|
androidContext(this@MainApplication)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```kotlin
|
|
fun doInitKoin() {
|
|
configureLogging()
|
|
initKoin()
|
|
}
|
|
```
|
|
|
|
**Planner note:** Add `authModule` without starting Koin from composables. Wire modules from the existing `initKoin` path, preserving the one-start-per-platform rule.
|
|
|
|
### Compose App Shell + Auth Screens
|
|
|
|
Applies to:
|
|
- `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt`
|
|
- `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/theme/RecipeTheme.kt`
|
|
- `SplashScreen.kt`
|
|
- `LoginScreen.kt`
|
|
- `LoginViewModel.kt`
|
|
- `PostLoginPlaceholderScreen.kt`
|
|
- `PostLoginViewModel.kt`
|
|
- `composeApp/src/commonMain/composeResources/values/strings.xml`
|
|
|
|
**Analog:** `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt`, `composeResources/drawable/compose-multiplatform.xml`
|
|
|
|
**Current app wrapper to preserve/replace** (`App.kt` lines 25-52):
|
|
```kotlin
|
|
@Composable
|
|
@Preview
|
|
fun App() {
|
|
MaterialTheme {
|
|
var showContent by remember { mutableStateOf(false) }
|
|
Column(
|
|
modifier =
|
|
Modifier
|
|
.background(MaterialTheme.colorScheme.primaryContainer)
|
|
.safeContentPadding()
|
|
.fillMaxSize(),
|
|
horizontalAlignment = Alignment.CenterHorizontally,
|
|
) {
|
|
Button(onClick = { showContent = !showContent }) {
|
|
Text("Click me!")
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Resource import pattern** (`App.kt` lines 21-23):
|
|
```kotlin
|
|
import org.jetbrains.compose.resources.painterResource
|
|
import recipe.composeapp.generated.resources.Res
|
|
import recipe.composeapp.generated.resources.compose_multiplatform
|
|
```
|
|
|
|
**Compose resource file placement analog** (`composeResources/drawable/compose-multiplatform.xml` lines 1-7):
|
|
```xml
|
|
<vector
|
|
xmlns:android="http://schemas.android.com/apk/res/android"
|
|
xmlns:aapt="http://schemas.android.com/aapt"
|
|
android:width="450dp"
|
|
android:height="450dp"
|
|
android:viewportWidth="64"
|
|
android:viewportHeight="64">
|
|
```
|
|
|
|
**UI contract to copy from `02-UI-SPEC.md` lines 149-161:**
|
|
```text
|
|
AuthState.Loading -> SplashScreen()
|
|
AuthState.Unauthenticated -> LoginScreen(viewModel = koinViewModel())
|
|
AuthState.Authenticated(user, householdId) -> PostLoginPlaceholderScreen(user, viewModel = koinViewModel())
|
|
```
|
|
|
|
**Layout contract to copy from `02-UI-SPEC.md` lines 185-197:**
|
|
```kotlin
|
|
Modifier.fillMaxSize()
|
|
.background(MaterialTheme.colorScheme.surface)
|
|
.safeContentPadding()
|
|
.padding(horizontal = 16.dp)
|
|
Column(
|
|
horizontalAlignment = Alignment.CenterHorizontally,
|
|
verticalArrangement = Arrangement.Center,
|
|
modifier = Modifier.fillMaxSize(),
|
|
)
|
|
```
|
|
|
|
**Planner note:** Existing `App.kt` is template code. Keep the `@Composable`, `@Preview`, `MaterialTheme` shape, but replace the button/greeting body with the auth gate. All strings come from Compose Resources, not raw Polish literals.
|
|
|
|
### Server Application, Config, Flyway, and Routes
|
|
|
|
Applies to:
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt`
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt`
|
|
- `server/src/main/resources/application.conf`
|
|
- `server/src/main/resources/db/migration/V1__users.sql`
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/auth/MeRoute.kt`
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/auth/AuthConfig.kt`
|
|
|
|
**Analog:** existing server files
|
|
|
|
**Application install and routing pattern** (`Application.kt` lines 24-38):
|
|
```kotlin
|
|
fun Application.module() {
|
|
install(ContentNegotiation) {
|
|
json()
|
|
}
|
|
Database.migrate(this)
|
|
configureRouting()
|
|
}
|
|
|
|
fun Application.configureRouting() {
|
|
routing {
|
|
get("/health") {
|
|
call.respond(Health(status = "ok"))
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**HOCON env override pattern** (`application.conf` lines 1-18):
|
|
```hocon
|
|
ktor {
|
|
deployment {
|
|
port = 8080
|
|
port = ${?PORT}
|
|
}
|
|
}
|
|
|
|
database {
|
|
url = "jdbc:postgresql://localhost:5432/recipe"
|
|
url = ${?DATABASE_URL}
|
|
user = "recipe"
|
|
user = ${?DATABASE_USER}
|
|
password = "recipe"
|
|
password = ${?DATABASE_PASSWORD}
|
|
}
|
|
```
|
|
|
|
**Flyway runtime pattern** (`Database.kt` lines 10-39):
|
|
```kotlin
|
|
fun migrate(app: Application) {
|
|
val url = app.environment.config.property("database.url").getString()
|
|
val user = app.environment.config.property("database.user").getString()
|
|
val password = app.environment.config.property("database.password").getString()
|
|
|
|
log.info("Connecting to {} as {} and running Flyway migrations", url, user)
|
|
|
|
runCatching {
|
|
Flyway
|
|
.configure()
|
|
.dataSource(url, user, password)
|
|
.locations("classpath:db/migration")
|
|
.baselineOnMigrate(true)
|
|
.validateOnMigrate(true)
|
|
.cleanDisabled(true)
|
|
.load()
|
|
.migrate()
|
|
}.onFailure { ex ->
|
|
log.error("Flyway migration failed", ex)
|
|
throw IllegalStateException("Database unreachable or migration failed", ex)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Planner note:** Insert auth install in `Application.module()` after `ContentNegotiation`/`CallLogging` and before protected routing. Keep `configureRouting()` testable without invoking real Postgres where possible.
|
|
|
|
### Server JWT Auth + Principal Resolver
|
|
|
|
Applies to:
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/auth/AuthPlugin.kt`
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/auth/PrincipalResolver.kt`
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/auth/UsersTable.kt`
|
|
|
|
**Analog:** `Application.kt` plugin install, `Database.kt` DB boundary. No existing JWT or Exposed analog exists yet.
|
|
|
|
**Plugin install style to copy** (`Application.kt` lines 24-27):
|
|
```kotlin
|
|
install(ContentNegotiation) {
|
|
json()
|
|
}
|
|
```
|
|
|
|
**DB config/logging boundary to copy** (`Database.kt` lines 7-9, 24-39):
|
|
```kotlin
|
|
object Database {
|
|
private val log = LoggerFactory.getLogger(Database::class.java)
|
|
|
|
fun migrate(app: Application) {
|
|
log.info("Connecting to {} as {} and running Flyway migrations", url, user)
|
|
runCatching {
|
|
Flyway.configure().dataSource(url, user, password).load().migrate()
|
|
}.onFailure { ex ->
|
|
log.error("Flyway migration failed", ex)
|
|
throw IllegalStateException("Database unreachable or migration failed", ex)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Required auth shape from `02-CONTEXT.md` lines 62-64:**
|
|
```kotlin
|
|
install(Authentication) {
|
|
jwt("authentik") {
|
|
// verifier(jwkProvider, issuer), withIssuer, withAudience, acceptLeeway(30)
|
|
// validate block must reject null or blank sub
|
|
}
|
|
}
|
|
```
|
|
|
|
**Required JIT upsert from `02-CONTEXT.md` lines 81-91:**
|
|
```sql
|
|
INSERT INTO users (sub, email, display_name)
|
|
VALUES (:sub, :email, :name)
|
|
ON CONFLICT (sub) DO UPDATE
|
|
SET email = EXCLUDED.email,
|
|
display_name = EXCLUDED.display_name,
|
|
updated_at = now()
|
|
RETURNING *;
|
|
```
|
|
|
|
**Planner note:** Use Exposed DSL only and suspend transaction APIs for request-handling DB work. There is no local Exposed analog yet; the plan must treat `PrincipalResolver` as the first canonical server CRUD service.
|
|
|
|
### Server Tests
|
|
|
|
Applies to:
|
|
- `server/src/test/kotlin/dev/ulfrx/recipe/auth/JwtAuthTest.kt`
|
|
- `server/src/test/kotlin/dev/ulfrx/recipe/auth/JwtTestSupport.kt`
|
|
- `server/src/test/kotlin/dev/ulfrx/recipe/auth/MeRouteTest.kt` if added
|
|
|
|
**Analog:** `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt`
|
|
|
|
**Ktor test pattern** (`ApplicationTest.kt` lines 14-29):
|
|
```kotlin
|
|
class ApplicationTest {
|
|
@Test
|
|
fun `health endpoint returns 200 with status ok`() =
|
|
testApplication {
|
|
application {
|
|
install(ContentNegotiation) {
|
|
json()
|
|
}
|
|
configureRouting()
|
|
}
|
|
val response = client.get("/health")
|
|
assertEquals(HttpStatusCode.OK, response.status)
|
|
val body = response.bodyAsText()
|
|
assertTrue(body.contains("\"status\""), "expected body to contain status field, was: $body")
|
|
assertTrue(body.contains("\"ok\""), "expected body to contain ok value, was: $body")
|
|
}
|
|
}
|
|
```
|
|
|
|
**Planner note:** Compose test modules directly with `testApplication { application { ... } }`. Avoid calling `Application.module()` in tests that should not require a real Postgres unless the test sets up an in-memory DB first.
|
|
|
|
### OIDC Platform Bootstrap
|
|
|
|
Applies to:
|
|
- `OidcClient.kt`
|
|
- `OidcResult.kt`
|
|
- platform `OidcClient.*.kt`
|
|
- `composeApp/src/androidMain/AndroidManifest.xml`
|
|
- `iosApp/iosApp/Info.plist`
|
|
- `iosApp/iosApp/iOSApp.swift`
|
|
- `iosApp/Podfile`
|
|
|
|
**Analog:** platform entry points and manifests
|
|
|
|
**Android activity pattern** (`MainActivity.kt` lines 10-19):
|
|
```kotlin
|
|
class MainActivity : ComponentActivity() {
|
|
override fun onCreate(savedInstanceState: Bundle?) {
|
|
enableEdgeToEdge()
|
|
super.onCreate(savedInstanceState)
|
|
|
|
setContent {
|
|
App()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Android manifest application/activity pattern** (`AndroidManifest.xml` lines 1-23):
|
|
```xml
|
|
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
|
|
<application
|
|
android:name=".MainApplication"
|
|
android:label="@string/app_name"
|
|
android:theme="@android:style/Theme.Material.Light.NoActionBar">
|
|
<activity
|
|
android:exported="true"
|
|
android:name=".MainActivity">
|
|
<intent-filter>
|
|
<action android:name="android.intent.action.MAIN"/>
|
|
<category android:name="android.intent.category.LAUNCHER"/>
|
|
</intent-filter>
|
|
</activity>
|
|
</application>
|
|
</manifest>
|
|
```
|
|
|
|
**iOS SwiftUI bootstrap pattern** (`iOSApp.swift` lines 1-15):
|
|
```swift
|
|
import SwiftUI
|
|
import ComposeApp
|
|
|
|
@main
|
|
struct iOSApp: App {
|
|
init() {
|
|
KoinIosKt.doInitKoin()
|
|
}
|
|
|
|
var body: some Scene {
|
|
WindowGroup {
|
|
ContentView()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**iOS plist pattern** (`Info.plist` lines 1-8):
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>CADisableMinimumFrameDurationOnPhone</key>
|
|
<true/>
|
|
</dict>
|
|
</plist>
|
|
```
|
|
|
|
**Target-specific main patterns** (`jvmMain/main.kt` lines 8-18, `webMain/main.kt` lines 8-14):
|
|
```kotlin
|
|
fun main() {
|
|
configureLogging()
|
|
initKoin()
|
|
application {
|
|
Window(
|
|
onCloseRequest = ::exitApplication,
|
|
title = "recipe",
|
|
) {
|
|
App()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```kotlin
|
|
@OptIn(ExperimentalComposeUiApi::class)
|
|
fun main() {
|
|
configureLogging()
|
|
initKoin()
|
|
ComposeViewport {
|
|
App()
|
|
}
|
|
}
|
|
```
|
|
|
|
**Planner note:** Preserve existing Koin bootstrap while adding AppAuth callback wiring. For `recipe://callback`, register Android AppAuth receiver and iOS `CFBundleURLTypes`; do not replace unrelated app metadata.
|
|
|
|
### Client AuthSession, Token Store, HTTP Client, and Common Tests
|
|
|
|
Applies to:
|
|
- `AuthState.kt`
|
|
- `AuthSession.kt`
|
|
- `TokenStore.kt`
|
|
- `AuthHttpClient.kt`
|
|
- `MeClient.kt`
|
|
- `SettingsFactory.*.kt`
|
|
- `HttpClientEngine.*.kt`
|
|
- `AuthSessionTest.kt`
|
|
|
|
**Analog:** Koin module pattern, platform main files, `ComposeAppCommonTest.kt`. There is no existing Ktor client or settings storage analog.
|
|
|
|
**Common test skeleton** (`ComposeAppCommonTest.kt` lines 1-10):
|
|
```kotlin
|
|
package dev.ulfrx.recipe
|
|
|
|
import kotlin.test.Test
|
|
import kotlin.test.assertEquals
|
|
|
|
class ComposeAppCommonTest {
|
|
@Test
|
|
fun example() {
|
|
assertEquals(3, 1 + 2)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Koin module registration analog** (`AppModule.kt` lines 5-9):
|
|
```kotlin
|
|
// Phase 2 adds authModule; Phase 4 adds syncModule; Phase 5 adds catalogModule; etc.
|
|
val appModule =
|
|
module {
|
|
// intentionally empty in Phase 1
|
|
}
|
|
```
|
|
|
|
**Required Ktor client bearer shape from `02-RESEARCH.md` lines 313-329:**
|
|
```kotlin
|
|
install(Auth) {
|
|
bearer {
|
|
loadTokens {
|
|
authSession.currentBearerTokens()
|
|
}
|
|
refreshTokens {
|
|
authSession.refreshBearerTokens()
|
|
}
|
|
sendWithoutRequest { request ->
|
|
request.url.host == apiHost
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Required auth state shape from `02-CONTEXT.md` lines 97-107:**
|
|
```kotlin
|
|
sealed class AuthState {
|
|
data object Loading : AuthState()
|
|
data object Unauthenticated : AuthState()
|
|
data class Authenticated(
|
|
val user: User,
|
|
val householdId: HouseholdId? = null,
|
|
) : AuthState()
|
|
}
|
|
```
|
|
|
|
**Planner note:** This group becomes the client auth canonical pattern for later phases. Keep collaborators injectable behind small interfaces so common tests can fake OIDC and `/me` without platform AppAuth.
|
|
|
|
## Shared Patterns
|
|
|
|
### Shared Module Purity
|
|
|
|
**Source:** `tools/verify-shared-pure.sh` lines 1-15
|
|
**Apply to:** all files under `shared/src/commonMain`
|
|
|
|
```bash
|
|
# Enforces INFRA-06 / D-19: shared/commonMain must not import Ktor, Compose, SQLDelight.
|
|
# Runs grep against shared/src/commonMain/ only. Allowed imports: kotlin.*, kotlinx.serialization, kotlinx.datetime.
|
|
VIOLATIONS=$(grep -rn -E '^import[[:space:]]+(io\.ktor|androidx\.compose|org\.jetbrains\.compose|app\.cash\.sqldelight)' shared/src/commonMain/ 2>/dev/null || true)
|
|
```
|
|
|
|
### Server Startup Order
|
|
|
|
**Source:** `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` lines 24-30
|
|
**Apply to:** `Application.kt`, auth plugin install, route wiring
|
|
|
|
```kotlin
|
|
fun Application.module() {
|
|
install(ContentNegotiation) {
|
|
json()
|
|
}
|
|
Database.migrate(this)
|
|
configureRouting()
|
|
}
|
|
```
|
|
|
|
Phase 2 should extend this to:
|
|
```text
|
|
ContentNegotiation -> CallLogging redaction -> Database.migrate -> Database.connect -> configureAuth -> configureRouting
|
|
```
|
|
|
|
### Server Logging
|
|
|
|
**Source:** `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` lines 7-8, 24, 36-39
|
|
**Apply to:** server DB/auth services
|
|
|
|
```kotlin
|
|
object Database {
|
|
private val log = LoggerFactory.getLogger(Database::class.java)
|
|
|
|
log.info("Connecting to {} as {} and running Flyway migrations", url, user)
|
|
log.error("Flyway migration failed", ex)
|
|
throw IllegalStateException("Database unreachable or migration failed", ex)
|
|
}
|
|
```
|
|
|
|
### Client Logging
|
|
|
|
**Source:** `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt` lines 1-8
|
|
**Apply to:** `AuthSession`, OIDC client wrappers
|
|
|
|
```kotlin
|
|
import co.touchlab.kermit.Logger
|
|
|
|
fun configureLogging() {
|
|
Logger.setTag("recipe")
|
|
// Platform log writers (OSLog iOS, LogCat Android, System.out JVM/Wasm) install by default.
|
|
}
|
|
```
|
|
|
|
Use `Logger.withTag("auth")` for auth flow diagnostics, but never log token bodies or `Authorization` headers.
|
|
|
|
### Koin Startup
|
|
|
|
**Source:** `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt` lines 7-10 and platform callers
|
|
**Apply to:** `authModule`, ViewModels, OIDC clients, settings factories
|
|
|
|
```kotlin
|
|
fun initKoin(config: KoinAppDeclaration? = null): KoinApplication =
|
|
startKoin {
|
|
config?.invoke(this)
|
|
modules(appModule)
|
|
}
|
|
```
|
|
|
|
### HOCON Env Vars
|
|
|
|
**Source:** `server/src/main/resources/application.conf` lines 11-18
|
|
**Apply to:** `oidc.issuer`, `oidc.audience`, `oidc.jwksUrl`, `oidc.leewaySeconds`
|
|
|
|
```hocon
|
|
database {
|
|
url = "jdbc:postgresql://localhost:5432/recipe"
|
|
url = ${?DATABASE_URL}
|
|
user = "recipe"
|
|
user = ${?DATABASE_USER}
|
|
password = "recipe"
|
|
password = ${?DATABASE_PASSWORD}
|
|
}
|
|
```
|
|
|
|
### Ktor Route Tests
|
|
|
|
**Source:** `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` lines 17-29
|
|
**Apply to:** `JwtAuthTest`, `MeRouteTest`
|
|
|
|
```kotlin
|
|
testApplication {
|
|
application {
|
|
install(ContentNegotiation) {
|
|
json()
|
|
}
|
|
configureRouting()
|
|
}
|
|
val response = client.get("/health")
|
|
assertEquals(HttpStatusCode.OK, response.status)
|
|
}
|
|
```
|
|
|
|
## No Analog Found
|
|
|
|
| File | Role | Data Flow | Reason |
|
|
|------|------|-----------|--------|
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/UsersTable.kt` | model | CRUD | No Exposed table exists yet. Phase 2 establishes first server table DSL pattern. |
|
|
| `server/src/main/kotlin/dev/ulfrx/recipe/auth/AuthPlugin.kt` JWT details | middleware | request-response | Ktor server exists, but no Authentication/JWT plugin exists yet. Use `02-CONTEXT.md` D-21/D-22 and Ktor docs from research. |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt` | service | request-response | No Ktor client code exists yet. Use `02-RESEARCH.md` Ktor bearer shape. |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/TokenStore.kt` | service | file-I/O | No multiplatform-settings usage exists yet. Keep explicit platform store seam. |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/LoginViewModel.kt` | controller | event-driven | Koin ViewModel deps exist, but no ViewModel classes exist yet. Use method-per-action `StateFlow` convention from project docs/UI spec. |
|
|
| `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/ui/screens/auth/PostLoginViewModel.kt` | controller | event-driven | Same as LoginViewModel. |
|
|
| `iosApp/Podfile` | config | build-config | No existing Podfile. Follow Plan 03 CocoaPods DSL and iOS deployment target from `composeApp/build.gradle.kts`. |
|
|
|
|
## Metadata
|
|
|
|
**Analog search scope:** `composeApp/`, `server/`, `shared/`, `iosApp/`, `build-logic/`, `gradle/`, `tools/`, Phase 1 summaries and Phase 2 plan drafts.
|
|
**Files scanned:** 75+ code/config/planning files via `rg --files`, `find`, and targeted `nl -ba` reads.
|
|
**Pattern extraction date:** 2026-04-27
|
|
|