# tbsten/cream architecture

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

- Interactive diagram: https://gitdiagram.com/tbsten/cream
- Repository: https://github.com/tbsten/cream

## Overview

##### Project type and purpose
- This is an open-source Kotlin Multiplatform library and toolset.
- cream-ksp: a KSP (Kotlin Symbol Processing) plugin that generates cross-class copy functions at compile time.
- cream-runtime: a Kotlin library providing the generated functions at runtime.
- buildLogic: a custom Gradle convention plugin to enforce consistent build settings.
- optionBuilder: a multiplatform sample/demo application (desktopApp, sharedUI, webApp) showcasing an interactive Option Builder UI.
- test module: validates core library behavior across platforms.

##### File structure
- Top-level modules:
- buildLogic/ : custom Gradle plugin (LintPlugin, DSL helpers)
- cream-ksp/ : KSP processor that reads annotations (@CopyTo, @CombineFrom, etc.) and emits Kotlin source in META-INF/services
- cream-runtime/ : core library consumed by user code and by optionBuilder
- optionBuilder/ : demo app with 3 sub-modules
– desktopApp (Compose Desktop main.kt)
– sharedUI (Compose Multiplatform UI components)
– webApp (JS target using sharedUI)
- test/ : multiplatform tests for functionality
- Configuration artifacts: build.gradle.kts at root, settings.gradle.kts, GitHub workflows, gradle.properties, gradle/libs.versions.toml

##### Readme insights
- The README describes:
- How cream-ksp hooks into KSP to generate mapping functions based on annotations.
- How cream-runtime supplies those functions at runtime for state transitions and data copy.
- A live Option Builder tool (optionBuilder) for visualizing and experimenting with configuration options.

##### Main components & relationships
- Developer’s project source (annotated Kotlin classes)
- Gradle build system + buildLogic plugin
- KSP processor (cream-ksp)
- Generated code (build/generated for commonMain and platform sources)
- Runtime library (cream-runtime)
- Demo application (optionBuilder: sharedUI → desktopApp/webApp)
- Unit/integration tests (test module)
1. Developer writes Kotlin code with cream annotations →
2. Gradle invokes KSP (cream-ksp) at compile time →
3. KSP scans source, emits generated Kotlin files →
4. Generated files + cream-runtime are compiled →
5. optionBuilder apps and user code invoke generated functions at runtime →
6. test module validates behavior
c. Architectural patterns & design principles:
- Plugin architecture: clear separation between compile-time (KSP) and runtime (library)
- Kotlin Multiplatform: commonMain, jsMain, jvmMain, desktop, web
- Convention over configuration: buildLogic plugin enforces common rules
- Modularization: each module has single responsibility (processor, runtime, UI, tests)

