honeyDueKMP/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ Important: This is the KMM mobile client repository. For full-stack documentation covering both the mobile app and backend API, see the root CLAUDE.md at ../CLAUDE.md.

Important Guidelines

⚠️ DO NOT auto-commit code changes. Always ask the user before committing. Only create commits when the user explicitly requests it with commands like "commit this work" or "create a commit".

Project Overview

MyCrib is a Kotlin Multiplatform Mobile (KMM) property management application with shared business logic and platform-specific UI implementations. The backend is a Django REST Framework API (located in the sibling myCribAPI directory).

Tech Stack:

• Shared (Kotlin): Compose Multiplatform for Android, networking layer, ViewModels, models
• iOS: SwiftUI with Kotlin shared layer integration via SKIE
• Backend: Django REST Framework (separate repository at ../myCribAPI)

Build Commands

Android

# Build debug APK
./gradlew :composeApp:assembleDebug

# Build release APK
./gradlew :composeApp:assembleRelease

# Run on connected device/emulator
./gradlew :composeApp:installDebug

iOS

# Build from command line (use Xcode for best experience)
xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' build

# Or open in Xcode
open iosApp/iosApp.xcodeproj

Desktop (JVM)

./gradlew :composeApp:run

Web

# Wasm target (modern browsers)
./gradlew :composeApp:wasmJsBrowserDevelopmentRun

# JS target (older browser support)
./gradlew :composeApp:jsBrowserDevelopmentRun

Architecture

Shared Kotlin Layer (composeApp/src/commonMain/kotlin/com/example/mycrib/)

Core Components:

1. APILayer (network/APILayer.kt)

   • Single entry point for all API calls
   • Manages caching via DataCache
   • Handles automatic cache updates on mutations (create/update/delete)
   • Pattern: Cache-first reads with optional forceRefresh parameter
   • Returns ApiResult<T> (Success/Error/Loading states)

2. DataCache (cache/DataCache.kt)

   • In-memory cache for lookup data (residence types, task categories, priorities, statuses, etc.)
   • Must be initialized via APILayer.initializeLookups() after login
   • Stores MutableState objects that UI can observe directly
   • Cleared on logout

3. TokenStorage (storage/TokenStorage.kt)

   • Platform-specific secure token storage
   • Android: EncryptedSharedPreferences
   • iOS: Keychain
   • All API calls automatically include token from TokenStorage

4. ViewModels (viewmodel/)

   • Shared ViewModels expose StateFlow for UI observation
   • Pattern: ViewModel calls APILayer → APILayer manages cache + network → ViewModel emits ApiResult states
   • ViewModels: ResidenceViewModel, TaskViewModel, AuthViewModel, ContractorViewModel, etc.

5. Navigation (navigation/)

   • Type-safe navigation using kotlinx.serialization
   • Routes defined as @Serializable data classes
   • Shared between Android Compose Navigation

Data Flow:

UI → ViewModel → APILayer → (Cache Check) → Network API → Update Cache → Return to ViewModel → UI observes StateFlow

iOS Layer (iosApp/iosApp/)

Integration Pattern:

• SwiftUI views wrap Kotlin ViewModels via @StateObject
• iOS-specific ViewModels (Swift) wrap shared Kotlin ViewModels
• Pattern: @Published var data in Swift observes Kotlin StateFlow via async iteration
• Navigation uses SwiftUI NavigationStack with sheets for modals

Key iOS Files:

• MainTabView.swift: Tab-based navigation
• *ViewModel.swift (Swift): Wraps shared Kotlin ViewModels, exposes @Published properties
• *View.swift: SwiftUI screens
• Directory structure mirrors feature organization (Residence/, Task/, Contractor/, etc.)

iOS ↔ Kotlin Bridge:

// Swift ViewModel wraps Kotlin ViewModel
@StateObject private var viewModel = ResidenceViewModel() // Swift wrapper
// Inside: let sharedViewModel: ComposeApp.ResidenceViewModel // Kotlin

// Observe Kotlin StateFlow
Task {
    for await state in sharedViewModel.residencesState {
        await MainActor.run {
            self.residences = (state as? ApiResultSuccess)?.data
        }
    }
}

Android Layer

Android uses Compose UI directly from composeApp with shared ViewModels. Navigation via Jetpack Compose Navigation in App.kt.

Environment Configuration

API Environment Toggle (composeApp/src/commonMain/kotlin/com/example/mycrib/network/ApiConfig.kt):

val CURRENT_ENV = Environment.DEV  // or Environment.LOCAL

• Environment.LOCAL: Points to http://10.0.2.2:8000/api (Android emulator) or http://127.0.0.1:8000/api (iOS simulator)
• Environment.DEV: Points to https://mycrib.treytartt.com/api

Change this to switch between local Django backend and production server.

Common Development Patterns

Adding a New API Endpoint

