# am-zed/kbd_firmware architecture

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

- Interactive diagram: https://gitdiagram.com/am-zed/kbd_firmware
- Repository: https://github.com/am-zed/kbd_firmware

## Overview

1. This repository is a split-keyboard firmware project for the Corne/crkbd, built on QMK with a Vial-enabled fork alongside a plain QMK build. The core architectural boundary is between upstream firmware code and this repo’s keyboard-specific overlays, keymaps, and feature headers.

2. The repo is organized around two firmware variants:
   - `keyboards/crkbd/qmk/qmk_firmware` for a standard QMK build
   - `keyboards/crkbd/vial-kb/vial-qmk` for the Vial runtime-configurable build  
   Both sit on top of vendor firmware submodules and contain only the project-specific keyboard definition, keymaps, and custom behavior.

3. The build boundary is managed from the repo root with `Makefile` plus the QMK toolchain. Build outputs are checked in under `.build` as firmware artifacts such as `.hex` and `.uf2`, which indicates the firmware is intended to be compiled externally and then flashed onto the keyboard controller.

4. Hardware-wise, the target is a split Corne board revision (`rev4_1`) with a left master half, TRRS serial split communication, and pin-based handedness detection. The firmware also assumes per-key RGB on 46 LEDs total, so the hardware layer includes both matrix scanning and LED control as first-class concerns.

5. The input pipeline starts at the physical matrix scan, then flows through QMK’s split transport and into the keymap logic. Project code then intercepts events in the custom keymap layer to implement macros, Unicode typing, swap-hands behavior, sentence case, smart backspace, and other behaviors before final USB HID events are sent to the host.

6. The main behavior surface is the layered keymap. The README describes eight layers: base, navigation, function/RGB, symbols, mouse, macros, ErgoArabic, and RGB control. Tri-layer logic turns the symbols/adjust layer on when the navigation and function layers are both active, and layer lock can hold a layer without continuous key pressure.

7. The Vial build adds a runtime configuration boundary. Files like `keymap.json` and `vial.json` define what the Vial GUI can edit, while `rules.mk` and the Vial-specific keymap structure enable features such as dynamic macros and live key remapping without reflashing firmware.

8. Custom command behavior is centralized in the feature headers under `features/` in the Vial tree. The important ones are leader-key handling, custom keycodes, smart backspace, RGB matrix behavior, pin/layout definitions, and modifier-layer helpers. These headers are the main extension points that turn a stock keymap into a feature-rich firmware.

9. The leader-key system is a separate command layer on top of normal typing. A leader sequence can trigger host shortcuts, text insertion, bootloader entry, or layer changes. Architecturally, this is a firmware-side command router that maps short chorded sequences to higher-level actions.

10. Unicode and Arabic support form a distinct typing subsystem. The ErgoArabic layer maps keys to Arabic letters, diacritics, and punctuation, while Unicode mode selection adapts output for Linux, Windows, WinCompose, or macOS-style input methods. This means the firmware is responsible not just for keycodes, but for host-specific text entry workflows.

11. RGB lighting is both a status channel and an effect engine. `rgb_matrix.h` and related helpers drive per-layer LED indicators, caps-lock state, reactive typing effects, suspend behavior, and brightness control. In the architecture diagram, this should be shown as a parallel output path from firmware state to the keyboard’s LED matrix.

12. The `lib/` directory in the QMK tree contains support utilities such as readers and loggers for layer state, host LED state, RGB state, timing, and key logging. These act as shared presentation helpers for firmware status features, separate from the keymap logic itself.

13. Overall, the system has three main external interaction points: the host computer over USB HID, the split-half link over serial/TRRS, and the configuration/build toolchain via QMK and Vial. The repo’s architecture is therefore a layered firmware stack: upstream firmware base, keyboard board support, custom feature modules, keymaps, and generated binaries.

