kmp-data-layer

Files (1)

• SKILL.md

SKILL.md (first lines)

# KMP Data Layer

> Content flows: JSON catalog -> CatalogService -> ContentRepository -> UI (Compose/SwiftUI). The shared-core module owns all data logic. Platform apps only consume repositories via ServiceLocator.

## Architecture overview

```
JSON / API
    |
CatalogService (implements CatalogSource interface)
    |
ContentRepository (caches + queries)
    |
ServiceLocator (provides singleton instances)
    |
UI Layer (MainActivity / SwiftUI views)
```

## Core data model: ContentItem

```kotlin
// shared-core/src/commonMain/kotlin/models/ContentItem.kt

data class ContentItem(
    val id: String,
    val title: String,
    val description: String? = null,
    val thumbnailUrl: String? = null,
    val contentType: ContentType,          // Video, Audio, Image, Mixed
    val metadata: ContentMetadata = ContentMetadata(),
    val isOfflineAvailable: Boolean = false,
    val lastAccessed: Long? = null,
    val focusable: Boolean = true,
    val collections: List<String> = emptyList(),
    val tags: List<String> = emptyList(),
    val priority: Int = 0,                 // Higher = more prominent in UI
    val videoUrl: String? = null,
)
```

### ContentMetadata

```kotlin
data class ContentMetadata(
    val genre: String? = null,
    val rating: String? = null,
    val releaseDate: String? = null,
    val duration: Long? = null,
    val director: String? = null,
    val cast: List<String> = emptyList(),
)
```

### ContentType enum

```kotlin
enum class ContentType { Video, Audio, Image, Mixed }
```

## Repository pattern

### Interface

```kotlin
// shared-core/src/commonMain/kotlin/repositories/ContentRepository.kt

interface ContentRepository {
    suspend fun getContentItems(limit: Int = 50, offset: Int = 0): Result<List<ContentItem>>
    suspend fun getContentItem(id: String): Result<ContentItem?>
    suspend fun searchContent(query: String): Result<List<ContentItem>>
    suspend fun markContentAccessed(contentId: String): Result<Unit>
}
```

### Implementation

`ContentRepositoryImpl` wraps a `CatalogSource` and adds:
- **Lazy loading:** catalog is fetched once, then cached in-memory
- **Thread safety:** `Mutex` protects the content map
- **Sorting:** items returned sorted by `priority` descending
- **Search:** filters by title, description, and tags (case-insensitive)

### Result type

```kotlin
sealed class Result<out T> {
    data class Success<T>(val data: T) : Result<T>()
    data class Error(val exception: Exception? = null, val message: String? = null) : Result<Nothing>()
}
```

UI code uses `onSuccess`/`onFailure` extension methods for clean handling.

## CatalogService — loading content

```kotlin
interface CatalogSource {
    suspend fun fetchCatalog(): Result<List<ContentItem>>
}
```

The default `CatalogService` implementation loads content from a JSON endpoint or bundled file. To wire custom content:

### Option 1: Replace the JSON source

Implement `CatalogSource` to read from your content.json:

```kotlin
class CustomCatalogSource(private val jsonString: String) : CatalogSource {
    override suspend fun fetchCatalog(): Result<List<ContentItem>> {
        return try {
            val items = Json.decodeFromString<List<ContentItem>>(jsonString)
            Result.Success(items)
        } catch (e: Exception) {
            Result.Error(e, "Failed to parse catalog")
        }
    }
}
```

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness