# keychron/zmk architecture

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

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

## Overview

##### Project Type and Purpose
- ZMK is an embedded firmware project for mechanical keyboards, built on the Zephyr RTOS.
- It provides a modular stack for handling key scanning, input processing, behaviors (layers, combos, macros), BLE/USB HID, displays, split-keyboard support, and hardware integration via devicetree overlays.

##### High‐Level Architecture Components
a. Hardware / Boards
- Physical MCU boards (nRF52840, RP2040, etc.) described by devicetree overlays and board files under app/boards.
- Shields / interconnects that extend or split keyboards (app/boards/shields, app/boards/interconnects).
b. Zephyr RTOS
- Kernel, scheduling, device driver framework underneath ZMK (configured via app/prj.conf, module/zephyr/module.yml).
c. ZMK Core (app/src, app/include)
- Input subsystem: kscan drivers → event_manager → behaviors → keymap.
- Output subsystem: usb.c (USB HID) and ble.c (Bluetooth Low Energy HID).
- Subsystems: backlight, underglow, display (app/src/display), split (app/src/split), studio RPC (app/src/studio).
- Settings persistence and reset handlers (app/src/settings).
- Event definitions and handlers (app/src/events, include/zmk/events).
d. ZMK Modules (app/module)
- Device‐specific drivers (GPIO expanders, displays, sensors in module/drivers).
- DTS bindings for custom peripherals (module/dts/bindings).
- Build hooks and Kconfig fragments to integrate into Zephyr build.
e. Keymap Modules (app/keymap-module)
- Provide a Zephyr module that lets end users drop in custom keymaps as overlays.
f. Build System / Configuration
- CMakeLists.txt and Kconfig files across app/, module/, keymap-module/.
- West (app/west.yml) for managing Zephyr and module dependencies.
g. Tests & CI
- Native POSIX “board” (app/boards/native_posix_64) to run automated tests under app/tests.
- CI workflows (.github/workflows) driving build, test, doc checks.
h. Documentation & Frontend
- Docs site (docs/) built with Docusaurus, separate from firmware.

##### Relationships & Data Flow
- Key press → kscan driver (Zephyr) → ZMK event_manager → behavior processing → HID report generator → Transport (USB or BLE).
- Devicetree overlays and Kconfig feed into Zephyr build; application code & modules compile down to a single firmware image.
- Split keyboards: central vs. peripheral code communicate over BLE or other interconnect.
- Status: ZMK display subsystem → driver (module/drivers/display) → e-ink screens.
- CI pipelines trigger builds for boards, run native tests, deploy docs.

##### Architectural Patterns & Principles
- Layered architecture: Hardware → RTOS → Middleware (ZMK core) → Application (behaviors, keymaps).
- Modular plugin pattern: device drivers and keymaps are added as Zephyr modules.
- Event‐driven design: input, behaviors, transport all communicate via events and queues.
- Use of devicetree (DTS) for hardware abstraction.
- Kconfig for compile‐time feature selection.

