# tencent-tds/kuiklyui architecture

> Architecture diagram of the GitHub repository tencent-tds/kuiklyui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencent-tds/kuiklyui
- Repository: https://github.com/tencent-tds/kuiklyui

## Overview

##### Project type and purpose
- This is an open-source, cross-platform UI framework (Kuikly) built with Kotlin Multiplatform.
- It supplies a unified core runtime (layout, rendering, event dispatch, DSL) plus platform-specific renderer modules for Android and iOS.
- It also includes code-generation/annotation-processing modules and two host shell apps (androidApp, iosApp) to demonstrate integration.

##### File structure
- Top-level modules:
- buildSrc – shared Gradle logic and build variables
- core-annotations, core-kapt, core-ksp – annotation definitions & processors that generate entry points for the core
- core – the multiplatform “business logic” and rendering pipeline abstractions (commonMain + androidMain/jvmMain/iosMain)
- core-render-android – Android-specific rendering implementation producing an AAR
- core-render-ios – iOS-specific rendering implementation producing a framework
- demo – sample code and assets using the library’s DSL
- androidApp, iosApp – host shell projects that consume the published artifacts and launch a Kuikly render view
- Auxiliary files: various Gradle/Kotlin version test scripts, Gradle wrapper, CI config, docs, license.

##### README for additional insights
- Confirms the layering: “core” for cross-platform, separate renderer modules, annotation-processor modules, host apps, demo.
- Highlights technologies: Kotlin Multiplatform, Gradle, KAPT, KSP, CocoaPods, Android Studio, Xcode.

##### Components
a. Build & code-generation layer
- Gradle (+ buildSrc) orchestrates compilation.
- core-annotations defines @Page etc.
- core-kapt / core-ksp generate entry boilerplate (KuiklyCoreProcessor)
b. Core runtime layer
- `core` module (commonMain) implements: UI tree, layout (Flex), reactive system, event dispatch, modules (Router, Network, etc.).
- Platform bridges (`NativeBridge`) provide serialization & communication.
c. Platform renderer layer
- core-render-android: IKuiklyRenderView → Android ViewAdapterManager → native Canvas/Views
- core-render-ios: KuiklyRenderView → native CALayer/UIView renderers
d. Host shell & demo apps
- androidApp & iosApp import published artifacts (.aar, .framework).
- Demo assets/JSON/PAG files feed the core runtime.
e. External services & tools
- Kotlin MPP plugin, Gradle Daemon, AAPT (Android), CocoaPods / Xcode (iOS).

##### Relationships & interactions
- Build flow: Gradle → annotation processors → compile core + renderers → produce artifacts
- Runtime flow: Host App → instantiate KuiklyRenderView → load JSON/DSL → Core runtime builds VirtualView tree → renderer adapter draws native UI → event callbacks propagate back through NativeBridge → Core signals user code
- Demo app plugs into Core APIs to showcase components and modules (e.g., KRRouterModule).

##### Architectural patterns & design principles
- Layered architecture: codegen → core runtime → platform adapters → host integration
- Plugin/Module pattern: pluggable modules (Notify, Network, TDF, Performance) registered via ModuleAccessor
- Dependency inversion: core references interfaces (IKuiklyRenderView, IKRImageAdapter) implemented by platform modules
- Reactive & declarative paradigms coexisting: reactive properties + DSL compose

