# wokdsem/kioto architecture

> Architecture diagram of the GitHub repository wokdsem/kioto, 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/wokdsem/kioto
- Repository: https://github.com/wokdsem/kioto

## Overview

##### Project Type and Purpose
- This is a Kotlin Multiplatform library (Kioto) plus a sample “example” app demonstrating its usage on Android and iOS.
- Kioto provides a lightweight, opinionated UI/navigation framework for Compose Multiplatform Mobile, enforcing clean architecture via Nodes, NodeViews, NodeTokens, and a central NodeNav.

##### High-level Components
a. Kioto Library Module (“kioto/” folder)
- commonMain: Core abstractions – Node, NodeNav, NodeView, NodeToken, Context, Compose integration
- androidMain: Android-specific hosts and Platform.android.kt (NodeHost composable)
- iosMain: iOS-specific hosts and Platform.ios.kt (nodeHost UIViewController)
b. Sample Application Module (“example/” folder)
- commonMain: example business logic and features built on Kioto (Demo, Movies, Navigation features)
- androidMain: Android app entry point (MainActivity + AndroidManifest + resources)
- iosMain (exampleIOs/iosApp): iOS app project (Xcode files, Info.plist, SwiftUI UIViewControllerRepresentable)
c. Build & Configuration
- Gradle Kotlin DSL (build.gradle.kts, settings.gradle.kts, libs.versions.toml, gradle wrapper)
- exampleIOs Xcode configuration files (Config.xcconfig, pbxproj)

##### Relationships and Data Flow
1. At app launch (Android MainActivity or iOS UIViewController), an instance of NodeNav is created and configured with a root Token (e.g., Demo.Token).
2. NodeHost (Android) or nodeHost (iOS) renders a Compose tree that listens to NodeNav.
3. NodeNav drives a stack of Nodes; each Node is instantiated via its NodeToken (node() factory), holds its own State, subscribes to suspend/flow sources, and exposes a NodeView.
4. NodeView (a @Composable on Android or Swift-wrapped on iOS) renders UI for that Node’s State and invokes listener callbacks for events.
5. Callbacks call nav.navigate / nav.resetNavigation / presentStack / etc., which mutate the NodeNav stack. NodeNav emits new Node sequences, NodeHost recomposes accordingly.
6. Context and CompositionLocals (LocalPlatform, LocalNodeNavigation) flow down the Compose tree, allowing Nodes to retrieve dependencies (e.g., Logger).