##### Practical Steps
1. Sketch base layers horizontally.
4. Use rounded rectangles for Zephyr subsystems and ZMK subsystems.
5. Callouts for module plug-points and board overlays.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Layer
    subgraph "Application Layer"
        KM["Keymap Modules"]:::modules
    end

    %% ZMK Core Layer
    subgraph "ZMK Core" 
        EM["Event Manager"]:::core
        BE["Behaviors"]:::core
        KSB["Keyscan Sideband"]:::core
        USB["USB HID"]:::core
        BLE["BLE HID"]:::core
        BACK["Backlight"]:::core
        DISP["Display"]:::core
        SPLIT["Split Support"]:::core
        STUDIO["Studio RPC"]:::core
        SETT["Settings"]:::core
        EVTSRC["Event Sources"]:::core
        EVTPUB["Public Event Types"]:::core
    end

    %% ZMK Modules
    subgraph "ZMK Modules"
        MODDRV["Device Drivers"]:::modules
        MODDTS["DTS Bindings"]:::modules
        MODHOOK["Module Build Hooks"]:::modules
    end

    %% Build System
    subgraph "Build System"
        CMAKE_APP["app/CMakeLists.txt"]:::modules
        KCONF_APP["app/Kconfig"]:::modules
        PRJCONF["app/prj.conf"]:::rtos
        MODMOD["module/zephyr/module.yml"]:::modules
        WEST["app/west.yml"]:::modules
    end

    %% Zephyr RTOS Layer
    subgraph "Zephyr RTOS"
        KERNEL["Kernel & Drivers"]:::rtos
        DTS["Devicetree Overlays"]:::rtos
        PRJCONF
    end

    %% Hardware Layer
    subgraph "Hardware"
        BOARDS["Boards"]:::hardware
        SHIELDS["Shields"]:::hardware
        INTERCON["Interconnects"]:::hardware
    end

    %% CI & Tests
    subgraph "CI & Tests & Docs"
        POSIX["Native POSIX Board"]:::ci
        TESTS["Automated Tests"]:::ci
        CIWF["CI Workflows"]:::ci
        DOCS["Documentation Site"]:::ci
        DOCSRC["Docs Source"]:::ci
    end

    %% Runtime Data Flow
    BOARDS --> KSB
    KSB --> EM
    EM --> BE
    BE --> USB
    BE --> BLE

    %% Build-time Integration
    BOARDS --> DTS
    SHIELDS --> DTS
    INTERCON --> DTS
    DTS --> KERNEL
    PRJCONF --> KERNEL
    CMAKE_APP --> KERNEL
    KCONF_APP --> KERNEL
    WEST --> KERNEL
    MODMOD --> KERNEL
    MODDRV --> KERNEL
    MODDTS --> DTS
    MODHOOK --> KERNEL
    KM --> DTS
    KM --> KERNEL

    %% ZMK Core Subsystems
    EM --> EVTSRC
    EM --> EVTPUB
    EM --> BE
    EM --> SETT
    EM --> STUDIO
    EM --> SPLIT
    EM --> DISP
    EM --> BACK

    %% CI
    CIWF --> POSIX
    POSIX --> TESTS
    CIWF --> DOCS
    DOCS --> DOCSRC

    %% Click Events
    click BOARDS "https://github.com/keychron/zmk/tree/main/app/boards"
    click SHIELDS "https://github.com/keychron/zmk/tree/main/app/boards/shields"
    click INTERCON "https://github.com/keychron/zmk/tree/main/app/boards/interconnects"
    click PRJCONF "https://github.com/keychron/zmk/blob/main/app/prj.conf"
    click MODMOD "https://github.com/keychron/zmk/blob/main/module/zephyr/module.yml"
    click CMAKE_APP "https://github.com/keychron/zmk/blob/main/app/CMakeLists.txt"
    click KCONF_APP "https://github.com/keychron/zmk/tree/main/app/Kconfig"
    click WEST "https://github.com/keychron/zmk/blob/main/app/west.yml"
    click EM "https://github.com/keychron/zmk/blob/main/app/src/event_manager.c"
    click BE "https://github.com/keychron/zmk/blob/main/app/src/behavior.c"
    click BE "https://github.com/keychron/zmk/blob/main/app/src/behavior_queue.c"
    click KSB "https://github.com/keychron/zmk/blob/main/app/src/kscan_sideband_behaviors.c"
    click MODDRV "https://github.com/keychron/zmk/tree/main/app/module/drivers/"
    click MODDTS "https://github.com/keychron/zmk/tree/main/app/module/dts/bindings/"
    click MODHOOK "https://github.com/keychron/zmk/blob/main/app/module/CMakeLists.txt"
    click MODHOOK "https://github.com/keychron/zmk/tree/main/app/module/Kconfig"
    click KM "https://github.com/keychron/zmk/blob/main/app/keymap-module/zephyr/module.yml"
    click TESTS "https://github.com/keychron/zmk/tree/main/app/tests/"
    click POSIX "https://github.com/keychron/zmk/tree/main/app/boards/native_posix_64"
    click CIWF "https://github.com/keychron/zmk/tree/main/.github/workflows/"
    click DOCSRC "https://github.com/keychron/zmk/tree/main/docs/src/"

    %% Styles
    classDef hardware fill:#dddddd,stroke:#888888
    classDef rtos fill:#aed6f1,stroke:#5499c7
    classDef core fill:#a9dfbf,stroke:#27ae60
    classDef modules fill:#f9e79f,stroke:#d4ac0d
    classDef ci fill:#d7bde2,stroke:#8e44ad
```
