# kellman88/adv360-pro-zmk architecture

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

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

## Overview

This project is a configuration repository for the Kinesis Advantage 360 Pro firmware – a customized fork of the ZMK keyboard firmware. Its primary purpose is to provide board-specific keymap configurations and device settings (like RGB effects, NKRO, battery reporting, etc.), along with build automation and firmware packaging for a split keyboard (left/right modules). The repository integrates a local build system and GitHub Actions for continuous integration, and it also links to an external web GUI for editing keymaps.

##### Main Components
- Build & Automation Layer: Show the Makefile execution and Dockerfile usage supported by scripts in the ‘bin’ directory. GitHub workflows (in .github/workflows) serve as the cloud-based CI/CD environment.
- Firmware Artifacts: Indicate where compiled output is stored (the ‘firmware’ directory) and how the binaries (for left and right modules) are produced from the configuration.
- External Interfaces & Documentation: Include the web-based GUI (for keymap editing) and related external documentation resources from Kinesis and ZMK. Also represent support interfaces like upgrade documents (UPGRADE.md) and changelogs.
- Versioning & Update Process: Emphasize the integration of version tracking (e.g., Git commit hash, build timestamp) as described in the README, and how users are guided to upgrade firmware.

##### Relationships & Data Flow
- External user interactions: the GUI for keymap editing and the instructions for flashing (which include bootloader modes and USB flashing) as separate nodes communicating with the firmware output.

##### Architectural Patterns & Design Principles
- Modular Design: Separate directories indicate clear separation of concerns – configuration, build scripts, assets, and CI workflows are all isolated into their sections. Each module (left/right firmware, keymap definitions, board configurations) should be distinct.
- CI/CD Integration: Emphasize the GitHub Actions automated build process described in the README, supporting continuous integration practices.
- Containerization: Include the role of Docker (or Podman) and Make for ensuring repeatable builds across environments.
- Versioning: Clearly denote that version metadata (compilation date, branch, commit hash) is embedded into firmware during the build process, reinforcing traceability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Assets"
        Config["Configuration Files (config/)"]:::config
        Assets["Assets (assets/)"]:::config
    end

    subgraph "Build & Automation Layer"
        subgraph "Local Build System (Make & Docker)"
            Makefile["Makefile"]:::buildscript
            Dockerfile["Dockerfile"]:::buildscript
            BuildSh["bin/build.sh"]:::buildscript
            GetVersion["bin/get_version.sh"]:::buildscript
        end
        CI["GitHub Actions CI (.github/workflows/)"]:::ci
    end

    subgraph "Firmware Output"
        Firmware["Firmware Binaries (Left/Right) (firmware/)"]:::firmware
    end

    subgraph "External Interfaces"
        WebGUI["Web GUI Keymap Editor"]:::external
        Flasher["User Flashing Process"]:::external
        Docs["Documentation (README.md, UPGRADE.md, CHANGELOG.md)"]:::external
    end

    %% Data Flow Connections
    Config -->|"config_input"| Makefile
    Assets -->|"assets_input"| Dockerfile
    Config -->|"config_input"| CI
    Assets -->|"assets_input"| CI

    Makefile -->|"builds"| Firmware
    Dockerfile -->|"builds"| Firmware
    BuildSh -->|"runs_build"| Firmware
    GetVersion -->|"injects_version"| Firmware

    CI -->|"cloud_build"| Firmware

    WebGUI -->|"updates_keymap"| Config
    Firmware -->|"flash"| Flasher
    Docs -->|"guides_upgrade"| Flasher

    %% Styles
    classDef config fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef buildscript fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef ci fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef firmware fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:2px;

    %% Click Events
    click Config "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/config/"
    click Assets "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/assets/"
    click Makefile "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/Makefile"
    click Dockerfile "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/Dockerfile"
    click BuildSh "https://github.com/kellman88/adv360-pro-zmk/blob/V3.0/bin/build.sh"
    click GetVersion "https://github.com/kellman88/adv360-pro-zmk/blob/V3.0/bin/get_version.sh"
    click CI "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/.github/workflows/"
    click Firmware "https://github.com/kellman88/adv360-pro-zmk/tree/V3.0/firmware/"
    click Docs "https://github.com/kellman88/adv360-pro-zmk/blob/V3.0/README.md"
```