Main entry points: [`keyboards/crkbd/vial-kb/vial-qmk`](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk) (Vial tree), [`keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c`](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c) (Vial keymap), [`keyboards/crkbd/qmk/qmk_firmware`](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware) (QMK tree), [`Makefile`](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/Makefile) (Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo root"]
  node_makefile["Makefile<br/>build entry"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_qmk_build[("Firmware bins<br/>artifacts<br/>[.build]")]
end

subgraph group_qmk["QMK build"]
  node_qmk_fw["QMK tree<br/>firmware subtree"]
  node_qmk_keymap["Default keymap<br/>[keymap.c]"]
  node_qmk_crkbd["Board code<br/>board glue<br/>[crkbd.c]"]
end

subgraph group_vial["Vial build"]
  node_vial_fw["Vial tree<br/>vial firmware subtree"]
  node_vial_keymap["Vial keymap<br/>runtime keymap<br/>[keymap.c]"]
  node_vial_rules["Vial rules<br/>build config<br/>[rules.mk]"]
  node_vial_json["Vial schema<br/>runtime config<br/>[vial.json]"]
  node_vial_keymap_json["Keymap data<br/>layout config<br/>[keymap.json]"]
end

subgraph group_hardware["Hardware support"]
  node_qmk_rev4["rev4_1 defs<br/>board config"]
  node_qmk_standard["Standard rev<br/>variant config<br/>[keyboard.json]"]
  node_split_link(("Split link<br/>serial transport"))
end

subgraph group_features["Feature modules"]
  node_qmk_lib["Support lib<br/>status helpers"]
  node_vial_features["Feature headers<br/>feature modules"]
  node_vial_rgb_inc["RGB hooks<br/>led hooks"]
end

node_host(("USB host<br/>external host"))

node_makefile -->|"builds"| node_qmk_fw
node_makefile -->|"builds"| node_vial_fw
node_readme -.->|"documents"| node_makefile
node_qmk_fw -->|"contains"| node_qmk_crkbd
node_qmk_fw -->|"contains"| node_qmk_keymap
node_qmk_fw -->|"targets"| node_qmk_rev4
node_qmk_rev4 -->|"uses"| node_split_link
node_qmk_rev4 -->|"defines"| node_qmk_standard
node_qmk_keymap -->|"uses"| node_qmk_lib
node_qmk_keymap -->|"reports to"| node_host
node_qmk_lib -->|"observes"| node_host
node_qmk_build -.->|"produced by"| node_makefile
node_vial_fw -->|"contains"| node_vial_keymap
node_vial_fw -->|"contains"| node_vial_rules
node_vial_fw -->|"contains"| node_vial_json
node_vial_fw -->|"contains"| node_vial_keymap_json
node_vial_fw -->|"contains"| node_vial_features
node_vial_fw -->|"contains"| node_vial_rgb_inc
node_vial_features -->|"types to"| node_host
node_vial_features -->|"uses"| node_split_link
node_vial_keymap -->|"includes"| node_vial_features
node_vial_keymap -->|"reports to"| node_host
node_vial_rgb_inc -->|"indicates"| node_host
node_vial_json -.->|"describes"| node_vial_keymap
node_vial_keymap_json -.->|"describes"| node_vial_keymap

click node_makefile "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/Makefile"
click node_readme "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/README.md"
click node_qmk_fw "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware"
click node_qmk_keymap "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/keymaps/default/keymap.c"
click node_qmk_crkbd "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/crkbd.c"
click node_qmk_rev4 "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/rev4_1"
click node_qmk_standard "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/rev4_1/standard/keyboard.json"
click node_qmk_lib "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/lib"
click node_qmk_build "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/.build"
click node_vial_fw "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk"
click node_vial_keymap "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c"
click node_vial_rules "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rules.mk"
click node_vial_json "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/vial.json"
click node_vial_keymap_json "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.json"
click node_vial_features "https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/features"
click node_vial_rgb_inc "https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rgb_matrix_user.inc"

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_makefile,node_readme,node_qmk_build toneBlue
class node_qmk_fw,node_qmk_keymap,node_qmk_crkbd toneAmber
class node_vial_fw,node_vial_keymap,node_vial_rules,node_vial_json,node_vial_keymap_json toneMint
class node_qmk_rev4,node_qmk_standard,node_split_link toneRose
class node_qmk_lib,node_vial_features,node_vial_rgb_inc toneIndigo
class node_host toneNeutral
```

## Components

### Repo root

Build entry points and top-level documentation

- [Makefile](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/Makefile): build entry · Top-level build entry that drives firmware compilation · `Makefile`
- [README](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/README.md): docs · Project overview and build/usage guidance · `README.md`
- [Firmware bins](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/.build): artifacts · Checked-in build outputs such as HEX and UF2 images · `keyboards/crkbd/qmk/qmk_firmware/.build`

### QMK build

Plain QMK firmware subtree for the Corne board

- [QMK tree](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware): firmware subtree · Plain QMK firmware fork for the Corne board · `keyboards/crkbd/qmk/qmk_firmware`
- [Default keymap](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/keymaps/default/keymap.c): keymap · Main QMK keymap implementation · `keyboards/crkbd/qmk/qmk_firmware/keymaps/default/keymap.c`
- [Board code](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/crkbd.c): board glue · Keyboard-specific board integration code · `keyboards/crkbd/qmk/qmk_firmware/crkbd.c`

### Vial build

Vial-enabled firmware subtree with runtime configuration

- [Vial tree](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk): vial firmware subtree · Vial-enabled QMK fork for runtime-configurable firmware · `keyboards/crkbd/vial-kb/vial-qmk`
- [Vial keymap](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c): runtime keymap · Vial keymap implementation with live remapping support · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c`
- [Vial rules](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rules.mk): build config · Feature flags and build settings for the Vial keymap · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rules.mk`
- [Vial schema](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/vial.json): runtime config · Metadata consumed by the Vial GUI for editable behavior · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/vial.json`
- [Keymap data](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.json): layout config · Editable keymap layout and feature metadata for Vial · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.json`

### Hardware support

Board revision and split-transport hardware definitions

- [rev4_1 defs](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/rev4_1): board config · Corne rev4_1 hardware configuration and post-config hooks · `keyboards/crkbd/qmk/qmk_firmware/rev4_1`
- [Standard rev](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/rev4_1/standard/keyboard.json): variant config · Standard firmware variant metadata for the rev4_1 board · `keyboards/crkbd/qmk/qmk_firmware/rev4_1/standard/keyboard.json`
- **Split link**: serial transport · TRRS/serial communication between keyboard halves

### Feature modules

Reusable behavior and UI helpers inside the firmware trees

- [Support lib](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/qmk/qmk_firmware/lib): status helpers · Shared readers and loggers for layers, host LEDs, RGB, timing, and key logging · `keyboards/crkbd/qmk/qmk_firmware/lib`
- [Feature headers](https://github.com/am-zed/kbd_firmware/tree/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/features): feature modules · Custom behavior headers that extend the Vial keymap · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/features`
- [RGB hooks](https://github.com/am-zed/kbd_firmware/blob/keebart_vial_corne4146k/keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rgb_matrix_user.inc): led hooks · RGB matrix user hook implementation for the Vial build · `keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rgb_matrix_user.inc`

### Other components

- **USB host**: external host · Computer receiving HID reports and text input from the firmware

## Connections

- Makefile → QMK tree: builds · Invokes the plain QMK firmware build
- Makefile → Vial tree: builds · Invokes the Vial-enabled firmware build
- README → Makefile: documents · Explains build and flashing workflow
- QMK tree → Board code: contains · Keyboard-specific board integration
- QMK tree → Default keymap: contains · Default keymap implementation
- QMK tree → rev4_1 defs: targets · Board revision hardware configuration
- rev4_1 defs → Split link: uses · Split transport and handedness behavior
- rev4_1 defs → Standard rev: defines · Standard rev4_1 variant metadata
- Default keymap → Support lib: uses · Shares firmware state readers and loggers
- Default keymap → USB host: reports to · Sends HID output and typing events
- Support lib → USB host: observes · Reads host LED and state feedback
- Firmware bins → Makefile: produced by · Checked-in compiled firmware artifacts
- Vial tree → Vial keymap: contains · Runtime-configurable keymap implementation
- Vial tree → Vial rules: contains · Build flags for the Vial variant
- Vial tree → Vial schema: contains · Vial runtime configuration schema
- Vial tree → Keymap data: contains · Editable keymap metadata and layout
- Vial tree → Feature headers: contains · Project-specific behavior extensions
- Vial tree → RGB hooks: contains · RGB user hook integration
- Feature headers → USB host: types to · Implements host-facing typing and command behaviors
- Feature headers → Split link: uses · Relies on split hardware definitions and matrix pins
- Vial keymap → Feature headers: includes · Pulls in custom command and behavior headers
- Vial keymap → USB host: reports to · Sends HID output and text entry
- RGB hooks → USB host: indicates · Drives LED state and effects as status output
- Vial schema → Vial keymap: describes · Exposes runtime-editable behaviors to Vial GUI
- Keymap data → Vial keymap: describes · Defines the editable keymap surface
