# dessalines/thumb-key architecture

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

- Interactive diagram: https://gitdiagram.com/dessalines/thumb-key
- Repository: https://github.com/dessalines/thumb-key

## Overview

##### Project type and purpose
- This is an Android Input Method Editor (IME) app called “Thumb-Key.”
- It implements a smart, privacy-conscious keyboard using Jetpack Compose and the Android IME APIs.

##### High-level architectural layers
- Android Platform & IME Framework
- App boundary:
- IMEService (bridge to Android IME APIs)
- ComposeKeyboardView (Compose UI presentation)
- MainActivity & Settings Screens (Compose UI for configuration)
- Domain logic: keyboard layouts, swipe logic, modifications
- Data layer: Room database (AppDb) and YAML config assets
- External services: other IMEs (voice input), publishing pipelines (Fastlane, F-Droid, Play Store)

##### Main components
a. Android IME Framework (InputMethodManager)
b. IMEService.kt
c. ComposeKeyboardView.kt
d. Keyboard definitions package (com.dessalines.thumbkey.keyboards)
e. KeyboardModificationService & KeyboardLayout utils
f. UI components package (com.dessalines.thumbkey.ui)
g. Room Data layer (AppDb.kt)
h. Assets (YAML modifier files in app/src/main/assets)
i. Settings screens (SetupScreen, BehaviorScreen, etc.)
j. External voice IME services (FUTO Voice, Transcribro, Whisper IME)

##### Relationships and data flow
- At startup: IMEService registers with Android IME Framework → loads configuration from assets and Room DB via KeyboardModificationService → instantiates ComposeKeyboardView and Settings UI.
- User taps/swipes on ComposeKeyboardView → events dispatched to IMEService → domain logic (KeyboardLayout + AutoCapitalizers, Utils) computes output → IMEService.commitText() to Android.
- Settings changes in MainActivity → write/read to Room DB → triggers recomposition of UI and reloading of layouts.
- Voice input: IMEService triggers Android’s InputMethodManager.switchToNextInputMethod or external IME services.

##### Architectural patterns & principles
- Layered architecture: Presentation (Compose) → Domain (keyboard logic) → Data (Room + asset configs)
- Separation of concerns: IMEService as system boundary; Compose UIs isolated in ui/components; keyboard definitions isolated in keyboards package; config and persistence in data/util classes.
- Use of Jetpack Compose for declarative UI; Room for local persistence; Android IME API for text input.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External System
    AndroidIME["Android IME Framework<br/>(InputMethodManager)"]:::external

    %% App Boundary
    subgraph "App Boundary"
        subgraph "System Bridge"
            IMEService["IMEService"]:::system
        end

        subgraph "Presentation"
            ComposeKeyboardView["ComposeKeyboardView"]:::presentation
            MainActivity["MainActivity"]:::presentation
            subgraph "UI Components"
                CommonUI["Common UI Components"]:::presentation
                KeyboardUI["Keyboard UI Components"]:::presentation
                SettingsUI["Settings UI Components"]:::presentation
                SetupScreen["SetupScreen"]:::presentation
            end
        end

        subgraph "Domain Logic"
            KeyDefs["Keyboard Definitions<br/>(com.dessalines.thumbkey.keyboards)"]:::domain
            ModService["KeyboardModificationService"]:::domain
            LayoutUtil["KeyboardLayout"]:::domain
            AutoCap["AutoCapitalizers"]:::domain
            Utils["General Utilities"]:::domain
        end

        subgraph "Data Layer"
            AppDb["AppDb<br/>(Room Database)"]:::data
            Assets["YAML Config Assets"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        Voice1["FUTO Voice IME"]:::external
        Voice2["Transcribro"]:::external
        Voice3["Whisper IME"]:::external
    end

    %% CI/CD & Publishing
    subgraph "CI/CD & Publishing"
        Wood["Woodpecker Config"]:::external
        Fastlane["Fastlane Scripts"]:::external
    end

    %% Runtime and Configuration Flows
    AndroidIME -->|"register"| IMEService
    IMEService -->|"loadLayouts()"| ModService
    Assets -.->|"load"| ModService
    ModService -->|"provides layouts"| ComposeKeyboardView
    ModService -->|"reads/writes"| AppDb
    AppDb -.->|"settings data"| MainActivity
    MainActivity -->|"updates settings"| AppDb
    MainActivity -->|"launch"| SetupScreen
    ComposeKeyboardView -->|"onKeyEvent()"| IMEService
    IMEService -->|"commitText()"| AndroidIME
    IMEService -->|"switchIME()"| Voice1
    IMEService -->|"switchIME()"| Voice2
    IMEService -->|"switchIME()"| Voice3
    IMEService -.->|"IME XML config"| AndroidManifest
    %% CI/CD connections
    Wood -.-> Fastlane

    %% Click Events
    click IMEService "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/IMEService.kt"
    click ComposeKeyboardView "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/ComposeKeyboardView.kt"
    click MainActivity "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/MainActivity.kt"
    click KeyDefs "https://github.com/dessalines/thumb-key/tree/main/app/src/main/java/com/dessalines/thumbkey/keyboards/"
    click ModService "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/utils/KeyboardModificationService.kt"
    click LayoutUtil "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/utils/KeyboardLayout.kt"
    click AutoCap "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/utils/AutoCapitalizers.kt"
    click Utils "https://github.com/dessalines/thumb-key/tree/main/app/src/main/java/com/dessalines/thumbkey/utils/"
    click CommonUI "https://github.com/dessalines/thumb-key/tree/main/app/src/main/java/com/dessalines/thumbkey/ui/"
    click KeyboardUI "https://github.com/dessalines/thumb-key/tree/main/app/src/main/java/com/dessalines/thumbkey/ui/components/keyboard/"
    click SettingsUI "https://github.com/dessalines/thumb-key/tree/main/app/src/main/java/com/dessalines/thumbkey/ui/components/settings/"
    click SetupScreen "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/ui/components/setup/SetupScreen.kt"
    click AppDb "https://github.com/dessalines/thumb-key/blob/main/app/src/main/java/com/dessalines/thumbkey/db/AppDb.kt"
    click Assets "https://github.com/dessalines/thumb-key/tree/main/app/src/main/assets/"
    click AndroidManifest "https://github.com/dessalines/thumb-key/blob/main/app/src/main/AndroidManifest.xml"
    click IME_XML "https://github.com/dessalines/thumb-key/blob/main/app/src/main/res/xml/method.xml"
    click Wood "https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml"
    click Fastlane "https://github.com/dessalines/thumb-key/tree/main/fastlane/"

    %% Styles
    classDef presentation fill:#CCEEFF,stroke:#0366d6,color:#0366d6
    classDef domain fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef data fill:#FFF4E5,stroke:#D46A00,color:#D46A00
    classDef system fill:#E8E0FF,stroke:#6F42C1,color:#6F42C1
    classDef external fill:#F0F0F0,stroke:#6C757D,color:#6C757D
```
