# kashif-e/camerak architecture

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

- Interactive diagram: https://gitdiagram.com/kashif-e/camerak
- Repository: https://github.com/kashif-e/camerak

## Overview

1. **Repository shape**
   This is a Kotlin Multiplatform/Compose Multiplatform monorepo centered on the `cameraK` library. The root project builds the core camera library plus several optional plugin modules, a sample app, documentation, and publishing/tooling support.

2. **Core library boundary: `cameraK`**
   `cameraK` is the main product module. Its public API lives in `src/commonMain` and is split into:
   - state management (`CameraKState`, `CameraKStateHolder`)
   - camera control (`CameraController`)
   - Compose-facing UI primitives (`CameraPreviewView`, `rememberCameraKState`, `CameraKScreen`)
   - shared configuration and result types (`AspectRatio`, `FlashMode`, `ImageCaptureResult`, `VideoConfiguration`, `CameraKEvent`, etc.)
   This common layer defines the contract that all platforms and plugins must obey.

3. **Reactive runtime flow**
   The central runtime model is state-driven:
   - UI calls `rememberCameraKState(...)`
   - this creates a `CameraKStateHolder`
   - the holder exposes `StateFlow<CameraKState>`, `StateFlow<CameraUIState>`, and `SharedFlow<CameraKEvent>`
   - when the camera reaches `Ready`, the UI receives a platform-specific `CameraController`
   - plugins subscribe to the same holder and activate when the camera becomes ready
   This is the main data flow to diagram: UI/configuration → state holder → platform controller → events/results back to UI/plugins.

4. **Platform-specific camera backends**
   `cameraK` uses `expect/actual` boundaries for the camera controller, preview UI, permissions, and state helpers. Each platform has its own implementation under:
   - `androidMain`
   - `appleMain`
   - `desktopMain`
   The backend technologies materially differ:
   - Android: CameraX
   - iOS: AVFoundation
   - Desktop: JavaCV
   These implementations are the hardware-adapter layer beneath the shared API.

5. **Android-specific implementation**
   Android code contains builder/controller classes, Compose preview integration, permission handling, and utility code. The Android manifest lives in the module, so Android has explicit runtime permission and camera lifecycle concerns that are isolated from common code.

6. **Apple/iOS-specific implementation**
   The Apple source set includes controller and preview implementations, permission provisioning, video recording delegation, burst capture management, and Objective-C interop utilities. This indicates iOS is not just a thin wrapper; it has its own capture/session management and platform bridging.

7. **Desktop-specific implementation**
   Desktop has a more imperative capture pipeline with classes like `CameraGrabber`, `FrameConverter`, `ImageCaptureManager`, and `ImagePanel`. That suggests the desktop backend handles frame acquisition and rendering differently from mobile, while still presenting the same common controller/state API.

8. **Plugin architecture**
   The library is designed around attachable plugins via `CameraKPlugin` and `CameraKStateHolder.attachPlugin(...)`. Plugins are not separate apps; they are runtime extensions that listen to camera readiness, camera events, and frame/capture data. Their lifecycle is tied to the camera state holder: `onAttach` / `onDetach`.

9. **Optional plugin modules**
   Several standalone modules extend the core camera pipeline:
   - `imageSaverPlugin`: persists captures to files/storage
   - `qrScannerPlugin`: scans camera frames for QR codes
   - `ocrPlugin`: performs text recognition; includes desktop trained data
   - `videoRecorderPlugin`: records video from the camera session
   - `analyzerPlugin`: likely a lower-level frame analysis extension
   These modules depend on the core API, not the sample app, and plug into the shared event/state flow.

10. **Capture and recording data paths**
    The core library exposes two capture paths:
    - still capture via `takePictureToFile()` or legacy `takePicture()`
    - video recording via controller/state-holder methods and `VideoCaptureResult`
    Plugins can intercept or react to these flows: image saver consumes capture results, QR/OCR consume frame streams, and the video recorder emits its own recording events.

11. **Sample application**
    `Sample` is a Compose Multiplatform app demonstrating library usage across Android, desktop, iOS, and JS targets. It contains shared UI/theme code, platform entry points, and resource assets. This module is for validation and demonstration rather than being part of the library runtime.

