# rokiden/midandpad-dj architecture

> Architecture diagram of the GitHub repository rokiden/midandpad-dj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rokiden/midandpad-dj
- Repository: https://github.com/rokiden/midandpad-dj

## Overview

1. **What this repository is**
   - This is a single-purpose Android app called **Midandpad**, an **MIDI controller for Android**.
   - The repo is centered around one mobile application module (`app`) with no backend service or multi-module architecture.

2. **Top-level system boundary**
   - The application sits entirely on-device: user interaction happens in the app UI, and MIDI output is sent from the phone/tablet to an external MIDI target.
   - There is no evidence of a server, cloud sync, or web layer; the key external boundary is the **Android MIDI ecosystem / connected MIDI device**.

3. **App entry and screen flow**
   - `MainActivity.kt` is the likely Android entry point, with `Splash.kt` as the initial loading/branding screen.
   - The main experience is split across several dedicated screens:
     - `MainScreen.kt` for the primary controller surface
     - `ExploreScreen.kt` for browsing/selecting content or presets
     - `BtnConfigScreen.kt` and `BarConfigScreen.kt` for configuration workflows
     - `TouchCalibration.kt` for input calibration
   - `AndroidManifest.xml` and the XML layouts under `res/layout` define how these screens are launched and arranged.

4. **UI composition**
   - The app appears to use **classic Android XML layouts** rather than a single declarative UI stack.
   - Reusable custom UI pieces are implemented as Kotlin classes such as:
     - `EventButton`, `CalibrationButton`
     - `VerticalSlider`, `CCBar`
     - `NoteRow`, `PresetItem`
     - `PropertiesView`
   - These components are backed by specialized layouts like `button_note.xml`, `button_control.xml`, `button_program.xml`, `button_chord.xml`, `noterow.xml`, and `mixer.xml`.

5. **MIDI generation subsystem**
   - MIDI behavior is concentrated in `MidiHelper.kt`, `MidiConfig.kt`, and `MidiConfig`-related data structures.
   - The app supports multiple MIDI action types, reflected by the config classes:
     - `ButtonNoteCfg`
     - `ButtonControlCfg`
     - `ButtonProgramCfg`
     - `ButtonChordCfg`
   - This suggests the UI maps user gestures to different kinds of MIDI messages: notes, control changes, program changes, and chords.

6. **Configuration model**
   - `ConfigParams.kt` likely holds the shared state and parameters that connect the UI to MIDI behavior.
   - The config screens and custom view classes indicate a two-layer model:
     - screen-specific editing UIs
     - shared configuration/state objects used at runtime
   - `MidiConfig.kt` and the button config classes are the main boundary between “what the user designed” and “what the controller sends”.

7. **Persistence and backup**
   - `MidandpadDB.kt` is the app’s persistence layer for storing configurations/presets.
   - `BackupDatabase.kt` indicates the app can export or restore saved data, which is important for a controller app where users build custom setups.
   - The presence of `res/xml/backup_rules.xml` and `data_extraction_rules.xml` shows Android-managed backup/restore integration is also configured.

8. **Touch and calibration pipeline**
   - `TouchCalibration.kt` and `CalibrationButton.kt` suggest the app includes an explicit calibration workflow for touch mapping.
   - This matters for a MIDI controller UI because button positions, sliders, and pads need predictable touch areas, especially on different screen sizes.
   - Calibration data likely feeds back into the configuration and rendering logic used by the main controller screen.

9. **Main interaction modes**
   - The layouts and classes indicate at least three interaction families:
     - **note/pad triggering** (`NoteRow`, `button_note.xml`)
     - **continuous controls** (`VerticalSlider`, `CCBar`, `button_control.xml`)
     - **program/chord/preset actions** (`ButtonProgramCfg`, `ButtonChordCfg`, `PresetItem`)
   - This implies the main screen is a configurable MIDI surface rather than a fixed instrument UI.

10. **Assets and presentation layer**
    - The app includes many vector drawables for note durations and UI state, plus custom icons and status shapes.
    - Strings are localized in **English and Spanish** (`values/strings.xml`, `values-es/strings.xml`), so the UI is multilingual.
    - Theme, sizes, margins, and custom attrs are centralized in `res/values`, which supports consistent styling across the controller screens.