##### Key details to capture
- Exactly which modules depend on which (cream-ksp has no runtime dependency on cream-runtime, but generated code does).
- The multiplatform source sets in cream-runtime and optionBuilder/sharedUI.
- The custom Gradle plugin (buildLogic) hooking into all modules.
- Test module illustrating multiplatform validation.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Build Phase
  subgraph "Build Phase"
    subgraph "Root Configuration"
      RC1["build.gradle.kts"]:::config
      RC2["settings.gradle.kts"]:::config
      RC3["libs.versions.toml"]:::config
      RC4["gradle.yml"]:::config
      RC5["publish.yml"]:::config
    end

    subgraph "Gradle + buildLogic"
      BP1["LintPlugin"]:::buildtime
      BP2["Gradle DSL"]:::buildtime
      BP3["Ktlint DSL"]:::buildtime
      BP4["settings.gradle.kts"]:::buildtime
    end

    subgraph "KSP Processor"
      KP1["CreamSymbolProcessor.kt"]:::buildtime
      KP2["CreamSymbolProcessorProvider.kt"]:::buildtime
      KP3["SymbolProcessorProvider"]:::buildtime
      KP4["CreamOptions.kt"]:::buildtime
      KP5["CopyFunctionName.kt"]:::buildtime
    end
  end

  %% Compile & Package
  subgraph "Compile & Package"
    G1(("Generated Code")):::runtime
    subgraph "Runtime Library"
      R1["CopyTo.kt"]:::runtime
      R2["CopyFrom.kt"]:::runtime
      R3["CombineTo.kt"]:::runtime
      R4["CombineFrom.kt"]:::runtime
      R5["CopyMapping.kt"]:::runtime
      R6["CombineMapping.kt"]:::runtime
      R7["InternalCreamApi.kt"]:::runtime
    end
  end

  %% Runtime Phase
  subgraph "Runtime Phase"
    Dev["Developer Project Source"]:::app

    subgraph "OptionBuilder"
      subgraph "Shared UI Components"
        UI1["App.kt"]:::app
        UI2["InputOptionsSection.kt"]:::app
        UI3["CommonCard.kt"]:::app
        UI4["AppTheme.kt"]:::app
      end

      subgraph "Desktop App"
        DA1["main.kt"]:::app
        DA2["build.gradle.kts"]:::config
      end

      subgraph "Web App"
        WA1["main.kt"]:::app
        WA2["index.html"]:::config
      end
    end

    subgraph "Test Module"
      T1["Basic.kt"]:::test
      T2["ComplexTypes.kt"]:::test
      T3["BasicTest.kt"]:::test
      T4["VisibilityTest.kt"]:::test
    end
  end

  %% Connections
  Dev -->|"annotated source"| KP1
  RC1 --> BP1
  RC1 --> BP2
  RC1 --> BP3
  RC1 --> BP4
  BP1 --> KP1
  BP2 --> KP1
  BP3 --> KP1
  BP4 --> KP1
  KP1 -->|"process annotations"| G1
  KP2 --> G1
  KP3 --> G1
  KP4 --> G1
  KP5 --> G1
  G1 -->|"compiled with"| R1
  G1 --> R2
  G1 --> R3
  G1 --> R4
  G1 --> R5
  G1 --> R6
  G1 --> R7
  Dev -->|"uses mapping"| R1
  Dev --> R2
  Dev --> R3
  Dev --> R4
  Dev --> R5
  Dev --> R6
  Dev --> R7

  UI1 -->|"runtime library"| R1
  UI2 --> R2
  UI3 --> R3
  UI4 --> R4

  DA1 -->|"uses sharedUI"| UI1
  DA1 --> UI2
  WA1 -->|"uses sharedUI"| UI1
  WA1 --> UI3

  T1 --> G1
  T2 --> G1
  T3 --> R1
  T4 --> R1

  %% Click Events
  click BP1 "https://github.com/tbsten/cream/blob/main/buildLogic/convention/src/main/kotlin/LintPlugin.kt"
  click BP2 "https://github.com/tbsten/cream/blob/main/buildLogic/convention/src/main/kotlin/dsl/Gradle.kt"
  click BP3 "https://github.com/tbsten/cream/blob/main/buildLogic/convention/src/main/kotlin/dsl/Ktlint.kt"
  click BP4 "https://github.com/tbsten/cream/blob/main/buildLogic/settings.gradle.kts"

  click KP1 "https://github.com/tbsten/cream/blob/main/cream-ksp/src/main/kotlin/me/tbsten/cream/ksp/CreamSymbolProcessor.kt"
  click KP2 "https://github.com/tbsten/cream/blob/main/cream-ksp/src/main/kotlin/me/tbsten/cream/ksp/CreamSymbolProcessorProvider.kt"
  click KP3 "https://github.com/tbsten/cream/blob/main/cream-ksp/src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider"
  click KP4 "https://github.com/tbsten/cream/blob/main/cream-ksp/shared/src/commonMain/kotlin/me/tbsten/cream/ksp/options/CreamOptions.kt"
  click KP5 "https://github.com/tbsten/cream/blob/main/cream-ksp/shared/src/commonMain/kotlin/me/tbsten/cream/ksp/transform/CopyFunctionName.kt"

  click R1 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CopyTo.kt"
  click R2 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CopyFrom.kt"
  click R3 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CombineTo.kt"
  click R4 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CombineFrom.kt"
  click R5 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CopyMapping.kt"
  click R6 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/CombineMapping.kt"
  click R7 "https://github.com/tbsten/cream/blob/main/cream-runtime/src/commonMain/kotlin/me/tbsten/cream/InternalCreamApi.kt"

  click UI1 "https://github.com/tbsten/cream/blob/main/optionBuilder/sharedUI/src/commonMain/kotlin/me/tbsten/cream/App.kt"
  click UI2 "https://github.com/tbsten/cream/blob/main/optionBuilder/sharedUI/src/commonMain/kotlin/me/tbsten/cream/InputOptionsSection.kt"
  click UI3 "https://github.com/tbsten/cream/blob/main/optionBuilder/sharedUI/src/commonMain/kotlin/me/tbsten/cream/components/CommonCard.kt"
  click UI4 "https://github.com/tbsten/cream/blob/main/optionBuilder/sharedUI/src/commonMain/kotlin/me/tbsten/cream/theme/AppTheme.kt"

  click DA1 "https://github.com/tbsten/cream/blob/main/optionBuilder/desktopApp/src/main/kotlin/main.kt"
  click DA2 "https://github.com/tbsten/cream/blob/main/optionBuilder/desktopApp/build.gradle.kts"

  click WA1 "https://github.com/tbsten/cream/blob/main/optionBuilder/webApp/src/commonMain/kotlin/main.kt"
  click WA2 "https://github.com/tbsten/cream/blob/main/optionBuilder/webApp/src/commonMain/resources/index.html"

  click T1 "https://github.com/tbsten/cream/blob/main/test/src/commonMain/kotlin/me/tbsten/cream/test/combineFrom/Basic.kt"
  click T2 "https://github.com/tbsten/cream/blob/main/test/src/commonMain/kotlin/me/tbsten/cream/test/copyTo/ComplexTypes.kt"
  click T3 "https://github.com/tbsten/cream/blob/main/test/src/commonTest/kotlin/me/tbsten/cream/test/combineFrom/BasicTest.kt"
  click T4 "https://github.com/tbsten/cream/blob/main/test/src/commonTest/kotlin/me/tbsten/cream/test/copyTo/VisibilityTest.kt"

  click RC1 "https://github.com/tbsten/cream/blob/main/build.gradle.kts"
  click RC2 "https://github.com/tbsten/cream/blob/main/settings.gradle.kts"
  click RC3 "https://github.com/tbsten/cream/blob/main/gradle/libs.versions.toml"
  click RC4 "https://github.com/tbsten/cream/blob/main/.github/workflows/gradle.yml"
  click RC5 "https://github.com/tbsten/cream/blob/main/.github/workflows/publish.yml"

  %% Styles
  classDef buildtime fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
  classDef runtime fill:#DFFFE0,stroke:#228B22,stroke-width:1px
  classDef app fill:#FFE0B2,stroke:#FF8C00,stroke-width:1px
  classDef test fill:#EEEEEE,stroke:#888888,stroke-width:1px
  classDef config fill:#F3E5F5,stroke:#8A2BE2,stroke-width:1px
```
