# khiproteam/khipro-library architecture

> Architecture diagram of the GitHub repository khiproteam/khipro-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khiproteam/khipro-library
- Repository: https://github.com/khiproteam/khipro-library

## Overview

1. **Overall shape**
   - This is a cross-platform **C++ core library** for the Khipro Bangla input method, with thin platform bindings for **Android** and **WebAssembly/JavaScript**.
   - The architecture is centered on one reusable engine that is built into native libraries for multiple targets.

2. **Core domain boundary**
   - `core/` is the main subsystem and owns the actual input-method logic.
   - It exposes a **public C API** (`core/include/khipro/khipro.h`) so non-C++ consumers can integrate without depending on internal C++ types.

3. **Engine pipeline**
   - Inside `core/src/`, the implementation is split into:
     - `engine.*` for runtime state and composition behavior,
     - `spec.*` and `sexpr.*` for parsing/interpreting the bundled m17n layout specifications,
     - `convert.*` for converting between internal representations and output text.
   - The main data flow is: **key input → engine state update → spec-driven composition → produced Bangla output**.

4. **Bundled layout data**
   - The input-method behavior is not hardcoded; it comes from embedded `.mim` files in `resources/`.
   - There are two shipped variants:
     - `bn-khipro.mim` for desktop keyboards,
     - `bn-khipro-touchscreen.mim` for touch devices.
   - `resources/.lock` and the `scripts/resources/*` tooling track provenance and syncing of those upstream layout files.

5. **Build-time resource embedding**
   - The repository treats the m17n specs as build inputs that are embedded into the library at compile time.
   - This means the runtime library has no external dependency on the `.mim` files; they are packaged into the native artifacts.

6. **Android binding layer**
   - `bindings/android/` contains an Android Gradle project that wraps the native core through **JNI**.
   - `jni_bridge.cpp` is the native bridge, while the Kotlin library under `bindings/android/library/` provides the public Android API.
   - The Kotlin classes (`KhiproEngine`, `KhiproIme`, `KhiproNative`, etc.) separate engine control, IME integration, and result/variant modeling.

7. **Android usage model**
   - The Android binding is designed for both app integration and IME-style usage, with sample entry points in `bindings/android/samples/`.
   - The data flow is: **Kotlin API → JNI bridge → native C API/core engine → result back to Kotlin**.

8. **WebAssembly binding layer**
   - `bindings/web/` packages the same core engine for browser or JS runtimes via **Wasm**.
   - `wasm_shim.cpp` adapts the native core into a form that can be exported to TypeScript (`src/index.ts`).
   - This is another thin boundary around the same shared engine, not a separate implementation.

9. **Portability and packaging**
   - The repository is designed for multiple native targets: Linux, Windows, macOS, Android, and Wasm.
   - `cmake/` and `container/` hold the platform toolchains and Docker-based build environments used to produce the different artifacts.
   - The build is orchestrated through `Makefile`, `CMakeLists.txt`, and target scripts in `scripts/targets/`.

10. **Tests and conformance**
   - `tests/` contains conformance tests driven by CSV testcases in `resources/`.
   - These tests validate the engine’s composition behavior against expected Khipro outputs, so they sit at the boundary between core logic and the bundled layout specs.

11. **Versioning and release flow**
   - `khipro.meta` is the single source of truth for package metadata and versioning.
   - The GitHub Actions release workflow and `scripts/` automation use it to sync upstream layout versions, rebuild all targets, run tests, and publish tagged releases.

12. **Architecture summary for diagramming**
   - The cleanest diagram is: **upstream m17n layout specs → embedded resources → C++ core engine/API → platform bindings (Android JNI, WebAssembly) → target-specific packaged artifacts**.
   - Around that sit the build/release systems, which do not change runtime behavior but control resource ingestion, compilation, testing, and distribution.