##### Architectural Patterns & Design Principles
- Modular Node pattern: each UI screen is a Node (state + logic) + NodeView (UI) + NodeToken (factory glue).
- Centralized Navigation: NodeNav maintains a stack-of-stacks model, supporting push, pop, replace, present, and back gestures.
- Separation of concerns:
- Domain/data lives in commonMain of both kioto and example modules
- UI rendering lives in NodeView classes under commonMain + platform hosts in androidMain/iosMain
- Platform integration isolated in androidMain/iosMain of kioto
- Multiplatform consistency: shared API across Android and iOS, platform entry points only differ in host composables.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Application["Application\n(Entry Point)"]:::app

    subgraph "Kioto Core (commonMain)"
        direction TB
        Compose["Compose.kt"]:::library
        ContextC["Context.kt"]:::library
        Ext["Ext.kt"]:::library
        NodeC["Node.kt"]:::library
        NodeCommonHost["NodeCommonHost.kt"]:::library
        NodeNav["NodeNav.kt"]:::library
        Platform["Platform.kt"]:::library
    end

    subgraph "Kioto Android (androidMain)"
        direction TB
        NodeHostA["NodeHost.kt"]:::library
        PlatformA["Platform.android.kt"]:::library
    end

    subgraph "Kioto iOS (iosMain)"
        direction TB
        NodeHostI["NodeHost.kt"]:::library
        PlatformI["Platform.ios.kt"]:::library
    end

    subgraph "Example Common (example/src/commonMain)"
        direction TB
        App["App.kt"]:::app
        MoviesData["Movies.kt"]:::app
        Logger["Logger.kt"]:::app
        Domain["Movie.kt"]:::app
        FeaturesCtx["Context.kt"]:::app
        DemoTok["Demo.kt"]:::app
        DemoView["DemoView.kt"]:::app
        AdvTok["MovieAdvisor.kt"]:::app
        AdvView["MovieAdvisorView.kt"]:::app
        DetailTok["MovieDetail.kt"]:::app
        DetailView["MovieDetailView.kt"]:::app
        NavTok["Navigation.kt"]:::app
        NavView["NavigationView.kt"]:::app
        Screen["Screen.kt"]:::app
    end

    subgraph "Example Android (example/src/androidMain)"
        direction TB
        AndroidManifest["AndroidManifest.xml"]:::app
        ExampleAppA["ExampleApplication.kt"]:::app
        MainActivity["MainActivity.kt"]:::app
    end

    subgraph "Example iOS Entry (example/src/iosMain)"
        direction TB
        ExampleAppI["ExampleIOsApplication.kt"]:::app
    end

    subgraph "Example iOS Xcode (exampleIOs)"
        direction TB
        Xcconfig["Config.xcconfig"]:::app
        Pbxproj["project.pbxproj"]:::app
        InfoPlist["Info.plist"]:::app
        iOSApp["iOSApp.swift"]:::app
        Assets["Assets.xcassets"]:::app
    end

    Application -->|creates| NodeNav
    MainActivity -->|setContent| NodeHostA
    NodeHostA -->|listens| NodeNav
    ExampleAppI -->|getNodeNav| NodeHostI
    NodeHostI -->|listens| NodeNav
    NodeNav -->|factory| NodeC
    NodeC -->|renders| NodeCommonHost
    NodeCommonHost -->|produces| NodeView["NodeView"]:::library
    NodeView -->|events| NodeNav

    classDef library fill:#D0E8FF,stroke:#4D8FAC;
    classDef app fill:#D0F5C0,stroke:#3D8B37;

    click Compose "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/Compose.kt"
    click ContextC "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/Context.kt"
    click Ext "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/Ext.kt"
    click NodeC "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/Node.kt"
    click NodeCommonHost "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/NodeCommonHost.kt"
    click NodeNav "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/NodeNav.kt"
    click Platform "https://github.com/wokdsem/kioto/blob/main/kioto/src/commonMain/kotlin/com/wokdsem/kioto/Platform.kt"
    click NodeHostA "https://github.com/wokdsem/kioto/blob/main/kioto/src/androidMain/kotlin/com/wokdsem/kioto/NodeHost.kt"
    click PlatformA "https://github.com/wokdsem/kioto/blob/main/kioto/src/androidMain/kotlin/com/wokdsem/kioto/Platform.android.kt"
    click NodeHostI "https://github.com/wokdsem/kioto/blob/main/kioto/src/iosMain/kotlin/com/wokdsem/kioto/NodeHost.kt"
    click PlatformI "https://github.com/wokdsem/kioto/blob/main/kioto/src/iosMain/kotlin/com/wokdsem/kioto/Platform.ios.kt"
    click App "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/App.kt"
    click MoviesData "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/data/Movies.kt"
    click Logger "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/deps/Logger.kt"
    click Domain "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/domain/Movie.kt"
    click FeaturesCtx "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/Context.kt"
    click DemoTok "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/demo/Demo.kt"
    click DemoView "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/demo/DemoView.kt"
    click AdvTok "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/movies/advisor/MovieAdvisor.kt"
    click AdvView "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/movies/advisor/MovieAdvisorView.kt"
    click DetailTok "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/movies/movie/MovieDetail.kt"
    click DetailView "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/movies/movie/MovieDetailView.kt"
    click NavTok "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/navigation/Navigation.kt"
    click NavView "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/features/navigation/NavigationView.kt"
    click Screen "https://github.com/wokdsem/kioto/blob/main/example/src/commonMain/kotlin/com/wokdsem/kioto/example/ui/Screen.kt"
    click AndroidManifest "https://github.com/wokdsem/kioto/blob/main/example/src/androidMain/AndroidManifest.xml"
    click ExampleAppA "https://github.com/wokdsem/kioto/blob/main/example/src/androidMain/kotlin/com/wokdsem/kioto/example/ExampleApplication.kt"
    click MainActivity "https://github.com/wokdsem/kioto/blob/main/example/src/androidMain/kotlin/com/wokdsem/kioto/example/MainActivity.kt"
    click ExampleAppI "https://github.com/wokdsem/kioto/blob/main/example/src/iosMain/kotlin/com/wokdsem/kioto/example/ExampleIOsApplication.kt"
    click Xcconfig "https://github.com/wokdsem/kioto/blob/main/exampleIOs/Configuration/Config.xcconfig"
    click Pbxproj "https://github.com/wokdsem/kioto/blob/main/exampleIOs/iosApp.xcodeproj/project.pbxproj"
    click InfoPlist "https://github.com/wokdsem/kioto/blob/main/exampleIOs/iosApp/Info.plist"
    click iOSApp "https://github.com/wokdsem/kioto/blob/main/exampleIOs/iosApp/iOSApp.swift"
    click Assets "https://github.com/wokdsem/kioto/blob/main/exampleIOs/iosApp/Assets.xcassets"
```
