# theaniketraj/project-karl architecture

> Architecture diagram of the GitHub repository theaniketraj/project-karl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theaniketraj/project-karl
- Repository: https://github.com/theaniketraj/project-karl

## Overview

#### Purpose and entry points
KARL is a Kotlin library for private, on-device incremental learning from application interaction metadata. Its core is Kotlin Multiplatform; the runnable JVM desktop integration is `karl-example-desktop/src/jvmMain/kotlin/Main.kt`. Consumers primarily create and operate containers through `karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt`.

#### Module boundaries
The Gradle multi-module build is rooted at `settings.gradle.kts` and `build.gradle.kts`. `karl-core` owns platform-neutral contracts and orchestration; optional modules supply UI, learning, and persistence implementations:
- `karl-core/build.gradle.kts`
- `karl-kldl/build.gradle.kts`
- `karl-room/build.gradle.kts`

#### Public contract and domain model
The core API defines the extension boundary between a host app and KARL. Hosts provide a `DataSource` for relevant user events, a `DataStorage` for local persistence, and a `LearningEngine` for training/prediction. Shared models carry interaction metadata and serializable container state:
- `karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt`
- `karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt`
- `karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt`

#### Container orchestration
`KarlContainerImpl` is the per-user/per-scope control boundary. It coordinates event intake, instruction handling, learning-engine calls, predictions, and state persistence. This container model prevents learning context from being global to an application:
- `karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt`
- `karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt`

#### Learning and instruction stages
Incoming interaction data is interpreted under optional user/application rules, then used for incremental training. Predictions are requested from the engine and are based on locally retained learned state. The engine interface permits alternate ML implementations; the included JVM KLDL module supplies an MLP-backed engine:
- `karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt`
- `karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt`
- `karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt`

#### Persistence boundary
Storage is abstract in core, with a Room-backed implementation in `karl-room`. Room entities represent interaction records and container state; JVM factory/storage code connects that schema to the core `DataStorage` contract. Data is intended to remain on device; no cloud or network service is represented in this repository:
- `karl-room/src/commonMain/kotlin/com/karl/room/KarlDao.kt`
- `karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt`
- `karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt`

#### Presentation and reference integration
`karl-compose-ui` provides Compose Multiplatform UI around a KARL container, including learning-progress presentation, without becoming part of core orchestration. The desktop example wires concrete storage and learning components into a local app and includes a local SQLite database artifact:
- `karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt`
- `karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt`
- `karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt`

#### Runtime and delivery
Primary runtimes are Kotlin Multiplatform common code and JVM implementations; `karl-room` also declares Android support via its manifest. GitHub Actions builds, releases, and deploys Dokka documentation; the documented docs site is Netlify-hosted, while learning/storage execution stays local:
- `.github/workflows/build.yml`
- `.github/workflows/release.yml`
- `.github/workflows/deploy_dokka.yml`

