# julow/unexpected-keyboard architecture

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

- Interactive diagram: https://gitdiagram.com/julow/unexpected-keyboard
- Repository: https://github.com/julow/unexpected-keyboard

## Overview

##### Project type and purpose
- This is a single-module, full-stack Android application (an IME keyboard) called “Unexpected Keyboard.”
- Purpose: a lightweight, privacy-conscious virtual keyboard for Android that supports corner-swipe input to access extended characters, plus clipboard history features.
- Deployment: packaged via Gradle, distributed on F-Droid and Google Play with Fastlane scripts.

##### File structure
- Top level:
– AndroidManifest.xml, res/ (layouts, drawables, values, xml menus), assets/
– srcs/juloo.keyboard2/… Java UI & service code implementing Activities, Services, Views, InputMethod logic
– srcs/compose & srcs/layouts: Python/JSON/XML and Java scripts to generate keyboard layouts and compose files
– build.gradle.kts, gradle/…, shell.nix: build configuration and reproducible environment
– fastlane/metadata: deployment metadata
– check_layout.py, gen_layouts.py, gen_emoji.py: validation and code-generation pipelines
– test/: unit tests for core logic

##### README for additional insights
- Confirms core feature: swipe to corners for alternate symbols
- No external network calls or analytics (purely local)
- Originally designed for Termux, now general-purpose

##### Main components
a. Android App UI Layer
– LauncherActivity, SettingsActivity (Activity components)
– Keyboard2View & custom Views (ClipboardHistoryView, EmojiGridView)
b. Input Method / Core Logic
– Keyboard2 (InputMethodService subclass)
– KeyEventHandler, ComposeKey, Modmap – processes touch & swipe events, maps to characters
c. Data & Persistence
– SharedPreferences via DirectBootAwarePreferences
– Custom layouts / extra keys definitions loaded from res/xml & generated XML files
– ClipboardHistoryService & storage for clipboard entries
d. Build & Deployment Pipeline
– Code-gen scripts (gen_layouts.py, compile.py in srcs/compose, SvgToVector.java) produce XML/Java artifacts
– Gradle / Kotlin DSL builds .apk
– Fastlane tasks upload to F-Droid / Google Play
e. Testing
– Unit tests (ModmapTest, KeyValueParserTest) run via Gradle test tasks

##### Relationships & interactions
- User touch → Android framework → InputMethodService (Keyboard2)
- Keyboard2 delegates to KeyEventHandler / ComposeKeyData → character output
- Swipe gestures trigger alternate key lookup in KeyboardData (populated from generated layouts)
- Clipboard actions routed through ClipboardHistoryService ⇄ persistent storage
- Settings UI reads/writes config via SharedPreferences
- Build pipeline: code-gen scripts → resource generation → Gradle compile → apk → Fastlane publish

