# kinesiscorporation/adv360-pro-zmk architecture

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

- Interactive diagram: https://gitdiagram.com/kinesiscorporation/adv360-pro-zmk
- Repository: https://github.com/kinesiscorporation/adv360-pro-zmk

## Overview

##### Project type and purpose
- This repository is a firmware‐configuration project for the Kinesis Advantage 360 Pro keyboard, built on top of a custom ZMK fork.  It is not a web or mobile app but a specialized build‐system for generating and packaging keyboard firmware for two halves (left/right).

##### File structure
- Top level:
– Dockerfile & Makefile: define a reproducible containerized build environment.
– bin/: helper scripts (build.sh, get_version.sh).
– config/: all board definitions, keymaps, Kconfig, device trees, west manifest.
– firmware/: output directory for compiled .uf2 files.
– .github/workflows/build.yml: CI pipeline definition.
- config/boards/arm/adv360/: detailed hardware description (Kconfig, dts, yaml).
- config/west.yml: points to the custom ZMK fork and any external repositories.

##### Extract insights from the README
- Two build modes: cloud (GitHub Actions) and local (Docker/Podman + Make).
- Build produces timestamped artifacts (left.uf2, right.uf2).
- Flashing process targets physical USB‐mountable bootloader on each keyboard half.

##### Main components
a. Source Repositories & Editors
- Developer’s local clone / web GUI (keymap editor)
- GitHub repo (this config repo)
- External upstream ZMK fork (ReFil’s adv360‐z3.5) & base ZMK
b. Build Infrastructure
- GitHub Actions runner (cloud CI)
- Docker/Podman container (local CI)
- Make & bin/*.sh scripts orchestrating:
– west init/update to fetch ZMK sources
– CMake & Ninja build of firmware for left/right halves
c. Artifacts and Storage
- firmware/ directory in the repo (local builds)
- GitHub Actions artifacts (cloud builds)
d. Hardware Targets
- Left keyboard module (adv360_left.uf2)
- Right keyboard module (adv360_right.uf2)
- USB bootloader interface (drag‑and‑drop .uf2)
e. Documentation & Support
- Quick Start Guide & User Manual (external links)

##### Relationships and data flow
1. Developer edits config/ keymaps (locally or via web GUI).
2. Commit → push to GitHub → triggers CI pipeline.
3. CI or local Make:
– Launch container (Dockerfile) → mount workspace → run bin/build.sh →
– west fetch ZMK sources → CMake configure → Ninja build → produce UF2 files.
4. Build outputs saved to firmware/ and as GitHub Actions artifacts.
5. User flashes UF2 onto each physical half via USB bootloader.

##### Architectural patterns & design principles
- Separation of concerns:
- Configuration (config/) vs build orchestration (Makefile, Dockerfile, bin/) vs output (firmware/).
- CI pipeline isolated from local builds but reuses same container definition.
- Reproducibility:
- Containerized builds ensure identical environments across machines.
- west manifest pins external dependencies.
- Extensibility:
- Additional boards or keymaps can be added under config/boards or config/keymap.json.
- Custom build flags in defconfig files.

##### Final checklist
- Sufficient detail: call out config files (Kconfig, dtsi, defconfig), build scripts, CI workflow.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Source & Repositories
  subgraph "Source & Repositories"
    DEV["Developer / Editor"]:::external
    GUI["Web GUI Keymap Editor"]:::repos
    GitHub["GitHub Repo"]:::repos
    ZMK["Custom ZMK Fork (ReFil’s adv360-z3.5)"]:::external
  end

  DEV -->|git push| GitHub
  GUI -->|edit keymaps| GitHub
  GitHub -->|west init via| west
  west -.->|references| ZMK

  %% Configuration Files
  subgraph "Configuration Files" 
    direction TB
    west["west.yml"]:::repos
    subgraph "Board Definitions (config/boards/arm/adv360)"
      direction TB
      Kconfig["Kconfig"]:::repos
      KconfB["Kconfig.board"]:::repos
      KconfDef["Kconfig.defconfig"]:::repos
      layouts["adv360-layouts.dtsi"]:::repos
      dtsi["adv360.dtsi"]:::repos
      yaml["adv360.yaml"]:::repos
      zmkYml["adv360.zmk.yml"]:::repos
      leftDts["adv360_left.dts"]:::repos
      leftDef["adv360_left_defconfig"]:::repos
      rightDts["adv360_right.dts"]:::repos
      rightDef["adv360_right_defconfig"]:::repos
      boardCmake["board.cmake"]:::repos
      macros["macros.dtsi"]:::repos
      pinctrl["adv360_pinctrl.dtsi"]:::repos
    end
    subgraph "Keymap Configs (config)"
      direction TB
      kmAll["adv360.keymap"]:::repos
      kmLeft["adv360_left.keymap"]:::repos
      kmRight["adv360_right.keymap"]:::repos
      keymapJson["keymap.json"]:::repos
    end
  end

  west --> Kconfig
  west --> kmAll
  Kconfig --> layouts
  kmAll --> boardCmake

  %% Build Infrastructure
  subgraph "Build Infrastructure"
    direction TB
    CI["GitHub Actions Runner"]:::external
    Local["Local Make/Container"]:::build
    Docker["Docker Container"]:::build
    Make["Makefile"]:::build
    BuildSh["bin/build.sh"]:::build
    VerSh["bin/get_version.sh"]:::build
    VerLocal["bin/get_version_local.sh"]:::build
    CMake["CMake & Ninja"]:::build
  end

  GitHub -->|trigger CI| CI
  CI -->|docker run| Docker
  Local -->|docker run| Docker
  Docker -->|mount workspace & run| Make
  Make -->|invoke| BuildSh
  Make -->|invoke| VerSh
  Make -->|invoke| VerLocal
  BuildSh -->|west fetch| west
  BuildSh -->|CMake configure & Ninja build| CMake

  %% Artifacts & Storage
  subgraph "Artifacts & Storage"
    direction TB
    FirmwareDir["firmware/"]:::artifacts
    GHArt["GitHub Actions Artifacts"]:::artifacts
  end

  CMake -->|produce UF2| FirmwareDir
  CI -->|upload| GHArt

  %% Hardware Targets
  subgraph "Hardware Targets"
    direction TB
    LeftKF["Left Keyboard Bootloader"]:::hardware
    RightKF["Right Keyboard Bootloader"]:::hardware
  end

  FirmwareDir -->|copy adv360_left.uf2| LeftKF
  FirmwareDir -->|copy adv360_right.uf2| RightKF

  %% Documentation & Assets
  subgraph "Documentation & Support"
    direction TB
    KeyPos["assets/key-positions.md"]:::docs
    Swatches["assets/swatches"]:::docs
    QuickStart["Quick Start Guide (external)"]:::docs
  end

  KeyPos --> kmAll
  Swatches --> kmAll

  %% CI Pipeline Definition
  GHWF[".github/workflows/build.yml"]:::repos
  GitHub -->|uses workflow| GHWF

  %% Click Events
  click Docker "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/Dockerfile"
  click Make "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/Makefile"
  click BuildSh "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/bin/build.sh"
  click VerSh "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/bin/get_version.sh"
  click VerLocal "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/bin/get_version_local.sh"
  click west "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/west.yml"
  click Kconfig "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/config/boards/arm/adv360/Kconfig"
  click KconfB "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/Kconfig.board"
  click KconfDef "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/Kconfig.defconfig"
  click layouts "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360-layouts.dtsi"
  click dtsi "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360.dtsi"
  click yaml "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360.yaml"
  click zmkYml "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360.zmk.yml"
  click leftDts "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360_left.dts"
  click leftDef "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/config/boards/arm/adv360/adv360_left_defconfig"
  click rightDts "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360_right.dts"
  click rightDef "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/config/boards/arm/adv360/adv360_right_defconfig"
  click boardCmake "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/board.cmake"
  click macros "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/macros.dtsi"
  click pinctrl "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/boards/arm/adv360/adv360_pinctrl.dtsi"
  click kmAll "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/adv360.keymap"
  click kmLeft "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/adv360_left.keymap"
  click kmRight "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/adv360_right.keymap"
  click keymapJson "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/config/keymap.json"
  click GHWF "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/.github/workflows/build.yml"
  click FirmwareDir "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/firmware/"
  click KeyPos "https://github.com/kinesiscorporation/adv360-pro-zmk/blob/V3.0/assets/key-positions.md"
  click Swatches "https://github.com/kinesiscorporation/adv360-pro-zmk/tree/V3.0/assets/swatches"

  %% Styles
  classDef repos fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
  classDef external fill:#FFE8D0,stroke:#DA8C10,color:#DA8C10;
  classDef build fill:#D0FFD8,stroke:#2D662D,color:#2D662D;
  classDef artifacts fill:#FFF3BF,stroke:#BC8A00,color:#BC8A00;
  classDef hardware fill:#E0E0E0,stroke:#606060,color:#606060;
  classDef docs fill:#F0E0FF,stroke:#7D3B7E,color:#7D3B7E;
```
