# anketdhulekar/adv360-pro-zmk architecture

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

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

## Overview

##### Main modules/components
- Source Repository & Configuration:
- The “config” directory holds board configurations (for ARM/adv360) with various DTS, YAML, defconfig files, and board-specific settings.
- Keymap details for both left and right modules are defined here along with other macros and version definitions.
- Build Environment & Automation:
- The Makefile, Dockerfile, and scripts in the “bin” directory indicate the use of a containerized build system (Docker or Podman) to compile the firmware.
- The .github/workflows folder shows GitHub Actions are used to automatically build firmware on commit.
- Firmware Artifacts:
- The “firmware” folder and its contents are where built firmware images (UF2 files) are produced.
- Assets and Documentation:
- Other documents like CHANGELOG.md, README.md, and UPGRADE.md provide project history, usage, and migration instructions.

##### Detail the relationships and interactions
- Developers interact with the repository using either the GitHub interface (forking, pushing commits) or via local container setups, as documented.
- A Separation of concerns exists: configuration files define how the firmware should behave on the hardware, and build scripts/Docker setup compile these configurations into firmware binaries.
- GitHub Actions automate the building process when commits are pushed—this connection should be shown along with how the build artifact is produced and later used.

##### Architectural patterns/design principles
- Modularity: The project clearly separates configuration, build automation, and firmware output. Both physical halves (left and right) feature distinct configuration files, indicating a nearly “two-module” hardware architecture.
- Containerization: The Dockerfile and Makefile show that the build environment is containerized or scripted for consistency, ensuring repeatable builds.
- CI/CD Principle: With GitHub Actions and local build scripts enabling consistent automation and continuous integration.
- Separation of Concerns: Clearly delineated sections between hardware definition (via board configurations), firmware build process, and the user-facing documentation (and external web GUI for key mapping).

##### Relevant technologies and tools
- ZMK firmware and its customized fork.
- Container runtime tools like Docker or Podman.
- Build automation using Make and GitHub Actions (as seen in the workflows).
- Languages/configuration formats such as DTS, YAML, and CMake (for board.cmake) that define hardware and firmware configurations.
- External web-based keymap editor interfaces (i.e., the Kinesis GUI).

- A clear label for each main component: “Repository (Config Files: Keymaps, Board Configs), Build Infrastructure (Docker/Podman with Make/GitHub Actions), Firmware Artifacts (UF2 files), and External Interfaces (Web-based Keymap Editor, Hardware Flashing Process).”
- The build (locally or via CI)
- Then creation of firmware images
- Which are then used to flash the keyboard’s left and right modules.

## Diagram (Mermaid)

```mermaid
graph TD
    Developer["Developer"]:::external
    Repo["Source Repository & Configuration Files"]:::config
    Developer -->|"push_commit"| Repo

    subgraph "Build Infrastructure"
        LB["Local Build Environment"]
        CI["CI/CD Build Environment"]
    end

    subgraph "Local Build Tools"
        M["Makefile"]:::buildTool
        Dfile["Dockerfile"]:::buildTool
        Bin["bin (build.sh, get_version.sh)"]:::buildTool
        M --> LB
        Dfile --> LB
        Bin --> LB
    end

    subgraph "CI/CD Tools"
        GH[".github/workflows (build.yml)"]:::buildTool
        GH --> CI
    end

    Repo -->|"triggers_build"| LB
    Repo -->|"triggers_build"| CI

    LB -->|"builds"| Firmware["Firmware Artifacts (UF2 files)"]:::firmware
    CI -->|"builds"| Firmware

    Firmware -->|"flashes_to"| Left["Left Half Firmware"]:::firmware
    Firmware -->|"flashes_to"| Right["Right Half Firmware"]:::firmware

    Repo -->|"contains"| Assets["Assets & Documentation (assets, README.md, CHANGELOG.md, UPGRADE.md)"]:::docs

    Repo -->|"updated_by"| Editor["Web-based Keymap Editor"]:::external
    Editor --> Repo

    click Repo "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/config"
    click M "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/Makefile"
    click Dfile "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/Dockerfile"
    click Bin "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/bin"
    click GH "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/.github/workflows"
    click Firmware "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/firmware"
    click Assets "https://github.com/anketdhulekar/adv360-pro-zmk/tree/V3.0/assets"

    classDef external fill:#ffd1dc,stroke:#333,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef build fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef buildTool fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef firmware fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef docs fill:#d1ecf1,stroke:#333,stroke-width:2px;
```
