# rgoulter/smart-keymap architecture

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

- Interactive diagram: https://gitdiagram.com/rgoulter/smart-keymap
- Repository: https://github.com/rgoulter/smart-keymap

## Overview

1. Allowing developers to declaratively design keymaps using Nickel (via .ncl files) and then having those configurations drive the keyboard firmware.
2. Supporting multiple firmware targets (e.g., RP2040 with RTIC, STM32, CH32X035 USB device, CH58X BLE HID) via both Rust and C toolchains.

##### Main system components
- Smart Keymap Core Library – This is the Rust crate (found in smart_keymap/src, src/, and similar directories) that implements the keymap behavior. It exposes both a native static library (for C firmware projects) and a Rust interface (for Rust-based firmware).
- Nickel Configuration Engine – The project relies on Nickel (.ncl files in directories such as ncl/, tests/ncl/, features/keymap/) to define keymaps. There are also helper scripts and converters (e.g., gherkin2md.awk, keymap-codegen.ncl) that process these configurations.
- Firmware Implementations – There are several firmware sub-projects:
- RP2040-RTIC Smart Keyboard (rp2040-rtic-smart-keyboard): A Rust-based firmware built with RTIC for the RP2040.
- STM32F4-RTIC Smart Keyboard (stm32f4-rtic-smart-keyboard): Also Rust-based, targeting STM32.
- CH32X035 USB HID Keyboard (firmware/ch32x035-usb-device-compositekm-c): A C/CMake project for CH32X035.
- CH58X BLE HID Keyboard (firmware/ch58x-ble-hid-keyboard-c): Another C/CMake project tailored for BLE HID.
- Platform Toolchain and Build Environment – This includes configuration files for Cargo, CMake (in the SDK directories), Makefiles, and DevEnv (devenv.yaml, devenv.nix) as well as CI/CD workflows (.github/workflows) that automate testing/building.

##### Relationships and interactions
- The developer writes a keymap in Nickel. This configuration flows into the keymap generation layer (via scripts and NCL tools), producing representations (e.g., JSON or Rust source) usable by the Smart Keymap library.
- The Smart Keymap Library acts as a core module offering key processing functionality.
- Firmware projects on different hardware target platforms integrate the Smart Keymap Library – either linking it as a static library (for C firmware) or as a Rust dependency (for RTIC-based projects).
- The configuration and conversion tools (in ncl/ and features/) work as an intermediate layer between raw Nickel definitions and the final firmware build.
- Testing and CI/CD resources ensure that keymaps (both in Nickel and generated source) are validated through a suite of tests (located in tests/).

##### Important architectural patterns/principles
- Separation of concerns: The project clearly decouples keymap configuration (Nickel + NCL scripts) from firmware implementations (Rust RTIC, C firmware projects).
- Modularity and reusability: The core library (smart-keymap) is designed to be used as a standalone crate or static library, enabling re-use across multiple platforms.
- Cross-language interoperability: With components in Rust and C (with cbindgen assisting in header generation), the design promotes integration with various firmware ecosystems.
- Layered architecture: The “input” from the keyboard (configuration and runtime scanning) is processed by the core keymap engine, then handed off to firmware-specific driver layers that interact with the hardware.

##### Relevant technologies/frameworks
- Rust (with Cargo, build.rs, and the RTIC framework for real-time interrupt handling)
- C/CMake for several firmware projects and peripheral SDKs
- Nickel configuration (and its associated tooling)
- DevEnv (for environment and dependency management)
- GitHub Actions (CI/CD workflows defined in the .github/workflows directory)
- Makefile and justfile scripts for building and deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        NC["Nickel Keymap Config & NCL Scripts"]:::config
    end

    subgraph "Core Processing Layer"
        SKCL["Smart Keymap Core Library (Rust & Static Lib)"]:::rust
    end

    subgraph "Firmware Implementations"
        RP["RP2040 RTIC Firmware"]:::rust
        STM["STM32 RTIC Firmware"]:::rust
        CHUSB["CH32X035 USB HID Firmware"]:::cfirmware
        CHBLE["CH58X BLE HID Firmware"]:::cfirmware
    end

    subgraph "Build & Validation"
        TOOLS["Toolchain/Build Environment"]:::build
        CI["CI/CD & Testing"]:::ci
    end

    NC -->|"generates_config"| SKCL
    SKCL -->|"integrates"| RP
    SKCL -->|"integrates"| STM
    SKCL -->|"integrates"| CHUSB
    SKCL -->|"integrates"| CHBLE

    TOOLS -->|"builds"| RP
    TOOLS -->|"builds"| STM
    TOOLS -->|"builds"| CHUSB
    TOOLS -->|"builds"| CHBLE

    CI -->|"tests"| SKCL
    CI -->|"tests"| NC

    %% Click Events
    click SKCL "https://github.com/rgoulter/smart-keymap/blob/master/smart_keymap/src/lib.rs"
    click SKCL "https://github.com/rgoulter/smart-keymap/blob/master/src/lib.rs"
    click NC "https://github.com/rgoulter/smart-keymap/tree/master/ncl/"
    click NC "https://github.com/rgoulter/smart-keymap/tree/master/features/keymap/ncl/"
    click RP "https://github.com/rgoulter/smart-keymap/tree/master/rp2040-rtic-smart-keyboard/"
    click STM "https://github.com/rgoulter/smart-keymap/tree/master/stm32f4-rtic-smart-keyboard/"
    click CHUSB "https://github.com/rgoulter/smart-keymap/tree/master/firmware/ch32x035-usb-device-compositekm-c/"
    click CHBLE "https://github.com/rgoulter/smart-keymap/tree/master/firmware/ch58x-ble-hid-keyboard-c/"
    click TOOLS "https://github.com/rgoulter/smart-keymap/tree/master/.github/workflows/"
    click TOOLS "https://github.com/rgoulter/smart-keymap/blob/master/devenv.yaml"
    click TOOLS "https://github.com/rgoulter/smart-keymap/blob/master/devenv.nix"
    click TOOLS "https://github.com/rgoulter/smart-keymap/blob/master/Cargo.toml"
    click TOOLS "https://github.com/rgoulter/smart-keymap/tree/master/Makefile"
    click TOOLS "https://github.com/rgoulter/smart-keymap/tree/master/firmware/toolchains/"
    click CI "https://github.com/rgoulter/smart-keymap/tree/master/tests/"
    click CI "https://github.com/rgoulter/smart-keymap/tree/master/.github/workflows/"

    %% Styles
    classDef rust fill:#a0d2eb,stroke:#333,stroke-width:2px;
    classDef cfirmware fill:#b8e2a8,stroke:#333,stroke-width:2px;
    classDef config fill:#fff79a,stroke:#333,stroke-width:2px;
    classDef build fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef ci fill:#f4a8a8,stroke:#333,stroke-width:2px;
```