Main entry points: [`settings.gradle.kts`](https://github.com/theaniketraj/project-karl/blob/main/settings.gradle.kts) (Gradle multi-module build), [`karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt`](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt) (Karl container), [`karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt`](https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt) (Desktop example app), [`karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt`](https://github.com/theaniketraj/project-karl/blob/main/karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt) (Room data storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Kotlin Multiplatform Core"]
  node_api["Karl API<br/>public API<br/>[KarlAPI.kt]"]
  node_contracts["Host extension contracts<br/>interfaces"]
  node_models["Interaction models<br/>domain models<br/>[DataModels.kt]"]
  node_storage_contract["Storage state contract<br/>persistence contract<br/>[DataStorage.kt]"]
  node_container["Karl container<br/>orchestrator"]
  node_instructions["Instruction parser<br/>rule processing"]
  node_learning_contract["Learning engine contract<br/>ML interface<br/>[LearningEngine.kt]"]
end

subgraph group_extensions["Optional Implementations"]
  node_kldl["KLDL MLP engine<br/>JVM learning engine"]
  node_room_schema[("Room schema &amp; DAO<br/>local database schema")]
  node_room_storage["Room data storage<br/>JVM persistence adapter<br/>[RoomDataStorage.kt]"]
  node_ui["Compose container UI<br/>multiplatform UI<br/>[KarlContainerUI.kt]"]
end

subgraph group_integration["Desktop Integration &amp; Delivery"]
  node_desktop_main(("Desktop entry point<br/>JVM application entry<br/>[Main.kt]"))
  node_desktop_app["Desktop example app<br/>reference application"]
  node_example_storage["Example local storage<br/>storage setup<br/>[RealDataStorage.kt]"]
  node_build_ci["Build workflow<br/>GitHub Actions<br/>[build.yml]"]
  node_release_ci["Release workflow<br/>GitHub Actions<br/>[release.yml]"]
  node_docs_ci["Dokka deployment<br/>GitHub Actions<br/>[deploy_dokka.yml]"]
end

node_build{{"Gradle multi-module build"}}

node_build -->|"includes"| node_api
node_build -->|"includes"| node_kldl
node_build -->|"includes"| node_room_storage
node_build -->|"includes"| node_ui
node_api -->|"creates and operates"| node_container
node_contracts -->|"implemented by host dependencies"| node_container
node_models -->|"carries events and state"| node_container
node_storage_contract -->|"supports persistence contract"| node_contracts
node_container -->|"interprets events with"| node_instructions
node_container -->|"trains and predicts through"| node_learning_contract
node_container -->|"persists through"| node_contracts
node_kldl -->|"implements"| node_learning_contract
node_room_storage -->|"implements DataStorage"| node_contracts
node_room_storage -->|"reads and writes"| node_room_schema
node_ui -->|"presents"| node_container
node_desktop_main -->|"starts"| node_desktop_app
node_desktop_app -->|"uses"| node_api
node_desktop_app -->|"wires"| node_kldl
node_desktop_app -->|"configures"| node_example_storage
node_example_storage -->|"uses"| node_room_storage
node_build_ci -->|"builds"| node_build
node_release_ci -->|"releases"| node_build
node_docs_ci -->|"generates documentation from"| node_build

click node_build "https://github.com/theaniketraj/project-karl/blob/main/settings.gradle.kts"
click node_api "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt"
click node_contracts "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt"
click node_models "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt"
click node_storage_contract "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt"
click node_container "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt"
click node_instructions "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt"
click node_learning_contract "https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt"
click node_kldl "https://github.com/theaniketraj/project-karl/blob/main/karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt"
click node_room_schema "https://github.com/theaniketraj/project-karl/blob/main/karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt"
click node_room_storage "https://github.com/theaniketraj/project-karl/blob/main/karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt"
click node_ui "https://github.com/theaniketraj/project-karl/blob/main/karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt"
click node_desktop_main "https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/jvmMain/kotlin/Main.kt"
click node_desktop_app "https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt"
click node_example_storage "https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt"
click node_build_ci "https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/build.yml"
click node_release_ci "https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/release.yml"
click node_docs_ci "https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/deploy_dokka.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_contracts,node_models,node_storage_contract,node_container,node_instructions,node_learning_contract toneBlue
class node_kldl,node_room_schema,node_room_storage,node_ui toneAmber
class node_desktop_main,node_desktop_app,node_example_storage,node_build_ci,node_release_ci,node_docs_ci toneMint
class node_build toneNeutral
```

## Components

### Kotlin Multiplatform Core

Platform-neutral API, models, and container orchestration.

- [Karl API](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt): public API · Host entry point for creating and operating containers. · `karl-core/src/commonMain/kotlin/com/karl/core/api/KarlAPI.kt`
- [Host extension contracts](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt): interfaces · DataSource, DataStorage, and LearningEngine integration boundary. · `karl-core/src/commonMain/kotlin/com/karl/core/api/KarlCoreInterfaces.kt`
- [Interaction models](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt): domain models · Shared interaction metadata and container state. · `karl-core/src/commonMain/kotlin/com/karl/core/models/DataModels.kt`
- [Storage state contract](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt): persistence contract · Serializable storage-facing container state. · `karl-core/src/commonMain/kotlin/com/karl/core/models/DataStorage.kt`
- [Karl container](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt): orchestrator · Isolates learning context per user or scope. · `karl-core/src/commonMain/kotlin/com/karl/core/container/KarlContainerImpl.kt`
- [Instruction parser](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt): rule processing · Interprets optional user and application rules. · `karl-core/src/commonMain/kotlin/com/karl/core/instructions/InstructionParser.kt`
- [Learning engine contract](https://github.com/theaniketraj/project-karl/blob/main/karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt): ML interface · Supports interchangeable incremental training and prediction engines. · `karl-core/src/commonMain/kotlin/com/karl/core/learning/LearningEngine.kt`

### Optional Implementations

Learning, persistence, and UI modules.

- [KLDL MLP engine](https://github.com/theaniketraj/project-karl/blob/main/karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt): JVM learning engine · Included MLP-backed LearningEngine implementation. · `karl-kldl/src/jvmMain/kotlin/com/karl/kldl/KLDLLearningEngine.kt`
- [Room schema & DAO](https://github.com/theaniketraj/project-karl/blob/main/karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt): local database schema · Persists interaction records and container state. · `karl-room/src/commonMain/kotlin/com/karl/room/KarlRoomDatabase.kt`
- [Room data storage](https://github.com/theaniketraj/project-karl/blob/main/karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt): JVM persistence adapter · Connects Room persistence to the core storage contract. · `karl-room/src/jvmMain/kotlin/com/karl/room/RoomDataStorage.kt`
- [Compose container UI](https://github.com/theaniketraj/project-karl/blob/main/karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt): multiplatform UI · Presents a container and learning progress outside core orchestration. · `karl-compose-ui/src/commonMain/kotlin/com/karl/ui/KarlContainerUI.kt`

### Desktop Integration & Delivery

Reference JVM application and automation.

- [Desktop entry point](https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/jvmMain/kotlin/Main.kt): JVM application entry · Starts the runnable desktop reference integration. · `karl-example-desktop/src/jvmMain/kotlin/Main.kt`
- [Desktop example app](https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt): reference application · Wires KARL into a local desktop app. · `karl-example-desktop/src/main/kotlin/com/karl/example/DesktopExampleApp.kt`
- [Example local storage](https://github.com/theaniketraj/project-karl/blob/main/karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt): storage setup · Provides the example application's local persistence setup. · `karl-example-desktop/src/main/kotlin/com/karl/example/RealDataStorage.kt`
- [Build workflow](https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/build.yml): GitHub Actions · Build automation for the repository. · `.github/workflows/build.yml`
- [Release workflow](https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/release.yml): GitHub Actions · Release automation. · `.github/workflows/release.yml`
- [Dokka deployment](https://github.com/theaniketraj/project-karl/blob/main/.github/workflows/deploy_dokka.yml): GitHub Actions · Builds and deploys documentation. · `.github/workflows/deploy_dokka.yml`

### Other components

- [Gradle multi-module build](https://github.com/theaniketraj/project-karl/blob/main/settings.gradle.kts): build · Defines the KARL module topology. · `settings.gradle.kts`

## Connections

- Gradle multi-module build → Karl API: includes
- Gradle multi-module build → KLDL MLP engine: includes
- Gradle multi-module build → Room data storage: includes
- Gradle multi-module build → Compose container UI: includes
- Karl API → Karl container: creates and operates
- Host extension contracts → Karl container: implemented by host dependencies
- Interaction models → Karl container: carries events and state
- Storage state contract → Host extension contracts: supports persistence contract
- Karl container → Instruction parser: interprets events with
- Karl container → Learning engine contract: trains and predicts through
- Karl container → Host extension contracts: persists through
- KLDL MLP engine → Learning engine contract: implements
- Room data storage → Host extension contracts: implements DataStorage
- Room data storage → Room schema & DAO: reads and writes
- Compose container UI → Karl container: presents
- Desktop entry point → Desktop example app: starts
- Desktop example app → Karl API: uses
- Desktop example app → KLDL MLP engine: wires
- Desktop example app → Example local storage: configures
- Example local storage → Room data storage: uses
- Build workflow → Gradle multi-module build: builds
- Release workflow → Gradle multi-module build: releases
- Dokka deployment → Gradle multi-module build: generates documentation from