# dreamy-jy/rmk architecture

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

- Interactive diagram: https://gitdiagram.com/dreamy-jy/rmk
- Repository: https://github.com/dreamy-jy/rmk

## Overview

##### Project type and purpose
- This is a multi-crate Rust firmware project (“rmk”) for building feature-rich keyboard firmware on a variety of microcontrollers.
- It includes:
- A core firmware library (rmk)
- A configuration-generation tool (rmk-config)
- A procedural-macro crate (rmk-macro)
- A shared-types crate (rmk-types)
- Dozens of example applications (one per MCU family)
- Documentation site (VitePress under docs/)
- CI/CD workflows and helper scripts

##### File-structure analysis
- Top-level crates & folders:
- rmk-config (CPU-agnostic TOML → Rust code generator)
- rmk-macro (proc macros to wire up drivers, matrix, USB/BLE stacks)
- rmk-types (common enums/structs: keycodes, protocols)
- rmk (core runtime: matrix scanning, debouncing, layers, host protocols)
- examples/… (each example is a Cargo project targeting a specific MCU)
- docs/ (VitePress site source + theme)
- .github/workflows/ (CI: build, test, lint, docs deploy)
- scripts/ (automation: check_all, clean_all, via2rmk.py)
- rmk Cargo workspace: shared toolchain, rustfmt, build.rs scripts that invoke codegen or embed build metadata.

##### Key README insights
- Supports broad MCU families via Embassy + embedded-HAL
- Native Vial support (wireless keymap editing) over BLE or USB HID
- Advanced keyboard features baked in (layers, combos, mouse, media)
- Build is driven by a single keyboard.toml, or extended via Rust code

1. Developer tools
– keyboard.toml + Cargo project
– rmk-config CLI (codegen)
– rmk-macro (proc macro expansion)
2. Build system & CI/CD
– Cargo workspace
– build.rs scripts
– GitHub Actions + scripts/
3. Crate dependency graph
– rmk-types → rmk → examples
– rmk-macro → rmk (compile-time only)
– rmk-config → examples (codegen)
4. Generated firmware
– Monolithic binary per example
5. Runtime modules (inside rmk)
– Matrix scanning → Debouncer → Keymap → Controller → HID over USB or BLE
– Async executor (embassy)
– Storage (flash) / lighting / wireless reconnection
6. Hardware & external systems
– MCU (GPIO, ADC, SPI, USB peripheral, BLE radio)
– Host PC or mobile (USB HID host, Vial host over BLE)

– keyboard.toml  → rmk-config  → generated Rust modules → Cargo build
– Cargo build invokes rmk-macro (proc macros) → expands to driver/stack code
– Build.rs scripts (per crate) may embed metadata or call codegen
– Final binary flashes to MCU
– At runtime:
- Keyboard matrix → rmk matrix scanner
- Debounced events → keymap lookup → HID events
- HID events → USB endpoint or BLE GATT → Host
- Host → Vial UI (optional wireless keymap updates)

c. Architectural patterns & design principles
– Cargo workspace for multi-crate modularity
– Code-first configuration with TOML + codegen
– Compile-time macros for zero-cost abstractions
– Feature flags per MCU & per capability (async_matrix, wireless)
– Clear separation: hardware drivers, core logic, host protocol

d. Key technologies & frameworks
– Rust, Cargo, Proc‐Macros, build.rs
– embassy (async runtime)
– embedded‐HAL drivers
– usb‐device, Bluetooth GATT stacks
– VitePress for docs
– GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compile-time Pipeline
    subgraph "Compile-time Pipeline"
        direction TB
        Toml["keyboard.toml"]:::tools
        RmkConfig["rmk-config (codegen)"]:::tools
        GenRust["Generated Rust modules"]:::tools
        CargoBuild["Cargo build"]:::tools
        BuildRs["build.rs scripts"]:::tools
        RmkMacro["rmk-macro (proc macros)"]:::tools
    end

    Toml -->|"input"| RmkConfig
    RmkConfig -->|"codegen"| GenRust
    GenRust -->|"compilation"| CargoBuild
    CargoBuild --> BuildRs
    CargoBuild --> RmkMacro

    %% Build System & CI/CD
    subgraph "Build System & CI/CD"
        direction TB
        Workspace["Cargo workspace"]:::tools
        GHActions["GitHub Actions"]:::external
        Scripts["scripts/"]:::external
    end

    CargoBuild --> Workspace
    Workspace --> GHActions
    Workspace --> Scripts

    %% Crate Dependency Graph
    subgraph "Crate Dependency Graph"
        direction TB
        RmkTypes["rmk-types"]:::crates
        RmkCore["rmk (core)"]:::crates
        Examples["examples/"]:::crates
    end

    RmkTypes --> RmkCore
    RmkCore --> Examples
    RmkMacro --> RmkCore
    RmkConfig --> Examples

    %% Generated Firmware
    subgraph "Generated Firmware"
        direction TB
        FinalBin["Final binary"]:::runtime
    end

    Examples --> FinalBin

    %% Runtime Modules
    subgraph "Runtime Modules (rmk)"
        direction TB
        Matrix["Matrix scanning"]:::runtime
        Debouncer["Debouncer"]:::runtime
        Keymap["Keymap lookup"]:::runtime
        Controller["Controller"]:::runtime
        HIDUSB["USB HID stack"]:::runtime
        HIDBLE["BLE GATT stack"]:::runtime
        AsyncExec["Async executor (embassy)"]:::runtime
        Storage["Storage/Flash, Lighting, Wireless"]:::runtime
    end

    FinalBin --> Matrix
    Matrix --> Debouncer
    Debouncer --> Keymap
    Keymap --> Controller
    Controller --> HIDUSB
    Controller --> HIDBLE
    Matrix --> AsyncExec
    Controller --> Storage

    %% Hardware & External Systems
    subgraph "Hardware & External"
        direction TB
        MCU["MCU (GPIO, ADC, SPI, USB, BLE)"]:::external
        HostPC["Host PC (USB HID host)"]:::external
        VialApp["Vial UI (BLE)"]:::external
        Docs["docs/ (VitePress)"]:::external
    end

    FinalBin -->|"flash"| MCU
    HIDUSB -->|"USB HID"| HostPC
    HIDBLE -->|"BLE GATT"| HostPC
    HIDBLE -->|"Vial updates"| VialApp

    %% Legend
    subgraph "Legend"
        direction TB
        A["Developer/Build Tools"]:::tools
        B["Library Crates"]:::crates
        C["Runtime Modules"]:::runtime
        D["Hardware/External"]:::external
    end

    %% Click Events
    click RmkConfig "https://github.com/dreamy-jy/rmk/tree/main/rmk-config/"
    click RmkMacro "https://github.com/dreamy-jy/rmk/tree/main/rmk-macro/"
    click RmkTypes "https://github.com/dreamy-jy/rmk/tree/main/rmk-types/"
    click RmkCore "https://github.com/dreamy-jy/rmk/tree/main/rmk/"
    click Examples "https://github.com/dreamy-jy/rmk/tree/main/examples/"
    click Docs "https://github.com/dreamy-jy/rmk/tree/main/docs/"
    click GHActions "https://github.com/dreamy-jy/rmk/tree/main/.github/workflows/"
    click Scripts "https://github.com/dreamy-jy/rmk/tree/main/scripts/"

    %% Styles
    classDef tools fill:#D0E8FF,stroke:#004080,stroke-width:1px
    classDef crates fill:#D0FFD0,stroke:#006600,stroke-width:1px
    classDef runtime fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px
```
