# cspeterson/splatmoji architecture

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

- Interactive diagram: https://gitdiagram.com/cspeterson/splatmoji
- Repository: https://github.com/cspeterson/splatmoji

## Overview

##### Project Type and Purpose
- Splatmoji is an open-source, command-line utility written in Bash for quickly looking up and inserting emoji and emoticons/kaomoji on a GNU/Linux desktop via a pop-up menu.
- It leverages external tools (rofi, xdotool, xsel, jq) to present a menu, copy selections to the clipboard, or “type” them into the current window.

##### File‐Structure Analysis
- Top level
- splatmoji (the main executable script)
- splatmoji.config (default config template)
- build.sh, BUILD.md, LICENSE, README.md, CHANGELOG
- data/emoji & data/emoticons – TSV databases (per-language annotation files and emoticon lists)
- importers/ – scripts to convert external data sources into the TSV format
- lib/
- functions/ – reusable Bash functions for CLI parsing, data loading, filtering
- test_helpers/ – utilities for the test suite
- test/unit_tests – integration and unit tests (shunit2‐based)

##### Key Architecture Insights from README
- Modes of operation: copy, type, copypaste
- Configuration layering: built-in config, user config (`~/.config/splatmoji/splatmoji.config`), environment vars
- Data‐file discovery: CLI args → XDG_DATA_HOME → XDG_DATA_DIRS → in-repo data/
- Extensibility: custom TSV files, custom emoticon data, add new importers

a. Main Components
1. CLI Front End
- Argument parser, mode dispatcher
2. Configuration Manager
- Reads splatmoji.config and user overrides
3. Data Manager
- Discovers and loads TSV data files (emoji & emoticons)
- Applies language filters and skin-tone filters
4. UI Manager
- Builds the menu payload
- Invokes rofi (pop-up menu)
5. Selection Handler
- Receives user’s choice from rofi
- Updates history (recently‐used list)
6. Output Manager
- For “copy” mode: pipes output to xsel/xclip
- For “type” mode: invokes xdotool to type characters
- For “copypaste” mode: combo of both
7. Importer Tools (optional)
- Scripts in importers/ to generate/update TSV from external sources
8. Test Suite
- Runs functions through lib/test_helpers via shunit2

b. Relationships & Data Flow
- User invokes the `splatmoji` script → CLI Front End
- CLI Front End → Configuration Manager (load defaults + overrides)
- Configuration Manager → Data Manager (pass parameters: languages, skin-tones, disabled DB flags)
- Data Manager → UI Manager (provides list entries)
- UI Manager ↔ rofi (displays menu, captures selection)
- UI Manager → Selection Handler → updates history file via Data Manager
- Selection Handler → Output Manager → calls external tools (xsel, xdotool)
- Importer Tools → Data Manager (generate or refresh data/)
- Test Suite → each internal component (lib/functions, CLI script)

c. Architectural Patterns & Principles
- Modularization: separate responsibilities into small, reusable functions in `lib/functions`.
- Config layering: default + user override following XDG conventions.
- Data-driven design: all emoji/emoticon info lives in TSV files, making it easy to extend.
- External integration: thin wrappers around rofi, xdotool, xsel to remain agnostic of specific UI/clipboard implementations.
- Testability: functions are pure enough to be unit‐tested via shunit2.

d. Key Technologies & Libraries
- Bash (>=4.4)
- rofi (menu UI)
- xdotool (auto-typing)
- xsel or xclip (clipboard)
- jq (optional JSON escaping)
- shunit2 (testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Components
    subgraph "Core Engine"
        direction TB
        CLI["CLI Front End"]:::internal
        Config["Configuration Manager"]:::internal
        Data["Data Manager"]:::datastore
        UI["UI Manager"]:::internal
        Select["Selection Handler"]:::internal
        Output["Output Manager"]:::internal
    end

    %% Optional and External
    Importers["Importer Tools"]:::internal
    TestSuite["Test Suite"]:::internal
    rofi[(rofi)]:::external
    xdotool[(xdotool)]:::external
    xsel[(xsel/xclip)]:::external
    jq[(jq)]:::external

    %% Data Store
    TSV[(TSV Databases)]:::datastore

    %% Flows
    CLI -->|"load config"| Config
    Config -->|"params"| Data
    Data -->|"entries"| UI
    UI -->|display menu| rofi
    rofi -->|selection| UI
    UI -->|"choice"| Select
    Select -->|"update history"| Data
    Select -->|invoke| Output
    Output -->|type| xdotool
    Output -->|copy| xsel
    Importers -->|"generate/refresh"| Data
    TestSuite --> CLI
    TestSuite --> Config
    TestSuite --> Data
    TestSuite --> UI
    TestSuite --> Select
    TestSuite --> Output

    %% Data store connections
    Data -->|"loads from"| TSV

    %% Click Events
    click CLI "https://github.com/cspeterson/splatmoji/tree/master/splatmoji"
    click Config "https://github.com/cspeterson/splatmoji/blob/master/splatmoji.config"
    click Data "https://github.com/cspeterson/splatmoji/tree/master/data/"
    click UI "https://github.com/cspeterson/splatmoji/tree/master/lib/functions/"
    click Select "https://github.com/cspeterson/splatmoji/tree/master/lib/functions/"
    click Output "https://github.com/cspeterson/splatmoji/tree/master/lib/functions/"
    click Importers "https://github.com/cspeterson/splatmoji/tree/master/importers/"
    click TestSuite "https://github.com/cspeterson/splatmoji/tree/master/test/unit_tests/"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#007bff,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef datastore fill:#fff3cd,stroke:#ffc107,stroke-width:1px;
```
