# fcitx/fcitx5-unikey architecture

> Architecture diagram of the GitHub repository fcitx/fcitx5-unikey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fcitx/fcitx5-unikey
- Repository: https://github.com/fcitx/fcitx5-unikey

## Overview

This repository provides a Fcitx5 Vietnamese input method: typed keys are handled in an input context, transformed by Unikey’s composition engine, and returned as text for the application. Users can configure input method, output charset, spelling and macro options; Qt editors support macro and custom-keymap management. The sampled code confirms the Fcitx integration and engine adapter, but not all conversion, persistence, or macro-loading internals, so those connections are shown only where supported.

Main entry points: [`src/unikey-im.cpp`](https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-im.cpp) (Unikey addon), [`unikey/ukengine.cpp`](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/ukengine.cpp) (Composition engine), [`unikey/unikeyinputcontext.cpp`](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/unikeyinputcontext.cpp) (Input adapter), [`macro-editor/editor.cpp`](https://github.com/fcitx/fcitx5-unikey/blob/master/macro-editor/editor.cpp) (Macro editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Fcitx integration"]
  node_im_engine["Unikey addon<br/>[unikey-im.cpp]"]
  node_im_state["Input state<br/>[unikey-im.cpp]"]
  node_config["Addon configuration<br/>[unikey-config.h]"]
end

subgraph group_engine["Input engine"]
  node_input_context["Input adapter"]
  node_uk_engine["Composition engine<br/>[ukengine.cpp]"]
  node_input_processor["Key processing<br/>[inputproc.cpp]"]
  node_charset["Charset conversion<br/>[charset.cpp]"]
  node_macro_table["Macro table<br/>[mactab.cpp]"]
  node_keymap["User keymap<br/>[usrkeymap.cpp]"]
end

subgraph group_configuration["Configuration tools"]
end

subgraph group_editors["Qt editors"]
  node_macro_editor["Macro editor<br/>[editor.cpp]"]
  node_macro_model["Macro model<br/>[model.cpp]"]
  node_keymap_editor["Keymap editor<br/>[editor.cpp]"]
  node_keymap_model["Keymap model<br/>[model.cpp]"]
end

node_user(("User"))
node_fcitx["Fcitx host"]
node_application["Text application"]

node_user -->|"types keys"| node_fcitx
node_fcitx -->|"dispatches events"| node_im_engine
node_im_engine -->|"handles keys"| node_im_state
node_im_state -->|"filters input"| node_input_context
node_input_context -->|"processes keys"| node_uk_engine
node_uk_engine -->|"returns output"| node_input_context
node_im_engine -->|"loads settings"| node_config
node_im_engine -->|"configures method"| node_input_context
node_input_context -->|"provides text"| node_application
node_uk_engine -->|"uses mappings"| node_input_processor
node_uk_engine -->|"converts output"| node_charset
node_uk_engine -->|"matches macros"| node_macro_table
node_im_engine -->|"reloads keymap"| node_keymap
node_user -->|"edits macros"| node_macro_editor
node_macro_editor -->|"updates entries"| node_macro_model
node_user -->|"edits keymap"| node_keymap_editor
node_keymap_editor -->|"updates mappings"| node_keymap_model

click node_im_engine "https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-im.cpp"
click node_im_state "https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-im.cpp"
click node_input_context "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/unikeyinputcontext.cpp"
click node_uk_engine "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/ukengine.cpp"
click node_input_processor "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/inputproc.cpp"
click node_charset "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/charset.cpp"
click node_macro_table "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/mactab.cpp"
click node_keymap "https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/usrkeymap.cpp"
click node_config "https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-config.h"
click node_macro_editor "https://github.com/fcitx/fcitx5-unikey/blob/master/macro-editor/editor.cpp"
click node_macro_model "https://github.com/fcitx/fcitx5-unikey/blob/master/macro-editor/model.cpp"
click node_keymap_editor "https://github.com/fcitx/fcitx5-unikey/blob/master/keymap-editor/editor.cpp"
click node_keymap_model "https://github.com/fcitx/fcitx5-unikey/blob/master/keymap-editor/model.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_im_engine,node_im_state,node_config,node_user toneBlue
class node_input_context,node_uk_engine,node_input_processor,node_charset,node_macro_table,node_keymap toneAmber
class node_macro_editor,node_macro_model,node_keymap_editor,node_keymap_model toneRose
class node_fcitx,node_application toneIndigo
```

## Components

### Fcitx integration

- [Unikey addon](https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-im.cpp): `src/unikey-im.cpp`
- [Input state](https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-im.cpp): `src/unikey-im.cpp`
- [Addon configuration](https://github.com/fcitx/fcitx5-unikey/blob/master/src/unikey-config.h): `src/unikey-config.h`

### Input engine

- [Input adapter](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/unikeyinputcontext.cpp): `unikey/unikeyinputcontext.cpp`
- [Composition engine](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/ukengine.cpp): `unikey/ukengine.cpp`
- [Key processing](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/inputproc.cpp): `unikey/inputproc.cpp`
- [Charset conversion](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/charset.cpp): `unikey/charset.cpp`
- [Macro table](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/mactab.cpp): `unikey/mactab.cpp`
- [User keymap](https://github.com/fcitx/fcitx5-unikey/blob/master/unikey/usrkeymap.cpp): `unikey/usrkeymap.cpp`

### Qt editors

- [Macro editor](https://github.com/fcitx/fcitx5-unikey/blob/master/macro-editor/editor.cpp): `macro-editor/editor.cpp`
- [Macro model](https://github.com/fcitx/fcitx5-unikey/blob/master/macro-editor/model.cpp): `macro-editor/model.cpp`
- [Keymap editor](https://github.com/fcitx/fcitx5-unikey/blob/master/keymap-editor/editor.cpp): `keymap-editor/editor.cpp`
- [Keymap model](https://github.com/fcitx/fcitx5-unikey/blob/master/keymap-editor/model.cpp): `keymap-editor/model.cpp`

### Other components

- **User**
- **Fcitx host**
- **Text application**

## Connections

- User → Fcitx host: types keys
- Fcitx host → Unikey addon: dispatches events
- Unikey addon → Input state: handles keys
- Input state → Input adapter: filters input
- Input adapter → Composition engine: processes keys
- Composition engine → Input adapter: returns output
- Unikey addon → Addon configuration: loads settings
- Unikey addon → Input adapter: configures method
- Input adapter → Text application: provides text
- Composition engine → Key processing: uses mappings
- Composition engine → Charset conversion: converts output
- Composition engine → Macro table: matches macros
- Unikey addon → User keymap: reloads keymap
- User → Macro editor: edits macros
- Macro editor → Macro model: updates entries
- User → Keymap editor: edits keymap
- Keymap editor → Keymap model: updates mappings