11. **Build, release, and distribution**
    - The project is built with **Gradle Kotlin DSL** (`build.gradle.kts`, `app/build.gradle.kts`).
    - GitHub Actions workflows (`build-apk.yml`, `build-release-apk.yml`) automate APK generation.
    - `fastlane/metadata` indicates the app is prepared for Play Store-style release metadata and screenshots, so distribution is part of the repo architecture.

12. **Overall data flow**
    - A typical flow is: **user touches a custom control → screen/component uses calibration and config state → MIDI helper constructs the outgoing MIDI event → event is sent to an external MIDI destination**.
    - Configuration changes flow in the opposite direction into persistence: **config screen → database/backup layer → restored on next launch**.

13. **How to diagram it**
    - A good architecture diagram would show:
      - Android app shell / `MainActivity`
      - navigation to the main controller, config screens, calibration, and splash
      - shared config/state layer
      - MIDI message generation layer
      - persistence/backup layer
      - custom reusable UI components feeding the main controller and config screens
      - external MIDI device boundary on the output side

Main entry points: [`app/src/main/java/org/gnu/itsmoroto/midandpad/MainActivity.kt`](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainActivity.kt) (MainActivity), [`app/src/main/res/layout/maincontainer.xml`](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/res/layout/maincontainer.xml) (XML layouts), [`app/src/main/java/org/gnu/itsmoroto/midandpad/MainScreen.kt`](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainScreen.kt) (MainScreen), [`app/src/main/java/org/gnu/itsmoroto/midandpad/BtnConfigScreen.kt`](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BtnConfigScreen.kt) (BtnConfigScreen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_main_activity["MainActivity<br/>entry activity<br/>[MainActivity.kt]"]
  node_splash["Splash<br/>startup screen<br/>[Splash.kt]"]
  node_main_screen["MainScreen<br/>controller screen<br/>[MainScreen.kt]"]
  node_explore_screen["ExploreScreen<br/>browse screen<br/>[ExploreScreen.kt]"]
  node_btn_config["BtnConfigScreen<br/>config screen<br/>[BtnConfigScreen.kt]"]
  node_bar_config["BarConfigScreen<br/>config screen<br/>[BarConfigScreen.kt]"]
  node_touch_cal["TouchCalibration<br/>calibration screen"]
  node_config_params["ConfigParams<br/>shared state<br/>[ConfigParams.kt]"]
  node_midi_config["MidiConfig<br/>midi model<br/>[MidiConfig.kt]"]
  node_midi_helper["MidiHelper<br/>midi engine<br/>[MidiHelper.kt]"]
  node_db[("MidandpadDB<br/>persistence<br/>[MidandpadDB.kt]")]
  node_backup[("BackupDatabase<br/>[BackupDatabase.kt]")]
  node_ui_buttons["Pad controls<br/>custom UI<br/>[EventButton.kt]"]
  node_ui_sliders["Control widgets<br/>custom UI<br/>[VerticalSlider.kt]"]
  node_ui_props["PropertiesView<br/>custom UI<br/>[PropertiesView.kt]"]
  node_button_cfg_types["Button cfgs<br/>midi action types<br/>[ButtonNoteCfg.kt]"]
  node_manifest["AndroidManifest<br/>app manifest"]
end

subgraph group_release["Build and release"]
  node_build_release["Build and release<br/>tooling<br/>[build.gradle.kts]"]
end

subgraph group_assets["Resources"]
  node_layouts["XML layouts<br/>ui resources<br/>[maincontainer.xml]"]
  node_resources["Styles and assets<br/>resource bundle<br/>[strings.xml]"]
end

node_midi_device(("MIDI device<br/>external target"))

node_manifest -->|"launches"| node_main_activity
node_main_activity -->|"shows"| node_splash
node_main_activity -->|"navigates"| node_main_screen
node_main_activity -->|"navigates"| node_explore_screen
node_main_activity -->|"navigates"| node_btn_config
node_main_activity -->|"navigates"| node_bar_config
node_main_activity -->|"navigates"| node_touch_cal
node_main_screen -->|"uses"| node_ui_buttons
node_main_screen -->|"uses"| node_ui_sliders
node_main_screen -->|"reads"| node_config_params
node_main_screen -->|"sends"| node_midi_helper
node_explore_screen -->|"reads"| node_db
node_btn_config -->|"uses"| node_ui_props
node_bar_config -->|"uses"| node_ui_props
node_touch_cal -->|"uses"| node_ui_buttons
node_button_cfg_types -->|"defines"| node_midi_config
node_midi_config -->|"drives"| node_midi_helper
node_config_params -->|"binds"| node_midi_config
node_db -->|"syncs"| node_backup
node_layouts -->|"inflates"| node_main_activity
node_layouts -->|"inflates"| node_main_screen
node_layouts -->|"inflates"| node_btn_config
node_layouts -->|"inflates"| node_bar_config
node_layouts -->|"inflates"| node_touch_cal
node_resources -->|"supports"| node_layouts
node_build_release -->|"packages"| node_manifest
node_midi_helper -->|"outputs"| node_midi_device

click node_main_activity "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainActivity.kt"
click node_splash "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/Splash.kt"
click node_main_screen "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainScreen.kt"
click node_explore_screen "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ExploreScreen.kt"
click node_btn_config "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BtnConfigScreen.kt"
click node_bar_config "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BarConfigScreen.kt"
click node_touch_cal "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/TouchCalibration.kt"
click node_config_params "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ConfigParams.kt"
click node_midi_config "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidiConfig.kt"
click node_midi_helper "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidiHelper.kt"
click node_db "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidandpadDB.kt"
click node_backup "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BackupDatabase.kt"
click node_ui_buttons "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/EventButton.kt"
click node_ui_sliders "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/VerticalSlider.kt"
click node_ui_props "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/PropertiesView.kt"
click node_button_cfg_types "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ButtonNoteCfg.kt"
click node_layouts "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/res/layout/maincontainer.xml"
click node_resources "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/res/values/strings.xml"
click node_manifest "https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/AndroidManifest.xml"
click node_build_release "https://github.com/rokiden/midandpad-dj/blob/master/build.gradle.kts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_activity,node_splash,node_main_screen,node_explore_screen,node_btn_config,node_bar_config,node_touch_cal,node_config_params,node_midi_config,node_midi_helper,node_db,node_backup,node_ui_buttons,node_ui_sliders,node_ui_props,node_button_cfg_types,node_manifest toneBlue
class node_build_release toneAmber
class node_layouts,node_resources toneMint
class node_midi_device toneNeutral
```

## Components

### Android app

Single-module Midandpad application code and resources

- [MainActivity](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainActivity.kt): entry activity · App entry and screen host · `app/src/main/java/org/gnu/itsmoroto/midandpad/MainActivity.kt`
- [Splash](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/Splash.kt): startup screen · Initial branding/loading screen · `app/src/main/java/org/gnu/itsmoroto/midandpad/Splash.kt`
- [MainScreen](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MainScreen.kt): controller screen · Primary MIDI performance surface · `app/src/main/java/org/gnu/itsmoroto/midandpad/MainScreen.kt`
- [ExploreScreen](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ExploreScreen.kt): browse screen · Browse and select content or presets · `app/src/main/java/org/gnu/itsmoroto/midandpad/ExploreScreen.kt`
- [BtnConfigScreen](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BtnConfigScreen.kt): config screen · Edit button-trigger mappings · `app/src/main/java/org/gnu/itsmoroto/midandpad/BtnConfigScreen.kt`
- [BarConfigScreen](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BarConfigScreen.kt): config screen · Edit continuous-control mappings · `app/src/main/java/org/gnu/itsmoroto/midandpad/BarConfigScreen.kt`
- [TouchCalibration](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/TouchCalibration.kt): calibration screen · Calibrate touch targets and layout mapping · `app/src/main/java/org/gnu/itsmoroto/midandpad/TouchCalibration.kt`
- [ConfigParams](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ConfigParams.kt): shared state · Runtime parameters shared across screens · `app/src/main/java/org/gnu/itsmoroto/midandpad/ConfigParams.kt`
- [MidiConfig](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidiConfig.kt): midi model · Shared MIDI configuration model · `app/src/main/java/org/gnu/itsmoroto/midandpad/MidiConfig.kt`
- [MidiHelper](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidiHelper.kt): midi engine · Builds and sends MIDI messages · `app/src/main/java/org/gnu/itsmoroto/midandpad/MidiHelper.kt`
- [MidandpadDB](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/MidandpadDB.kt): persistence · Stores controller setups and presets · `app/src/main/java/org/gnu/itsmoroto/midandpad/MidandpadDB.kt`
- [BackupDatabase](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/BackupDatabase.kt): backup · Export and restore app data · `app/src/main/java/org/gnu/itsmoroto/midandpad/BackupDatabase.kt`
- [Pad controls](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/EventButton.kt): custom UI · Event and calibration buttons · `app/src/main/java/org/gnu/itsmoroto/midandpad/EventButton.kt`
- [Control widgets](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/VerticalSlider.kt): custom UI · Sliders, bars, and note rows · `app/src/main/java/org/gnu/itsmoroto/midandpad/VerticalSlider.kt`
- [PropertiesView](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/PropertiesView.kt): custom UI · Shared property editing view · `app/src/main/java/org/gnu/itsmoroto/midandpad/PropertiesView.kt`
- [Button cfgs](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/java/org/gnu/itsmoroto/midandpad/ButtonNoteCfg.kt): midi action types · Note, control, program, and chord configs · `app/src/main/java/org/gnu/itsmoroto/midandpad/ButtonNoteCfg.kt`
- [AndroidManifest](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/AndroidManifest.xml): app manifest · Declares app components and launch wiring · `app/src/main/AndroidManifest.xml`

### Build and release

Gradle, CI, and store metadata

- [Build and release](https://github.com/rokiden/midandpad-dj/blob/master/build.gradle.kts): tooling · Gradle, GitHub Actions, and store metadata · `build.gradle.kts`

### Resources

Layouts, drawables, strings, themes, and XML resources

- [XML layouts](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/res/layout/maincontainer.xml): ui resources · Screen and widget layouts · `app/src/main/res/layout/maincontainer.xml`
- [Styles and assets](https://github.com/rokiden/midandpad-dj/blob/master/app/src/main/res/values/strings.xml): resource bundle · Drawables, strings, themes, sizes, and attrs · `app/src/main/res/values/strings.xml`

### Other components

- **MIDI device**: external target · Connected hardware or Android MIDI endpoint

## Connections

- AndroidManifest → MainActivity: launches · Declares the entry activity
- MainActivity → Splash: shows · Starts with the splash screen
- MainActivity → MainScreen: navigates · Opens the primary controller surface
- MainActivity → ExploreScreen: navigates · Opens preset/content browsing
- MainActivity → BtnConfigScreen: navigates · Opens button mapping editor
- MainActivity → BarConfigScreen: navigates · Opens continuous-control editor
- MainActivity → TouchCalibration: navigates · Opens touch calibration
- MainScreen → Pad controls: uses · Renders pad and trigger controls
- MainScreen → Control widgets: uses · Renders mixer and bar controls
- MainScreen → ConfigParams: reads · Consumes shared controller state
- MainScreen → MidiHelper: sends · Converts interaction into MIDI output
- ExploreScreen → MidandpadDB: reads · Loads stored presets and setups
- BtnConfigScreen → PropertiesView: uses · Edits button properties
- BarConfigScreen → PropertiesView: uses · Edits bar properties
- TouchCalibration → Pad controls: uses · Calibrates touch targets
- Button cfgs → MidiConfig: defines · Specialized action variants feed the shared MIDI model
- MidiConfig → MidiHelper: drives · Defines what message to generate
- ConfigParams → MidiConfig: binds · Connects runtime state to MIDI setup
- MidandpadDB → BackupDatabase: syncs · Persisted data can be backed up or restored
- XML layouts → MainActivity: inflates · Activity and screen layouts
- XML layouts → MainScreen: inflates · Main controller layout
- XML layouts → BtnConfigScreen: inflates · Button config layout
- XML layouts → BarConfigScreen: inflates · Bar config layout
- XML layouts → TouchCalibration: inflates · Calibration layout
- Styles and assets → XML layouts: supports · Themes, strings, sizes, attrs, and drawable assets
- Build and release → AndroidManifest: packages · Builds the Android app bundle/APK
- MidiHelper → MIDI device: outputs · Sends MIDI events to external target
