# newterm/florence architecture

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

- Interactive diagram: https://gitdiagram.com/newterm/florence
- Repository: https://github.com/newterm/florence

## Overview

Florence is an accessible virtual keyboard: users point at or touch on-screen keys, which are rendered as a keyboard and dispatched as input; optional auto-click and focus-aware hiding support hands-free use. The GTK application also provides preferences, tray controls, configurable layouts/styles, and an optional Qt widget integration. The graph separates the GTK runtime, its domain layers, Qt components, and the layout editor. Edges reflect README statements or SOURCE INDEX references; unsampled implementations are represented only at the subsystem level.

Main entry points: [`src/florence.c`](https://github.com/newterm/florence/blob/master/src/florence.c) (Runtime coordinator), [`src/view.c`](https://github.com/newterm/florence/blob/master/src/view.c) (Keyboard display), [`src/keyboard.c`](https://github.com/newterm/florence/blob/master/src/keyboard.c) (Keyboard assembly), [`qt/src/florence.cpp`](https://github.com/newterm/florence/blob/master/qt/src/florence.cpp) (Qt keyboard widget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gtk["GTK keyboard"]
  node_main["Application startup<br/>[main.c]"]
  node_app["Runtime coordinator<br/>[florence.c]"]
  node_settings[("Preferences state<br/>[settings.c]")]
  node_preferences["Preferences window<br/>[settings-window.c]"]
  node_tray["Tray controls<br/>[trayicon.c]"]
  node_service["Session service<br/>[service.c]"]
end

subgraph group_domain["Input and presentation"]
  node_keyboard["Keyboard assembly<br/>[keyboard.c]"]
  node_layout["Layout reader<br/>[layoutreader.c]"]
  node_key["Key behavior<br/>[key.c]"]
  node_status["Input state<br/>[status.c]"]
  node_fsm["Input state machine<br/>[fsm.c]"]
  node_view["Keyboard display<br/>[view.c]"]
  node_style["Visual styling<br/>[style.c]"]
  node_xkeyboard["System keyboard input<br/>[xkeyboard.c]"]
  node_ramble["Ramble input mode<br/>[ramble.c]"]
end

subgraph group_qt["Qt widget"]
  node_qtwidget["Qt keyboard widget<br/>[florence.cpp]"]
  node_qtkey["Qt key interaction<br/>[key.cpp]"]
  node_qtmap["Qt keymap<br/>[keymap.cpp]"]
  node_qtsettings["Qt settings<br/>[settings.cpp]"]
  node_qtstyle["Qt style loader<br/>[style.cpp]"]
end

subgraph group_editor["Layout editor"]
  node_editor["Layout editor<br/>[editor.py]"]
  node_toolkit["Editor toolkit<br/>[toolkit.py]"]
end

node_user(("Pointing-device user"))

node_user -.->|"points at keys"| node_view
node_main -->|"initializes"| node_settings
node_main -->|"creates runtime"| node_app
node_main -->|"terminates"| node_service
node_app -->|"uses settings"| node_settings
node_app -->|"creates keyboard"| node_keyboard
node_app -->|"coordinates display"| node_view
node_app -->|"uses system input"| node_xkeyboard
node_app -->|"loads layouts"| node_layout
node_keyboard -->|"reads layout"| node_layout
node_keyboard -->|"assembles keys"| node_key
node_keyboard -->|"uses key mapping"| node_xkeyboard
node_status -->|"tracks key state"| node_key
node_status -->|"updates display"| node_view
node_status -->|"uses state machine"| node_fsm
node_view -->|"displays keyboard"| node_keyboard
node_view -->|"reads settings"| node_settings
node_view -->|"uses styling"| node_style
node_style -->|"reads style data"| node_layout
node_preferences -->|"edits settings"| node_settings
node_qtwidget -->|"manages keys"| node_qtkey
node_qtwidget -->|"uses settings"| node_qtsettings
node_qtwidget -->|"loads keymap"| node_qtmap
node_qtwidget -->|"loads style"| node_qtstyle
node_qtkey -->|"uses style"| node_qtstyle
node_qtkey -->|"uses keymap"| node_qtmap
node_editor -->|"uses toolkit"| node_toolkit

click node_main "https://github.com/newterm/florence/blob/master/src/main.c"
click node_app "https://github.com/newterm/florence/blob/master/src/florence.c"
click node_settings "https://github.com/newterm/florence/blob/master/src/settings.c"
click node_preferences "https://github.com/newterm/florence/blob/master/src/settings-window.c"
click node_tray "https://github.com/newterm/florence/blob/master/src/trayicon.c"
click node_service "https://github.com/newterm/florence/blob/master/src/service.c"
click node_keyboard "https://github.com/newterm/florence/blob/master/src/keyboard.c"
click node_layout "https://github.com/newterm/florence/blob/master/src/layoutreader.c"
click node_key "https://github.com/newterm/florence/blob/master/src/key.c"
click node_status "https://github.com/newterm/florence/blob/master/src/status.c"
click node_fsm "https://github.com/newterm/florence/blob/master/src/fsm.c"
click node_view "https://github.com/newterm/florence/blob/master/src/view.c"
click node_style "https://github.com/newterm/florence/blob/master/src/style.c"
click node_xkeyboard "https://github.com/newterm/florence/blob/master/src/xkeyboard.c"
click node_ramble "https://github.com/newterm/florence/blob/master/src/ramble.c"
click node_qtwidget "https://github.com/newterm/florence/blob/master/qt/src/florence.cpp"
click node_qtkey "https://github.com/newterm/florence/blob/master/qt/src/key.cpp"
click node_qtmap "https://github.com/newterm/florence/blob/master/qt/src/keymap.cpp"
click node_qtsettings "https://github.com/newterm/florence/blob/master/qt/src/settings.cpp"
click node_qtstyle "https://github.com/newterm/florence/blob/master/qt/src/style.cpp"
click node_editor "https://github.com/newterm/florence/blob/master/editor/editor.py"
click node_toolkit "https://github.com/newterm/florence/blob/master/editor/toolkit.py"

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_main,node_app,node_settings,node_preferences,node_tray,node_service,node_user toneBlue
class node_keyboard,node_layout,node_key,node_status,node_fsm,node_view,node_style,node_xkeyboard,node_ramble toneAmber
class node_qtwidget,node_qtkey,node_qtmap,node_qtsettings,node_qtstyle toneMint
class node_editor,node_toolkit toneRose
```

## Components

### GTK keyboard

- [Application startup](https://github.com/newterm/florence/blob/master/src/main.c): `src/main.c`
- [Runtime coordinator](https://github.com/newterm/florence/blob/master/src/florence.c): `src/florence.c`
- [Preferences state](https://github.com/newterm/florence/blob/master/src/settings.c): `src/settings.c`
- [Preferences window](https://github.com/newterm/florence/blob/master/src/settings-window.c): `src/settings-window.c`
- [Tray controls](https://github.com/newterm/florence/blob/master/src/trayicon.c): `src/trayicon.c`
- [Session service](https://github.com/newterm/florence/blob/master/src/service.c): `src/service.c`

### Input and presentation

- [Keyboard assembly](https://github.com/newterm/florence/blob/master/src/keyboard.c): `src/keyboard.c`
- [Layout reader](https://github.com/newterm/florence/blob/master/src/layoutreader.c): `src/layoutreader.c`
- [Key behavior](https://github.com/newterm/florence/blob/master/src/key.c): `src/key.c`
- [Input state](https://github.com/newterm/florence/blob/master/src/status.c): `src/status.c`
- [Input state machine](https://github.com/newterm/florence/blob/master/src/fsm.c): `src/fsm.c`
- [Keyboard display](https://github.com/newterm/florence/blob/master/src/view.c): `src/view.c`
- [Visual styling](https://github.com/newterm/florence/blob/master/src/style.c): `src/style.c`
- [System keyboard input](https://github.com/newterm/florence/blob/master/src/xkeyboard.c): `src/xkeyboard.c`
- [Ramble input mode](https://github.com/newterm/florence/blob/master/src/ramble.c): `src/ramble.c`

### Qt widget

- [Qt keyboard widget](https://github.com/newterm/florence/blob/master/qt/src/florence.cpp): `qt/src/florence.cpp`
- [Qt key interaction](https://github.com/newterm/florence/blob/master/qt/src/key.cpp): `qt/src/key.cpp`
- [Qt keymap](https://github.com/newterm/florence/blob/master/qt/src/keymap.cpp): `qt/src/keymap.cpp`
- [Qt settings](https://github.com/newterm/florence/blob/master/qt/src/settings.cpp): `qt/src/settings.cpp`
- [Qt style loader](https://github.com/newterm/florence/blob/master/qt/src/style.cpp): `qt/src/style.cpp`

### Layout editor

- [Layout editor](https://github.com/newterm/florence/blob/master/editor/editor.py): `editor/editor.py`
- [Editor toolkit](https://github.com/newterm/florence/blob/master/editor/toolkit.py): `editor/toolkit.py`

### Other components

- **Pointing-device user**

## Connections

- Pointing-device user → Keyboard display: points at keys (evidence: `README`)
- Application startup → Preferences state: initializes (evidence: `src/main.c`)
- Application startup → Runtime coordinator: creates runtime (evidence: `src/main.c`)
- Application startup → Session service: terminates (evidence: `src/main.c`)
- Runtime coordinator → Preferences state: uses settings (evidence: `src/florence.c`)
- Runtime coordinator → Keyboard assembly: creates keyboard (evidence: `src/florence.c`)
- Runtime coordinator → Keyboard display: coordinates display (evidence: `src/florence.c`)
- Runtime coordinator → System keyboard input: uses system input (evidence: `src/florence.c`)
- Runtime coordinator → Layout reader: loads layouts (evidence: `src/florence.c`)
- Keyboard assembly → Layout reader: reads layout
- Keyboard assembly → Key behavior: assembles keys
- Keyboard assembly → System keyboard input: uses key mapping
- Input state → Key behavior: tracks key state
- Input state → Keyboard display: updates display
- Input state → Input state machine: uses state machine
- Keyboard display → Keyboard assembly: displays keyboard (evidence: `src/view.c`)
- Keyboard display → Preferences state: reads settings (evidence: `src/view.c`)
- Keyboard display → Visual styling: uses styling
- Visual styling → Layout reader: reads style data (evidence: `src/style.c`)
- Preferences window → Preferences state: edits settings (evidence: `src/settings-window.c`)
- Qt keyboard widget → Qt key interaction: manages keys (evidence: `qt/src/key.cpp`)
- Qt keyboard widget → Qt settings: uses settings
- Qt keyboard widget → Qt keymap: loads keymap
- Qt keyboard widget → Qt style loader: loads style
- Qt key interaction → Qt style loader: uses style
- Qt key interaction → Qt keymap: uses keymap
- Layout editor → Editor toolkit: uses toolkit (evidence: `editor/editor.py`)