##### Detail
- Module boundary and interaction point: annotation processor → generated entry → core init → renderer adapter → native view
- Don’t shy away from showing subcomponents: e.g., core-render-android’s AdapterManager, scheduler threads, performance monitors
- The more granular (modules, packages, processors, adapters) you show, the clearer the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Codegen Layer
    subgraph "Build & Codegen Layer"
        direction TB
        BuildSrc["buildSrc"]:::build
        CoreAnnotations["core-annotations"]:::build
        CoreKAPT["core-kapt"]:::build
        CoreKSP["core-ksp"]:::build
        BuildSrc -->|"provides Gradle logic"| CoreKAPT
        BuildSrc -->|"provides Gradle logic"| CoreKSP
        CoreAnnotations -->|"annotations for codegen"| CoreKAPT
        CoreAnnotations -->|"annotations for codegen"| CoreKSP
        CoreKAPT -->|"generates entry boilerplate"| CoreJar(("core-processor.jar")):::artifact
        CoreKSP -->|"generates entry boilerplate"| CoreJar
    end

    %% Core Runtime Layer
    subgraph "Core Runtime Layer"
        direction TB
        CoreModule["core"]:::core
        CoreJar -->|"compile-time"| CoreModule
        subgraph "Core Sources"
            direction TB
            CommonMain["commonMain"]:::core
            AndroidMain["androidMain"]:::core
            iOSMain["iosMain"]:::core
            JVMMain["jvmMain"]:::core
            CommonMain --> CoreModule
            AndroidMain --> CoreModule
            iOSMain --> CoreModule
            JVMMain --> CoreModule
        end
    end

    %% Platform Renderers
    subgraph "Platform Renderer Layer"
        direction TB
        subgraph "Android Renderer"
            direction TB
            AndroidRender["core-render-android"]:::render
            AndroidAdapters["IKuiklyRenderView & Adapters"]:::render
            AdapterManager["AdapterManager & Context Handlers"]:::render
            SchedulerPerf["Scheduler & Performance"]:::render
            AndroidRender --> AndroidAdapters
            AndroidRender --> AdapterManager
            AndroidRender --> SchedulerPerf
            AndroidAdapters -->|"implements interfaces"| CoreModule
            AndroidRender -->|"produces"| AAR(("kuikly-android.aar")):::artifact
        end
        subgraph "iOS Renderer"
            direction TB
            iOSRender["core-render-ios"]:::render
            iOSCore["Core Framework"]:::render
            iOSExt["Extension Components"]:::render
            iOSHandler["Handlers & Protocols"]:::render
            iOSPerf["Performance & Threading"]:::render
            iOSView["View Entrypoint"]:::render
            iOSRender --> iOSCore
            iOSRender --> iOSExt
            iOSRender --> iOSHandler
            iOSRender --> iOSPerf
            iOSRender --> iOSView
            CoreModule --> iOSCore
            iOSRender -->|"produces"| FRAME(("kuikly-ios.framework")):::artifact
        end
    end

    %% Host Shell Apps & Demo
    subgraph "Host Shell Apps & Demo"
        direction TB
        Demo["demo"]:::host
        AndroidApp["androidApp"]:::host
        iOSApp["iosApp"]:::host
        Demo -->|"uses DSL & assets"| CoreModule
        AndroidApp -->|"imports .aar & jar"| AAR
        AndroidApp -->|"imports jar"| CoreJar
        iOSApp -->|"imports .framework & jar"| FRAME
        iOSApp -->|"imports jar"| CoreJar
    end

    %% Click Events
    click BuildSrc "https://github.com/tencent-tds/kuiklyui/tree/main/buildSrc/"
    click CoreAnnotations "https://github.com/tencent-tds/kuiklyui/tree/main/core-annotations/"
    click CoreKAPT "https://github.com/tencent-tds/kuiklyui/tree/main/core-kapt/"
    click CoreKSP "https://github.com/tencent-tds/kuiklyui/tree/main/core-ksp/"
    click CommonMain "https://github.com/tencent-tds/kuiklyui/tree/main/core/src/commonMain/"
    click AndroidMain "https://github.com/tencent-tds/kuiklyui/tree/main/core/src/androidMain/"
    click iOSMain "https://github.com/tencent-tds/kuiklyui/tree/main/core/src/iosMain/"
    click JVMMain "https://github.com/tencent-tds/kuiklyui/tree/main/core/src/jvmMain/"
    click AndroidRender "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-android/"
    click AndroidAdapters "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-android/src/main/java/com/tencent/kuikly/core/render/android/"
    click AdapterManager "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-android/src/main/java/com/tencent/kuikly/core/render/android/adapter/"
    click SchedulerPerf "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-android/src/main/java/com/tencent/kuikly/core/render/android/scheduler/"
    click iOSRender "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/"
    click iOSCore "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/Core/"
    click iOSExt "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/Extension/"
    click iOSHandler "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/Handler/"
    click iOSPerf "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/Performance/"
    click iOSView "https://github.com/tencent-tds/kuiklyui/tree/main/core-render-ios/View/"
    click Demo "https://github.com/tencent-tds/kuiklyui/tree/main/demo/"
    click AndroidApp "https://github.com/tencent-tds/kuiklyui/tree/main/androidApp/"
    click iOSApp "https://github.com/tencent-tds/kuiklyui/tree/main/iosApp/"

    %% Styles
    classDef build fill:#F5B041,stroke:#E67E22,color:#000
    classDef core fill:#AED6F1,stroke:#3498DB,color:#000
    classDef render fill:#A9DFBF,stroke:#27AE60,color:#000
    classDef host fill:#D2B4DE,stroke:#8E44AD,color:#000
    classDef artifact fill:#F2F3F4,stroke:#7F8C8D,color:#000

    class BuildSrc,CoreAnnotations,CoreKAPT,CoreKSP build
    class CoreModule,CommonMain,AndroidMain,iOSMain,JVMMain core
    class AndroidRender,AndroidAdapters,AdapterManager,SchedulerPerf,iOSRender,iOSCore,iOSExt,iOSHandler,iOSPerf,iOSView render
    class Demo,AndroidApp,iOSApp host
    class CoreJar,AAR,FRAME artifact
```