12. **Documentation, release, and publishing**
    The repo includes `docs/` with API and guides, `mkdocs.yml` for site generation, and GitHub Actions for documentation and Maven Central publishing. `convention-plugins` and Gradle Kotlin DSL scripts indicate the build is standardized around shared publication conventions and multiplatform module setup.

Main entry points: [`cameraK/src/commonMain/kotlin/com/kashif/cameraK/state`](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/state) (State holder), [`cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose`](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose) (Compose API), [`cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller`](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller) (Controller API), [`cameraK/src/commonMain/kotlin/com/kashif/cameraK`](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK) (Shared API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_camera_api["Shared API<br/>kmp commonMain"]
  node_camera_state(("State holder<br/>runtime flow"))
  node_camera_ui["Compose API<br/>ui facade"]
  node_camera_controller["Controller API<br/>control boundary"]
  node_camera_android["Android backend<br/>CameraX actual"]
  node_camera_apple["Apple backend<br/>AVFoundation actual"]
  node_camera_desktop["Desktop backend<br/>JavaCV actual"]
  node_plugin_api["Plugin API<br/>extension contract"]
end

subgraph group_plugins["Plugins"]
  node_image_saver["Image saver<br/>capture plugin"]
  node_qr_scanner["QR scanner<br/>frame plugin"]
  node_ocr_plugin["OCR plugin<br/>frame plugin"]
  node_video_recorder["Video recorder<br/>recording plugin"]
  node_analyzer_plugin["Analyzer plugin<br/>frame plugin"]
end

subgraph group_sample["Sample app"]
  node_sample_shared["Sample UI<br/>compose demo"]
  node_sample_platforms["Entry points<br/>platform launchers"]
end

subgraph group_tooling["Docs and tooling"]
  node_docs_site["Docs site<br/>mkdocs content"]
  node_build_conventions["Build conventions<br/>gradle support"]
  node_root_build["Repo build<br/>gradle root"]
end

node_camera_ui -->|"creates state"| node_camera_state
node_camera_state -->|"exposes controller"| node_camera_controller
node_camera_state -->|"attaches plugins"| node_plugin_api
node_camera_api -->|"defines state"| node_camera_state
node_camera_api -->|"defines contract"| node_camera_controller
node_camera_api -->|"exposes compose"| node_camera_ui
node_camera_controller -->|"actualized by"| node_camera_android
node_camera_controller -->|"actualized by"| node_camera_apple
node_camera_controller -->|"actualized by"| node_camera_desktop
node_camera_ui -->|"renders on"| node_camera_android
node_camera_ui -->|"renders on"| node_camera_apple
node_camera_ui -->|"renders on"| node_camera_desktop
node_image_saver -->|"listens to capture"| node_camera_state
node_qr_scanner -->|"listens to frames"| node_camera_state
node_ocr_plugin -->|"listens to frames"| node_camera_state
node_video_recorder -->|"records from state"| node_camera_state
node_analyzer_plugin -->|"analyzes stream"| node_camera_state
node_sample_shared -->|"uses API"| node_camera_ui
node_sample_platforms -->|"launches app"| node_sample_shared
node_docs_site -->|"documents"| node_camera_api
node_build_conventions -->|"supports build"| node_root_build

click node_camera_api "https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK"
click node_camera_state "https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/state"
click node_camera_ui "https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose"
click node_camera_controller "https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller"
click node_camera_android "https://github.com/kashif-e/camerak/tree/main/cameraK/src/androidMain/kotlin/com/kashif/cameraK"
click node_camera_apple "https://github.com/kashif-e/camerak/tree/main/cameraK/src/appleMain/kotlin/com/kashif/cameraK"
click node_camera_desktop "https://github.com/kashif-e/camerak/tree/main/cameraK/src/desktopMain/kotlin/com/kashif/cameraK"
click node_plugin_api "https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/plugins"
click node_image_saver "https://github.com/kashif-e/camerak/tree/main/ImageSaverPlugin/src/commonMain/kotlin/com/kashif/imagesaverplugin"
click node_qr_scanner "https://github.com/kashif-e/camerak/tree/main/qrScannerPlugin/src/commonMain/kotlin/com/kashif/qrscannerplugin"
click node_ocr_plugin "https://github.com/kashif-e/camerak/tree/main/ocrPlugin/src/commonMain/kotlin/com/kashif/ocrPlugin"
click node_video_recorder "https://github.com/kashif-e/camerak/tree/main/videoRecorderPlugin/src/commonMain/kotlin/com/kashif/videorecorderplugin"
click node_analyzer_plugin "https://github.com/kashif-e/camerak/blob/main/analyzerPlugin/src/commonMain/kotlin/com.kashif.analyzerPlugin"
click node_sample_shared "https://github.com/kashif-e/camerak/tree/main/Sample/src/commonMain/kotlin/org/company/app"
click node_sample_platforms "https://github.com/kashif-e/camerak/tree/main/Sample/src"
click node_docs_site "https://github.com/kashif-e/camerak/tree/main/docs"
click node_build_conventions "https://github.com/kashif-e/camerak/tree/main/convention-plugins"

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_camera_api,node_camera_state,node_camera_ui,node_camera_controller,node_camera_android,node_camera_apple,node_camera_desktop,node_plugin_api toneBlue
class node_image_saver,node_qr_scanner,node_ocr_plugin,node_video_recorder,node_analyzer_plugin toneAmber
class node_sample_shared,node_sample_platforms toneMint
class node_docs_site,node_build_conventions,node_root_build toneRose
```

## Components

### Core library

Shared camera API, state machine, and platform backends.

- [Shared API](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK): kmp commonMain · Public camera contract, enums, result types, permissions, and plugin hooks. · `cameraK/src/commonMain/kotlin/com/kashif/cameraK`
- [State holder](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/state): runtime flow · Owns CameraKState, exposes state flows, shared events, and plugin attachment lifecycle. · `cameraK/src/commonMain/kotlin/com/kashif/cameraK/state`
- [Compose API](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose): ui facade · rememberCameraKState, CameraPreviewView, and CameraKScreen for UI integration. · `cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose`
- [Controller API](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller): control boundary · Platform-neutral controller contract used to configure capture, preview, and recording. · `cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller`
- [Android backend](https://github.com/kashif-e/camerak/tree/main/cameraK/src/androidMain/kotlin/com/kashif/cameraK): CameraX actual · Android controller, preview, permissions, and builder implementation. · `cameraK/src/androidMain/kotlin/com/kashif/cameraK`
- [Apple backend](https://github.com/kashif-e/camerak/tree/main/cameraK/src/appleMain/kotlin/com/kashif/cameraK): AVFoundation actual · iOS controller, preview, permissions, burst capture, and recording delegation. · `cameraK/src/appleMain/kotlin/com/kashif/cameraK`
- [Desktop backend](https://github.com/kashif-e/camerak/tree/main/cameraK/src/desktopMain/kotlin/com/kashif/cameraK): JavaCV actual · Desktop capture pipeline for frame grabbing, conversion, rendering, and capture management. · `cameraK/src/desktopMain/kotlin/com/kashif/cameraK`
- [Plugin API](https://github.com/kashif-e/camerak/tree/main/cameraK/src/commonMain/kotlin/com/kashif/cameraK/plugins): extension contract · CameraPlugin interface used to attach runtime extensions to the state holder. · `cameraK/src/commonMain/kotlin/com/kashif/cameraK/plugins`

### Plugins

Attachable runtime extensions that consume camera state and frames.

- [Image saver](https://github.com/kashif-e/camerak/tree/main/ImageSaverPlugin/src/commonMain/kotlin/com/kashif/imagesaverplugin): capture plugin · Persists still capture outputs to files or storage targets. · `ImageSaverPlugin/src/commonMain/kotlin/com/kashif/imagesaverplugin`
- [QR scanner](https://github.com/kashif-e/camerak/tree/main/qrScannerPlugin/src/commonMain/kotlin/com/kashif/qrscannerplugin): frame plugin · Scans camera frames for QR codes across supported platforms. · `qrScannerPlugin/src/commonMain/kotlin/com/kashif/qrscannerplugin`
- [OCR plugin](https://github.com/kashif-e/camerak/tree/main/ocrPlugin/src/commonMain/kotlin/com/kashif/ocrPlugin): frame plugin · Performs text recognition, including desktop trained-data support. · `ocrPlugin/src/commonMain/kotlin/com/kashif/ocrPlugin`
- [Video recorder](https://github.com/kashif-e/camerak/tree/main/videoRecorderPlugin/src/commonMain/kotlin/com/kashif/videorecorderplugin): recording plugin · Adds video recording behavior on top of the shared camera session. · `videoRecorderPlugin/src/commonMain/kotlin/com/kashif/videorecorderplugin`
- [Analyzer plugin](https://github.com/kashif-e/camerak/blob/main/analyzerPlugin/src/commonMain/kotlin/com.kashif.analyzerPlugin): frame plugin · Lower-level frame analysis extension point for camera streams. · `analyzerPlugin/src/commonMain/kotlin/com.kashif.analyzerPlugin`

### Sample app

Multiplatform demo application and platform entry points.

- [Sample UI](https://github.com/kashif-e/camerak/tree/main/Sample/src/commonMain/kotlin/org/company/app): compose demo · Shared sample app UI, theme, utilities, and resources. · `Sample/src/commonMain/kotlin/org/company/app`
- [Entry points](https://github.com/kashif-e/camerak/tree/main/Sample/src): platform launchers · Android, desktop, iOS, and JS app entry points and theme wiring. · `Sample/src`

### Docs and tooling

Documentation, publishing conventions, and repo-wide build support.

- [Docs site](https://github.com/kashif-e/camerak/tree/main/docs): mkdocs content · Guides, API pages, examples, and site assets for users of the library. · `docs`
- [Build conventions](https://github.com/kashif-e/camerak/tree/main/convention-plugins): gradle support · Convention plugins and shared Gradle configuration for publication and multiplatform setup. · `convention-plugins`
- **Repo build**: gradle root · Root Gradle settings, version catalog, and shared build orchestration.

## Connections

- Compose API → State holder: creates state · UI entry points initialize and observe the shared state holder.
- State holder → Controller API: exposes controller · When ready, the state holder publishes the active controller to consumers.
- State holder → Plugin API: attaches plugins · Plugins register with the holder and follow onAttach/onDetach lifecycle.
- Shared API → State holder: defines state · Shared types define the camera state machine and events.
- Shared API → Controller API: defines contract · Common API defines the controller surface used by all platforms.
- Shared API → Compose API: exposes compose · Compose-facing helpers live in the common API layer.
- Controller API → Android backend: actualized by · Android provides the CameraX-backed controller implementation.
- Controller API → Apple backend: actualized by · Apple provides the AVFoundation-backed controller implementation.
- Controller API → Desktop backend: actualized by · Desktop provides the JavaCV-backed controller implementation.
- Compose API → Android backend: renders on · Android supplies the platform preview and permission flow.
- Compose API → Apple backend: renders on · Apple supplies the platform preview and permission flow.
- Compose API → Desktop backend: renders on · Desktop supplies the platform preview and permission flow.
- Image saver → State holder: listens to capture · Consumes capture results from the shared state/event flow.
- QR scanner → State holder: listens to frames · Consumes camera frames and readiness events.
- OCR plugin → State holder: listens to frames · Consumes camera frames for text recognition.
- Video recorder → State holder: records from state · Integrates with the active session and recording events.
- Analyzer plugin → State holder: analyzes stream · Hooks into the camera stream for analysis and processing.
- Sample UI → Compose API: uses API · The sample app consumes the shared Compose camera surface.
- Entry points → Sample UI: launches app · Platform entry points bootstrap the shared sample UI.
- Docs site → Shared API: documents · Docs describe the public API and usage patterns.
- Build conventions → Repo build: supports build · Convention plugins are applied through the repository build setup.
