# opensifli/zmk architecture

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

- Interactive diagram: https://gitdiagram.com/opensifli/zmk
- Repository: https://github.com/opensifli/zmk

## Overview

ZMK is Zephyr-based mechanical-keyboard firmware; this fork documents a split SF32LB52 keyboard target. The principal runtime path is physical key scanning into keymap behaviors, then HID output to a host, with split transport coordinating keyboard halves. Separate capabilities include pointing input, battery/status display, and ZMK Studio. The tree establishes these subsystems, but most implementation excerpts are unavailable, so uncertain runtime connections are shown as unverified rather than asserted.

Main entry points: [`app/src/keymap.c`](https://github.com/opensifli/zmk/blob/main/app/src/keymap.c) (Keymap state), [`app/src/behavior.c`](https://github.com/opensifli/zmk/blob/main/app/src/behavior.c) (Behavior engine), [`app/src/endpoints.c`](https://github.com/opensifli/zmk/blob/main/app/src/endpoints.c) (Output selection), [`app/src/split/central.c`](https://github.com/opensifli/zmk/blob/main/app/src/split/central.c) (Split central)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and mapping"]
  node_kscan["GPIO key scan"]
  node_matrix["Matrix transform<br/>[matrix_transform.c]"]
  node_keymap["Keymap state<br/>[keymap.c]"]
  node_combos["Combos and layers<br/>[combo.c]"]
  node_behavior["Behavior engine<br/>[behavior.c]"]
  node_behavior_set["Key behaviors"]
end

subgraph group_output["Host connectivity"]
  node_hid["HID reports<br/>[hid.c]"]
  node_endpoints["Output selection<br/>[endpoints.c]"]
  node_usb["USB HID<br/>[usb_hid.c]"]
  node_ble["Bluetooth HID<br/>[hog.c]"]
end

subgraph group_split["Split keyboard"]
  node_split_central["Split central<br/>[central.c]"]
  node_split_peripheral["Split peripheral<br/>[peripheral.c]"]
  node_split_service["Bluetooth split service<br/>[service.c]"]
  node_wired_central["Wired split central<br/>[central.c]"]
  node_wired_transport["Wired transport<br/>[wired.c]"]
end

subgraph group_extras["Status and extensions"]
  node_pointing["Pointing input<br/>[input_listener.c]"]
  node_battery["Battery sensing<br/>[max17048.c]"]
  node_display["Status display<br/>[main.c]"]
  node_status_screen["Status screen<br/>[status_screen.c]"]
  node_studio["Studio keymap RPC<br/>[keymap_subsystem.c]"]
end

node_keyboard_user(("Keyboard user"))
node_host(("Host device"))

node_keyboard_user -.->|"presses keys"| node_kscan
node_kscan -.->|"reports positions"| node_matrix
node_matrix -.->|"maps positions"| node_keymap
node_keymap -.->|"resolves bindings"| node_combos
node_keymap -.->|"dispatches behaviors"| node_behavior
node_behavior -.->|"runs behavior"| node_behavior_set
node_behavior -.->|"updates reports"| node_hid
node_hid -.->|"selects output"| node_endpoints
node_endpoints -.->|"routes USB"| node_usb
node_endpoints -.->|"routes Bluetooth"| node_ble
node_usb -.->|"sends reports"| node_host
node_ble -.->|"sends reports"| node_host
node_split_central -.->|"uses GATT service"| node_split_service
node_split_central -.->|"supports wired role"| node_wired_central
node_wired_central -.->|"uses transport"| node_wired_transport
node_split_peripheral -.->|"provides service"| node_split_service
node_pointing -.->|"feeds input"| node_behavior
node_display -->|"loads screen"| node_status_screen
node_battery -.->|"supplies status"| node_display
node_studio -.->|"updates keymap"| node_keymap

click node_kscan "https://github.com/opensifli/zmk/blob/main/app/module/drivers/kscan/kscan_gpio_matrix.c"
click node_matrix "https://github.com/opensifli/zmk/blob/main/app/src/matrix_transform.c"
click node_keymap "https://github.com/opensifli/zmk/blob/main/app/src/keymap.c"
click node_combos "https://github.com/opensifli/zmk/blob/main/app/src/combo.c"
click node_behavior "https://github.com/opensifli/zmk/blob/main/app/src/behavior.c"
click node_behavior_set "https://github.com/opensifli/zmk/blob/main/app/src/behaviors/behavior_hold_tap.c"
click node_hid "https://github.com/opensifli/zmk/blob/main/app/src/hid.c"
click node_endpoints "https://github.com/opensifli/zmk/blob/main/app/src/endpoints.c"
click node_usb "https://github.com/opensifli/zmk/blob/main/app/src/usb_hid.c"
click node_ble "https://github.com/opensifli/zmk/blob/main/app/src/hog.c"
click node_split_central "https://github.com/opensifli/zmk/blob/main/app/src/split/central.c"
click node_split_peripheral "https://github.com/opensifli/zmk/blob/main/app/src/split/peripheral.c"
click node_split_service "https://github.com/opensifli/zmk/blob/main/app/src/split/bluetooth/service.c"
click node_wired_central "https://github.com/opensifli/zmk/blob/main/app/src/split/wired/central.c"
click node_wired_transport "https://github.com/opensifli/zmk/blob/main/app/src/split/wired/wired.c"
click node_pointing "https://github.com/opensifli/zmk/blob/main/app/src/pointing/input_listener.c"
click node_battery "https://github.com/opensifli/zmk/blob/main/app/module/drivers/sensor/max17048/max17048.c"
click node_display "https://github.com/opensifli/zmk/blob/main/app/src/display/main.c"
click node_status_screen "https://github.com/opensifli/zmk/blob/main/app/src/display/status_screen.c"
click node_studio "https://github.com/opensifli/zmk/blob/main/app/src/studio/keymap_subsystem.c"

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_kscan,node_matrix,node_keymap,node_combos,node_behavior,node_behavior_set,node_keyboard_user toneBlue
class node_hid,node_endpoints,node_usb,node_ble toneAmber
class node_split_central,node_split_peripheral,node_split_service,node_wired_central,node_wired_transport toneMint
class node_pointing,node_battery,node_display,node_status_screen,node_studio toneRose
class node_host toneIndigo
```

## Components

### Input and mapping

- [GPIO key scan](https://github.com/opensifli/zmk/blob/main/app/module/drivers/kscan/kscan_gpio_matrix.c): `app/module/drivers/kscan/kscan_gpio_matrix.c`
- [Matrix transform](https://github.com/opensifli/zmk/blob/main/app/src/matrix_transform.c): `app/src/matrix_transform.c`
- [Keymap state](https://github.com/opensifli/zmk/blob/main/app/src/keymap.c): `app/src/keymap.c`
- [Combos and layers](https://github.com/opensifli/zmk/blob/main/app/src/combo.c): `app/src/combo.c`
- [Behavior engine](https://github.com/opensifli/zmk/blob/main/app/src/behavior.c): `app/src/behavior.c`
- [Key behaviors](https://github.com/opensifli/zmk/blob/main/app/src/behaviors/behavior_hold_tap.c): `app/src/behaviors/behavior_hold_tap.c`

### Host connectivity

- [HID reports](https://github.com/opensifli/zmk/blob/main/app/src/hid.c): `app/src/hid.c`
- [Output selection](https://github.com/opensifli/zmk/blob/main/app/src/endpoints.c): `app/src/endpoints.c`
- [USB HID](https://github.com/opensifli/zmk/blob/main/app/src/usb_hid.c): `app/src/usb_hid.c`
- [Bluetooth HID](https://github.com/opensifli/zmk/blob/main/app/src/hog.c): `app/src/hog.c`

### Split keyboard

- [Split central](https://github.com/opensifli/zmk/blob/main/app/src/split/central.c): `app/src/split/central.c`
- [Split peripheral](https://github.com/opensifli/zmk/blob/main/app/src/split/peripheral.c): `app/src/split/peripheral.c`
- [Bluetooth split service](https://github.com/opensifli/zmk/blob/main/app/src/split/bluetooth/service.c): `app/src/split/bluetooth/service.c`
- [Wired split central](https://github.com/opensifli/zmk/blob/main/app/src/split/wired/central.c): `app/src/split/wired/central.c`
- [Wired transport](https://github.com/opensifli/zmk/blob/main/app/src/split/wired/wired.c): `app/src/split/wired/wired.c`

### Status and extensions

- [Pointing input](https://github.com/opensifli/zmk/blob/main/app/src/pointing/input_listener.c): `app/src/pointing/input_listener.c`
- [Battery sensing](https://github.com/opensifli/zmk/blob/main/app/module/drivers/sensor/max17048/max17048.c): `app/module/drivers/sensor/max17048/max17048.c`
- [Status display](https://github.com/opensifli/zmk/blob/main/app/src/display/main.c): `app/src/display/main.c`
- [Status screen](https://github.com/opensifli/zmk/blob/main/app/src/display/status_screen.c): `app/src/display/status_screen.c`
- [Studio keymap RPC](https://github.com/opensifli/zmk/blob/main/app/src/studio/keymap_subsystem.c): `app/src/studio/keymap_subsystem.c`

### Other components

- **Keyboard user**
- **Host device**

## Connections

- Keyboard user → GPIO key scan: presses keys
- GPIO key scan → Matrix transform: reports positions
- Matrix transform → Keymap state: maps positions
- Keymap state → Combos and layers: resolves bindings
- Keymap state → Behavior engine: dispatches behaviors
- Behavior engine → Key behaviors: runs behavior
- Behavior engine → HID reports: updates reports
- HID reports → Output selection: selects output
- Output selection → USB HID: routes USB
- Output selection → Bluetooth HID: routes Bluetooth
- USB HID → Host device: sends reports
- Bluetooth HID → Host device: sends reports
- Split central → Bluetooth split service: uses GATT service
- Split central → Wired split central: supports wired role
- Wired split central → Wired transport: uses transport
- Split peripheral → Bluetooth split service: provides service
- Pointing input → Behavior engine: feeds input
- Status display → Status screen: loads screen (evidence: `app/src/display/main.c`)
- Battery sensing → Status display: supplies status
- Studio keymap RPC → Keymap state: updates keymap