# xxfast/nytimes-kmp architecture

> Architecture diagram of the GitHub repository xxfast/nytimes-kmp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xxfast/nytimes-kmp
- Repository: https://github.com/xxfast/nytimes-kmp

## Overview

##### Project Type and Purpose
- This is a Kotlin Multiplatform (KMP) application showcasing the New York Times on multiple targets (Android, WearOS, iOS, Desktop, Web‐JS, Web‐WASM).
- Its purpose is to share as much UI and business logic as possible via Compose Multiplatform, Ktor networking, Kotlinx Serialization, Decompose for navigation, Molecule for state, and KStore for persistence.

##### File Structure Analysis
- Top‐level “app” folder contains subprojects per platform:
- app/android, app/wear, app/desktop, app/ios, app/web
- Each has its own Gradle config and entry point (MainActivity.kt, Application.kt, etc.).
- Shared code under app/src:
- commonMain: shared domain, API client (NyTimesWebService), models, navigation ViewModel, UI components, DI, resources, utils
- platform‐specific sources (androidMain, desktopMain, iosMain, jsMain, wasmJsMain) override or adapt storage, WindowInsets, navigation bindings, AppDelegate, etc.
- Build orchestration: Gradle Kotlin DSL, settings.gradle.kts, libs.versions.toml, GitHub workflows.

##### README Insights
- Key libraries: Compose Multiplatform (UI), Ktor (HTTP), Kotlinx Serialization, Datetime, KStore (local storage), Decompose+Router (navigation), Molecule (state), compose-imageloader.
- Execution: each platform has a run configuration.

a. Main Components
- Shared Core Module
- UI layer (Compose Multiplatform)
- Navigation & State (Decompose + Molecule + ViewModels)
- Domain & Data layer
– Models (ApiModels, StorageModels)
– Repository/Storage (KStore)
– API client (Ktor HttpClient, NyTimesWebService)
- Platform Adapters
- androidMain, iosMain, desktopMain, jsMain, wasmJsMain: provide platform bindings (WindowInsets, AppDelegate, Application launcher, Storage implementation)
- Platform‐specific Applications
- Android app
- WearOS app
- iOS app
- Desktop app
- Web‐JS & Web‐WASM app
- External Service
- New York Times REST API

b. Relationships & Data Flow
1. UI (Compose) sends user interactions → ViewModel
2. ViewModel invokes domain/data layer → Repository
3. Repository
‐ checks local store (KStore)
‐ if stale or missing, uses Ktor client to fetch from NYT API
‐ stores fresh data in KStore
4. Repository returns models → ViewModel → UI updates
5. Navigation handled via Decompose Router between screens

c. Architectural Patterns
- MVVM / MVI hybrid with ViewModels driving state via Molecule
- Clean separation: UI / Presentation / Domain / Data
- Dependency Injection via a simple DI object (AppStorage) in commonMain