1. Add API call to appropriate *Api.kt class in network/ (e.g., TaskApi.kt)
2. Add method to APILayer.kt that manages caching (if applicable)
3. Add method to relevant ViewModel that calls APILayer
4. Update UI to observe the new StateFlow

Handling Platform-Specific Code

Use expect/actual pattern:

// commonMain
expect fun platformSpecificFunction(): String

// androidMain
actual fun platformSpecificFunction(): String = "Android"

// iosMain
actual fun platformSpecificFunction(): String = "iOS"

Type Conversions for iOS

Kotlin types bridge to Swift with special wrappers:

• Double → KotlinDouble (use KotlinDouble(double:) constructor)
• Int → KotlinInt (use KotlinInt(int:) constructor)
• String stays String
• Optional types: Kotlin nullable (Type?) becomes Swift optional (Type?)

Example iOS form submission:

// TextField uses String binding
@State private var estimatedCost: String = ""

// Convert to KotlinDouble for API
estimatedCost: estimatedCost.isEmpty ? nil : KotlinDouble(double: Double(estimatedCost) ?? 0.0)

Refreshing Lists After Mutations

iOS Pattern:

.sheet(isPresented: $showingAddForm) {
    AddFormView(
        isPresented: $showingAddForm,
        onSuccess: {
            viewModel.loadData(forceRefresh: true)
        }
    )
}

Android Pattern:

// Use savedStateHandle to pass refresh flag between screens
navController.previousBackStackEntry?.savedStateHandle?.set("refresh", true)
navController.popBackStack()

// In destination composable
val shouldRefresh = backStackEntry.savedStateHandle.get<Boolean>("refresh") ?: false
LaunchedEffect(shouldRefresh) {
    if (shouldRefresh) viewModel.loadData(forceRefresh = true)
}

Testing

Currently tests are minimal. When adding tests:

• Android: Place in composeApp/src/androidUnitTest/ or composeApp/src/commonTest/
• iOS: Use XCTest framework in Xcode project

Key Dependencies

• Kotlin Multiplatform: 2.1.0
• Compose Multiplatform: 1.7.1
• Ktor Client: Network requests
• kotlinx.serialization: JSON serialization
• kotlinx.coroutines: Async operations
• SKIE: Kotlin ↔ Swift interop improvements

Important Notes

Committing Changes

When committing changes that span both iOS and Android, commit them together in the KMM repository. If backend changes are needed, commit separately in the myCribAPI repository.

Data Cache Initialization

Critical: After user login, call APILayer.initializeLookups() to populate DataCache with reference data. Without this, dropdowns and pickers will be empty.

// After successful login
val initResult = APILayer.initializeLookups()
if (initResult is ApiResult.Success) {
    // Navigate to main screen
}

iOS Build Issues

If iOS build fails with type mismatch errors:

1. Check that cost fields (estimatedCost, actualCost, purchasePrice) use KotlinDouble, not String
2. Verify preview/mock data matches current model signatures
3. Clean build folder in Xcode (Cmd+Shift+K) and rebuild

Force Refresh Pattern

Always use forceRefresh: true when data should be fresh:

• After creating/updating/deleting items
• On pull-to-refresh gestures
• When explicitly requested by user

Without forceRefresh, APILayer returns cached data.

Project Structure Summary

MyCribKMM/
├── composeApp/
│   └── src/
│       ├── commonMain/kotlin/com/example/mycrib/
│       │   ├── cache/          # DataCache
│       │   ├── models/         # Shared data models
│       │   ├── network/        # APILayer, API clients
│       │   ├── repository/     # Additional data repositories
│       │   ├── storage/        # TokenStorage
│       │   ├── ui/             # Compose UI (Android)
│       │   │   ├── components/ # Reusable components
│       │   │   ├── screens/    # Screen composables
│       │   │   └── theme/      # Material theme
│       │   ├── viewmodel/      # Shared ViewModels
│       │   └── App.kt          # Android navigation
│       ├── androidMain/        # Android-specific code
│       ├── iosMain/            # iOS-specific Kotlin code
│       └── commonTest/         # Shared tests
│
├── iosApp/iosApp/
│   ├── *ViewModel.swift        # Swift wrappers for Kotlin VMs
│   ├── *View.swift             # SwiftUI screens
│   ├── Components/             # Reusable SwiftUI components
│   ├── Design/                 # Design system (spacing, colors)
│   ├── Extensions/             # Swift extensions
│   ├── Helpers/                # Utility helpers
│   ├── PushNotifications/      # APNs integration
│   └── [Feature]/              # Feature-grouped files
│       ├── Task/
│       ├── Residence/
│       ├── Contractor/
│       └── Documents/
│
└── gradle/                     # Gradle wrapper and configs

Related Repositories

• Backend API: ../myCribAPI - Django REST Framework backend
• Load Testing: ../myCribAPI/locust - Locust load testing scripts
• Documentation: ../myCribAPI/docs - Server configuration guides