Main entry points: [`scripts/resources/embed.py`](https://github.com/khiproteam/khipro-library/blob/main/scripts/resources/embed.py) (Embed tool), [`core/src/engine.cpp`](https://github.com/khiproteam/khipro-library/blob/main/core/src/engine.cpp) (Engine), [`core/include/khipro/khipro.h`](https://github.com/khiproteam/khipro-library/blob/main/core/include/khipro/khipro.h) (C API), [`bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproEngine.kt`](https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproEngine.kt) (Kotlin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_core_api["C API<br/>public interface<br/>[khipro.h]"]
  node_core_engine["Engine<br/>runtime state<br/>[engine.cpp]"]
  node_core_spec["Spec parser<br/>layout interpreter<br/>[spec.cpp]"]
  node_core_sexpr["S-expr<br/>syntax parser<br/>[sexpr.cpp]"]
  node_core_convert["Converter<br/>text transform<br/>[convert.cpp]"]
  node_core_api_impl["API impl<br/>C bridge<br/>[api.cpp]"]
end

subgraph group_resources["Embedded layouts"]
  node_layout_specs["MIM layouts<br/>embedded resource<br/>[bn-khipro.mim]"]
  node_touch_layout["Touch layout<br/>embedded resource"]
  node_resource_meta["Resource lock<br/>provenance metadata<br/>[.lock]"]
  node_resource_tests["CSV cases<br/>test fixture"]
end

subgraph group_bindings["Platform bindings"]
  node_android_kotlin["Kotlin API<br/>Android wrapper<br/>[KhiproEngine.kt]"]
  node_android_ime["IME layer<br/>Android service<br/>[KhiproIme.kt]"]
  node_android_native["JNI bridge<br/>native binding<br/>[jni_bridge.cpp]"]
  node_android_model["Result model<br/>data model<br/>[KhiproResult.kt]"]
  node_web_ts["TS API<br/>Web wrapper<br/>[index.ts]"]
  node_web_shim["Wasm shim<br/>native binding<br/>[wasm_shim.cpp]"]
end

subgraph group_build["Build & release"]
  node_build_cmake["CMake<br/>build system<br/>[CMakeLists.txt]"]
  node_build_scripts["Target scripts<br/>automation<br/>[common.sh]"]
  node_resource_embed["Embed tool<br/>resource pipeline<br/>[embed.py]"]
  node_release_flow["Release workflow<br/>ci pipeline<br/>[release.yml]"]
end

subgraph group_tests["Tests"]
  node_conformance["Conformance<br/>test runner<br/>[main.cpp]"]
end

node_layout_specs -->|"embed"| node_resource_embed
node_touch_layout -->|"embed"| node_resource_embed
node_resource_meta -->|"sync"| node_build_scripts
node_resource_embed -->|"feeds"| node_core_spec
node_core_sexpr -->|"parses"| node_core_spec
node_core_spec -->|"drives"| node_core_engine
node_core_engine -->|"outputs"| node_core_convert
node_core_engine -->|"used by"| node_core_api_impl
node_core_api_impl -->|"exports"| node_core_api
node_core_api -->|"calls"| node_android_native
node_android_native -->|"bridges"| node_android_kotlin
node_android_kotlin -->|"extends"| node_android_ime
node_android_kotlin -->|"returns"| node_android_model
node_core_api -->|"exports"| node_web_shim
node_web_shim -->|"binds"| node_web_ts
node_resource_embed -->|"integrates"| node_build_cmake
node_build_cmake -->|"orchestrates"| node_build_scripts
node_build_scripts -->|"triggers"| node_release_flow
node_resource_tests -->|"drives"| node_conformance
node_core_engine -->|"validated by"| node_conformance
node_release_flow -->|"packages"| node_resource_embed
node_release_flow -->|"runs"| node_conformance

click node_core_api "https://github.com/khiproteam/khipro-library/blob/main/core/include/khipro/khipro.h"
click node_core_engine "https://github.com/khiproteam/khipro-library/blob/main/core/src/engine.cpp"
click node_core_spec "https://github.com/khiproteam/khipro-library/blob/main/core/src/spec.cpp"
click node_core_sexpr "https://github.com/khiproteam/khipro-library/blob/main/core/src/sexpr.cpp"
click node_core_convert "https://github.com/khiproteam/khipro-library/blob/main/core/src/convert.cpp"
click node_core_api_impl "https://github.com/khiproteam/khipro-library/blob/main/core/src/api.cpp"
click node_layout_specs "https://github.com/khiproteam/khipro-library/blob/main/resources/bn-khipro.mim"
click node_touch_layout "https://github.com/khiproteam/khipro-library/blob/main/resources/bn-khipro-touchscreen.mim"
click node_resource_meta "https://github.com/khiproteam/khipro-library/blob/main/resources/.lock"
click node_resource_tests "https://github.com/khiproteam/khipro-library/blob/main/resources/khipro-testcases.csv"
click node_android_kotlin "https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproEngine.kt"
click node_android_ime "https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproIme.kt"
click node_android_native "https://github.com/khiproteam/khipro-library/blob/main/bindings/android/jni_bridge.cpp"
click node_android_model "https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproResult.kt"
click node_web_ts "https://github.com/khiproteam/khipro-library/blob/main/bindings/web/src/index.ts"
click node_web_shim "https://github.com/khiproteam/khipro-library/blob/main/bindings/web/wasm_shim.cpp"
click node_build_cmake "https://github.com/khiproteam/khipro-library/blob/main/CMakeLists.txt"
click node_build_scripts "https://github.com/khiproteam/khipro-library/blob/main/scripts/targets/common.sh"
click node_resource_embed "https://github.com/khiproteam/khipro-library/blob/main/scripts/resources/embed.py"
click node_release_flow "https://github.com/khiproteam/khipro-library/blob/main/.github/workflows/release.yml"
click node_conformance "https://github.com/khiproteam/khipro-library/blob/main/tests/main.cpp"

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_core_api,node_core_engine,node_core_spec,node_core_sexpr,node_core_convert,node_core_api_impl toneBlue
class node_layout_specs,node_touch_layout,node_resource_meta,node_resource_tests toneAmber
class node_android_kotlin,node_android_ime,node_android_native,node_android_model,node_web_ts,node_web_shim toneMint
class node_build_cmake,node_build_scripts,node_resource_embed,node_release_flow toneRose
class node_conformance toneIndigo
```

## Components

### Core library

Reusable C++ input-method engine and public API.

- [C API](https://github.com/khiproteam/khipro-library/blob/main/core/include/khipro/khipro.h): public interface · Stable C-facing entrypoint for non-C++ consumers. · `core/include/khipro/khipro.h`
- [Engine](https://github.com/khiproteam/khipro-library/blob/main/core/src/engine.cpp): runtime state · Maintains composition state and processes key input. · `core/src/engine.cpp`
- [Spec parser](https://github.com/khiproteam/khipro-library/blob/main/core/src/spec.cpp): layout interpreter · Parses and interprets embedded m17n specification data. · `core/src/spec.cpp`
- [S-expr](https://github.com/khiproteam/khipro-library/blob/main/core/src/sexpr.cpp): syntax parser · Supports reading spec expressions used by the layout files. · `core/src/sexpr.cpp`
- [Converter](https://github.com/khiproteam/khipro-library/blob/main/core/src/convert.cpp): text transform · Converts internal composition results to output text. · `core/src/convert.cpp`
- [API impl](https://github.com/khiproteam/khipro-library/blob/main/core/src/api.cpp): C bridge · Implements the public C API on top of the C++ engine. · `core/src/api.cpp`

### Embedded layouts

Bundled m17n specs and test fixtures consumed by the core and tests.

- [MIM layouts](https://github.com/khiproteam/khipro-library/blob/main/resources/bn-khipro.mim): embedded resource · Bundled Bangla keyboard and touchscreen layout specs. · `resources/bn-khipro.mim`
- [Touch layout](https://github.com/khiproteam/khipro-library/blob/main/resources/bn-khipro-touchscreen.mim): embedded resource · Touch-oriented variant of the bundled layout. · `resources/bn-khipro-touchscreen.mim`
- [Resource lock](https://github.com/khiproteam/khipro-library/blob/main/resources/.lock): provenance metadata · Tracks upstream layout sync state and embedding provenance. · `resources/.lock`
- [CSV cases](https://github.com/khiproteam/khipro-library/blob/main/resources/khipro-testcases.csv): test fixture · Expected input/output cases for conformance testing. · `resources/khipro-testcases.csv`

### Platform bindings

Thin adapters that expose the same engine to Android and WebAssembly.

- [Kotlin API](https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproEngine.kt): Android wrapper · Public Android-facing API for engine control and IME integration. · `bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproEngine.kt`
- [IME layer](https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproIme.kt): Android service · IME-style integration and higher-level input workflow on Android. · `bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproIme.kt`
- [JNI bridge](https://github.com/khiproteam/khipro-library/blob/main/bindings/android/jni_bridge.cpp): native binding · Bridges Kotlin calls to the native C API. · `bindings/android/jni_bridge.cpp`
- [Result model](https://github.com/khiproteam/khipro-library/blob/main/bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproResult.kt): data model · Represents results and variants returned to Android callers. · `bindings/android/library/src/main/kotlin/com/khiproteam/khipro/KhiproResult.kt`
- [TS API](https://github.com/khiproteam/khipro-library/blob/main/bindings/web/src/index.ts): Web wrapper · TypeScript-facing API over the WebAssembly build. · `bindings/web/src/index.ts`
- [Wasm shim](https://github.com/khiproteam/khipro-library/blob/main/bindings/web/wasm_shim.cpp): native binding · Adapts the core engine for export to JavaScript/Wasm runtimes. · `bindings/web/wasm_shim.cpp`

### Build & release

Tooling for embedding resources, cross-compiling, packaging, and publishing.

- [CMake](https://github.com/khiproteam/khipro-library/blob/main/CMakeLists.txt): build system · Primary native build configuration for core and bindings. · `CMakeLists.txt`
- [Target scripts](https://github.com/khiproteam/khipro-library/blob/main/scripts/targets/common.sh): automation · Platform build and target orchestration scripts. · `scripts/targets/common.sh`
- [Embed tool](https://github.com/khiproteam/khipro-library/blob/main/scripts/resources/embed.py): resource pipeline · Build-time tooling that packs layout specs into native artifacts. · `scripts/resources/embed.py`
- [Release workflow](https://github.com/khiproteam/khipro-library/blob/main/.github/workflows/release.yml): ci pipeline · GitHub Actions workflow for sync, build, test, and release. · `.github/workflows/release.yml`

### Tests

Conformance checks for engine behavior against bundled cases.

- [Conformance](https://github.com/khiproteam/khipro-library/blob/main/tests/main.cpp): test runner · Runs engine behavior checks against bundled testcases. · `tests/main.cpp`

## Connections

- MIM layouts → Embed tool: embed · Bundles desktop layout data into build artifacts.
- Touch layout → Embed tool: embed · Bundles touchscreen layout data into build artifacts.
- Resource lock → Target scripts: sync · Tracks upstream provenance used by resource automation.
- Embed tool → Spec parser: feeds · Provides embedded spec data to the core parser.
- S-expr → Spec parser: parses · Supports interpreting spec expressions.
- Spec parser → Engine: drives · Defines the composition rules used by runtime state.
- Engine → Converter: outputs · Hands composition results to text conversion.
- Engine → API impl: used by · Core runtime is exposed through the C API implementation.
- API impl → C API: exports · Publishes the stable public interface.
- C API → JNI bridge: calls · Android JNI invokes the native C API.
- JNI bridge → Kotlin API: bridges · Provides native backing for the Kotlin wrapper.
- Kotlin API → IME layer: extends · IME integration builds on the engine-facing API.
- Kotlin API → Result model: returns · Result and variant types model Kotlin-facing outputs.
- C API → Wasm shim: exports · Wasm build exposes the same C API through a shim.
- Wasm shim → TS API: binds · TypeScript API wraps the Wasm exports.
- Embed tool → CMake: integrates · Embedding happens during native build configuration.
- CMake → Target scripts: orchestrates · Target scripts drive per-platform builds.
- Target scripts → Release workflow: triggers · Release automation reuses the build scripts.
- CSV cases → Conformance: drives · CSV fixtures define expected engine behavior.
- Engine → Conformance: validated by · Conformance tests exercise the runtime engine.
- Release workflow → Embed tool: packages · Release workflow rebuilds artifacts with embedded resources.
- Release workflow → Conformance: runs · Release workflow validates behavior before publishing.