d. Key Technologies
- Kotlin Multiplatform & Gradle
- Compose Multiplatform
- Ktor + Kotlinx Serialization
- KStore for persistence
- Decompose + Router for navigation
- Molecule for reactive state
- Compose-imageloader for images

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shared Core Module
    subgraph "Shared Core" 
        direction TB
        UI["UI Layer<br/>(Compose)"] 
        Nav["Navigation & State<br/>(Decompose + Molecule)"] 
        Repo["Repository"]
        subgraph "Domain & Data"
            direction TB
            ModelsApi["ApiModels"] 
            ModelsStorage["StorageModels"]
            Service["API Client<br/>NyTimesWebService"]
            HttpClient["HTTP Client<br/>HttpClient"]
            Store["Persistence<br/>KStore"]
            DI["DI<br/>AppStorage"]
        end
    end

    %% Platform Adapters
    subgraph "Platform Adapters"
        direction TB
        AndroidStorage["Android Storage Adapter"] 
        AndroidNavBind["Android Navigation Binding"]
        AndroidInsets["Android WindowInsets Adapter"]
        DesktopStorage["Desktop Storage Adapter"]
        DesktopNavBind["Desktop Navigation Binding"]
        DesktopInsets["Desktop WindowInsets Adapter"]
        iOSAppDelegate["iOS AppDelegate"]
        iOSLauncher["iOS Application Launcher"]
        iOSStorage["iOS Storage Adapter"]
        iOSNavBind["iOS Navigation Binding"]
        iOSInsets["iOS WindowInsets Adapter"]
        JSStorage["JS Storage Adapter"]
        JSNavBind["JS Navigation Binding"]
        JSInsets["JS WindowInsets Adapter"]
        WASMStorage["WASM Storage Adapter"]
        WASMNavBind["WASM Navigation Binding"]
        WASMInsets["WASM WindowInsets Adapter"]
    end

    %% Platform Applications
    subgraph "Platform Applications"
        direction TB
        AndroidApp["Android App"]
        WearApp["WearOS App"]
        DesktopApp["Desktop App"]
        iOSApp["iOS App"]
        WebJSApp["Web‐JS App"]
        WebWASMApp["Web‐WASM App"]
    end

    %% External Service
    NYTAPI["New York Times REST API"]

    %% Connections within Shared Core
    UI -->|user interaction| Nav
    Nav -->|calls| Repo
    Repo -->|reads/writes| Store
    Repo -->|fetches| Service
    Service -->|HTTP| NYTAPI
    Repo -->|uses| HttpClient
    Repo -->|provides| ModelsApi
    Repo -->|provides| ModelsStorage
    Repo -->|injected by| DI
    Store <-->|persists data| ModelsStorage

    %% Platform App to Adapters
    AndroidApp --> AndroidStorage
    AndroidApp --> AndroidNavBind
    AndroidApp --> AndroidInsets

    WearApp --> AndroidStorage
    WearApp --> AndroidNavBind
    WearApp --> AndroidInsets

    DesktopApp --> DesktopStorage
    DesktopApp --> DesktopNavBind
    DesktopApp --> DesktopInsets

    iOSApp --> iOSAppDelegate
    iOSApp --> iOSLauncher
    iOSApp --> iOSStorage
    iOSApp --> iOSNavBind
    iOSApp --> iOSInsets

    WebJSApp --> JSStorage
    WebJSApp --> JSNavBind
    WebJSApp --> JSInsets

    WebWASMApp --> WASMStorage
    WebWASMApp --> WASMNavBind
    WebWASMApp --> WASMInsets

    %% Adapters to Shared Core
    AndroidStorage --> Store
    AndroidNavBind --> Nav
    AndroidInsets --> UI

    DesktopStorage --> Store
    DesktopNavBind --> Nav
    DesktopInsets --> UI

    iOSStorage --> Store
    iOSNavBind --> Nav
    iOSInsets --> UI
    iOSAppDelegate --> UI
    iOSLauncher --> UI

    JSStorage --> Store
    JSNavBind --> Nav
    JSInsets --> UI

    WASMStorage --> Store
    WASMNavBind --> Nav
    WASMInsets --> UI

    AndroidApp:::apps
    WearApp:::apps
    DesktopApp:::apps
    iOSApp:::apps
    WebJSApp:::apps
    WebWASMApp:::apps

    UI:::core
    Nav:::core
    Repo:::core
    ModelsApi:::core
    ModelsStorage:::core
    Service:::core
    HttpClient:::core
    Store:::core
    DI:::core

    AndroidStorage:::adapters
    AndroidNavBind:::adapters
    AndroidInsets:::adapters
    DesktopStorage:::adapters
    DesktopNavBind:::adapters
    DesktopInsets:::adapters
    iOSAppDelegate:::adapters
    iOSLauncher:::adapters
    iOSStorage:::adapters
    iOSNavBind:::adapters
    iOSInsets:::adapters
    JSStorage:::adapters
    JSNavBind:::adapters
    JSInsets:::adapters
    WASMStorage:::adapters
    WASMNavBind:::adapters
    WASMInsets:::adapters

    NYTAPI:::external

    %% Click events
    click UI "https://github.com/xxfast/nytimes-kmp/tree/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/components"
    click Nav "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click Service "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/api/NyTimesWebService.kt"
    click HttpClient "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/data/HttpClient.kt"
    click Store "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/data/KStore.kt"
    click DI "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/di/AppStorage.kt"
    click ModelsApi "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/models/ApiModels.kt"
    click ModelsStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/commonMain/kotlin/io/github/xxfast/nytimes/models/StorageModels.kt"

    click AndroidStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/androidMain/kotlin/io/github/xxfast/nytimes/data/Storage.kt"
    click AndroidNavBind "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/androidMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click AndroidInsets "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/androidMain/kotlin/io/github/xxfast/nytimes/utils/WindowInsets.kt"

    click DesktopStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/desktopMain/kotlin/io/github/xxfast/nytimes/data/Storage.kt"
    click DesktopNavBind "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/desktopMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click DesktopInsets "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/desktopMain/kotlin/io/github/xxfast/nytimes/utils/WindowInsets.kt"

    click iOSAppDelegate "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/iosMain/kotlin/io/github/xxfast/nytimes/AppDelegate.kt"
    click iOSLauncher "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/iosMain/kotlin/io/github/xxfast/nytimes/Application.kt"
    click iOSStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/iosMain/kotlin/io/github/xxfast/nytimes/data/Storage.kt"
    click iOSNavBind "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/iosMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click iOSInsets "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/iosMain/kotlin/io/github/xxfast/nytimes/utils/WindowInsets.kt"

    click JSStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/jsMain/kotlin/io/github/xxfast/nytimes/data/Storage.kt"
    click JSNavBind "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/jsMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click JSInsets "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/jsMain/kotlin/io/github/xxfast/nytimes/utils/WindowInsets.kt"

    click WASMStorage "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/wasmJsMain/kotlin/io/github/xxfast/nytimes/data/Storage.kt"
    click WASMNavBind "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/wasmJsMain/kotlin/io/github/xxfast/nytimes/navigation/ViewModel.kt"
    click WASMInsets "https://github.com/xxfast/nytimes-kmp/blob/main/app/src/wasmJsMain/kotlin/io/github/xxfast/nytimes/utils/WindowInsets.kt"

    click AndroidApp "https://github.com/xxfast/nytimes-kmp/blob/main/app/android/src/main/java/io/github/xxfast/nytimes/android/MainActivity.kt"
    click DesktopApp "https://github.com/xxfast/nytimes-kmp/blob/main/app/desktop/src/main/kotlin/io/github/xxfast/nytimes/desktop/Application.kt"
    click iOSApp "https://github.com/xxfast/nytimes-kmp/blob/main/app/ios/ios/AppDelegate.swift"
    click WebJSApp "https://github.com/xxfast/nytimes-kmp/blob/main/app/web/src/jsMain/kotlin/io/github/xxfast/nytimes/web/Application.kt"
    click WebWASMApp "https://github.com/xxfast/nytimes-kmp/blob/main/app/web/src/wasmJsMain/kotlin/io/github/xxfast/nytimes/web/Application.kt"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef adapters fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef apps fill:#FAD7A0,stroke:#B9770E,color:#7E5109
    classDef external fill:#D5D8DC,stroke:#85929E,color:#1B2631
```