##### Architectural patterns & design principles
- Separation of concerns:
– UI (Activities/Views) vs. InputMethod core vs. Data storage
- Code generation for maintainability: layout definitions centralized in JSON/XML, transformed by scripts
- Modular resource layering: res/xml for keyboard rows, res/layout for dialogs & panes
- Testable core logic separated from Android framework for unit testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/UI Layer
    subgraph "Presentation/UI Layer"
        LA["LauncherActivity"]:::androidComp
        SA["SettingsActivity"]:::androidComp
        K2V["Keyboard2View"]:::androidComp
        CHV["ClipboardHistoryView"]:::androidComp
        EGV["EmojiGridView"]:::androidComp
    end

    %% InputMethod/Core Logic Layer
    subgraph "InputMethod/Core Logic Layer"
        K2["Keyboard2 (InputMethodService)"]:::androidComp
        KEH["KeyEventHandler"]:::logic
        CK["ComposeKey"]:::logic
        CKD["ComposeKeyData"]:::logic
        MM["Modmap"]:::logic
        KD["KeyboardData"]:::logic
    end

    %% Data & Persistence Layer
    subgraph "Data & Persistence Layer"
        DBP["DirectBootAwarePreferences"]:::data
        CHS["ClipboardHistoryService"]:::data
        XMLR["XML layout resources"]:::data
        GKL["Generated keyboard layouts"]:::data
    end

    %% Build & Deployment Layer
    subgraph "Build & Deployment Layer"
        GL["gen_layouts.py"]:::tools
        CL["check_layout.py"]:::tools
        CPY["compile.py"]:::tools
        SVG["SvgToVector.java"]:::tools
        subgraph "Gradle Build Config"
            BG["build.gradle.kts"]:::tools
            SG["settings.gradle.kts"]:::tools
            GW["gradle/…"]:::tools
            GP["gradle.properties"]:::tools
        end
        FL["fastlane/metadata/android/**"]:::tools
    end

    %% Testing Layer
    subgraph "Testing"
        MT["ModmapTest"]:::test
        KVP["KeyValueParserTest"]:::test
        CKT["ComposeKeyTest"]:::test
        KVT["KeyValueTest"]:::test
    end

    %% Relationships: UI to Service
    LA -->|"launches"| K2
    SA -->|"opens settings"| DBP
    K2V -->|"input UI"| K2
    CHV -->|"view clipboard"| CHS
    EGV -->|"view emojis"| KD

    %% Touch flow
    K2 -->|"delegates touch"| KEH
    KEH -->|"compose logic"| CK
    CK -->|"data lookup"| CKD
    KEH -->|"modifiers"| MM
    KEH -->|"load layout"| KD
    KD -->|"reads XML"| XMLR
    KD -->|"reads generated"| GKL

    %% Data interactions
    DBP -->|"stores prefs"| XMLR
    CHS -->|"stores entries"| GKL

    %% Build pipeline arrows
    GL -->|"generate layouts"| GKL
    CL -->|"validate"| GKL
    CPY -->|"compile compose"| CKD
    SVG -->|"convert icons"| XMLR
    GKL -->|"include in resources"| BG
    BG -->|"build apk"| FL
    SG --> BG
    GW --> BG
    GP --> BG
    FL -->|"deploy apk"| FL

    %% Testing relationships
    MT -->|"tests mapping"| MM
    KVP -->|"tests parser"| KD
    CKT -->|"tests compose"| CK
    KVT -->|"tests values"| KEH

    %% Click Events
    click LA "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/LauncherActivity.java"
    click SA "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/SettingsActivity.java"
    click K2V "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/Keyboard2View.java"
    click CHV "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/ClipboardHistoryView.java"
    click EGV "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/EmojiGridView.java"
    click K2 "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/Keyboard2.java"
    click KEH "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/KeyEventHandler.java"
    click CK "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/ComposeKey.java"
    click CKD "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/ComposeKeyData.java"
    click MM "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/Modmap.java"
    click KD "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/KeyboardData.java"
    click DBP "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/DirectBootAwarePreferences.java"
    click CHS "https://github.com/julow/unexpected-keyboard/blob/master/srcs/juloo.keyboard2/ClipboardHistoryService.java"
    click XMLR "https://github.com/julow/unexpected-keyboard/blob/master/res/xml/*.xml"
    click GKL "https://github.com/julow/unexpected-keyboard/blob/master/srcs/layouts/*.xml"
    click GL "https://github.com/julow/unexpected-keyboard/blob/master/gen_layouts.py"
    click CL "https://github.com/julow/unexpected-keyboard/blob/master/check_layout.py"
    click CPY "https://github.com/julow/unexpected-keyboard/blob/master/srcs/compose/compile.py"
    click SVG "https://github.com/julow/unexpected-keyboard/blob/master/srcs/res/SvgToVector.java"
    click BG "https://github.com/julow/unexpected-keyboard/blob/master/build.gradle.kts"
    click SG "https://github.com/julow/unexpected-keyboard/blob/master/settings.gradle.kts"
    click GW "https://github.com/julow/unexpected-keyboard/tree/master/gradle/"
    click GP "https://github.com/julow/unexpected-keyboard/blob/master/gradle.properties"
    click FL "https://github.com/julow/unexpected-keyboard/tree/master/fastlane/metadata/android/"

    %% Styles
    classDef androidComp fill:#CDE,stroke:#333,stroke-width:1px
    classDef logic fill:#CFC,stroke:#333,stroke-width:1px
    classDef data fill:#FDC,stroke:#333,stroke-width:1px
    classDef tools fill:#DDD,stroke:#333,stroke-width:1px
    classDef test fill:#DDF,stroke:#333,stroke-width:1px
```
