# icherniukh/ep133-krate architecture

> Architecture diagram of the GitHub repository icherniukh/ep133-krate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icherniukh/ep133-krate
- Repository: https://github.com/icherniukh/ep133-krate

## Overview

1. **What this repo is**
   - `ep133-krate` is a Python 3.11+ sample manager for the EP-133 KO-II.
   - It is centered on a reverse-engineered MIDI SysEx protocol; `PROTOCOL.md` and the `captures/` artifacts are the architectural source of truth.

2. **Top-level shape**
   - `src/core/` is the protocol/device domain layer.
   - `src/cli/` is the command-line interface.
   - `src/tui/` is the Textual-based terminal UI.
   - `src/mobile/` is a planned/early mobile app surface.
   - `tests/` contains most of the protocol and behavior verification, including emulator-backed end-to-end tests.

3. **Main runtime path**
   - User action enters through either the CLI entrypoint (`krate.py` / `src/cli/cli_main.py`) or the TUI (`src/tui/app.py`).
   - Both frontends call into the same core client/operations layer.
   - The core layer talks to the hardware over MIDI, and responses are parsed back into domain models for rendering or file transfer.

4. **Core domain boundary**
   - `src/core/client.py` is the low-level transport-facing client.
   - `src/core/operations.py` and `src/core/ops.py` hold the stateful workflows, such as upload transactions that span multiple protocol messages.
   - `src/core/models.py`, `types.py`, and `naming.py` define protocol data structures and wire encodings.
   - `audio.py`, `backup.py`, and `waveform_store.py` handle sample-specific concerns outside the raw transport layer.

5. **Protocol encoding layer**
   - `types.py` contains the wire primitives, especially `Packed7`, which exists because SysEx is 7-bit-clean.
   - Binary payloads such as PCM audio and JSON metadata are encoded/decoded here before they cross the MIDI boundary.
   - This keeps the transport layer unaware of the encoding details and makes serialization symmetric and testable.

6. **CLI architecture**
   - `src/cli/parser.py` routes subcommands into command modules like `cmd_audio.py`, `cmd_slots.py`, `cmd_system.py`, and `cmd_transfer.py`.
   - Commands are rendered through an injected `View` abstraction in `display.py` and `formatters.py`, with concrete terminal, silent, and JSON output modes.
   - This is a deliberate boundary: command logic can be tested without stdout patching or subprocesses.

7. **TUI architecture**
   - The TUI is a Textual app built from `src/tui/app.py`, `ui.py`, `state.py`, `actions.py`, and supporting widgets/dialogs.
   - Device access is isolated in `src/tui/worker.py`: blocking `EP133Client` calls run in a background thread so the async UI stays responsive.
   - `waveform_widget.py` and the waveform cache logic support braille waveform rendering and avoid unnecessary device round-trips when a fingerprint is already known.

8. **Audio and transfer pipeline**
   - Upload/download flows move between local files and slot metadata, with `src/core/audio.py` and `src/core/operations.py` coordinating conversion and protocol sequencing.
   - The README notes `sox` as a required external tool for audio conversion/optimization, so audio handling is not purely in-process Python.
   - The transfer path also includes recovery/verification behavior, reflecting the device’s quirks captured in protocol evidence.

9. **Device/protocol realities that shape the design**
   - The repo encodes known device behavior, such as re-initializing after downloads, avoiding stale metadata paths, and using runtime inventory over incomplete device metadata.
   - These constraints influence the client/operations design more than the UI design, because correctness depends on message ordering and session state.
   - `PROTOCOL.md` plus the capture files are therefore architectural dependencies, not just documentation.

10. **Support tooling and external surfaces**
   - `scripts/` contains utilities for capture upload, MIDI proxying, mobile bridging, and capture cleanup.
   - `tests/emulator.py` and the `tests/e2e/` suite provide a simulated device boundary for integration testing.
   - GitHub Actions, linting, and release workflows show the repo is designed for reproducible validation and packaging.

11. **Mobile roadmap**
   - `src/mobile/` exists as a separate UI surface with screens for slot lists and upload queue management.
   - It is architecturally distinct from the CLI/TUI, but still expected to reuse the same core protocol layer.
   - The README positions native mobile as a roadmap item rather than the primary shipped interface.

12. **How to diagram it**
   - A good diagram would show three client surfaces on top: CLI, TUI, and future mobile.
   - All three converge on the shared core domain layer.
   - The core layer then connects to the physical EP-133 over MIDI SysEx, with protocol docs/captures feeding development and tests verifying behavior against emulation and recorded traffic.

Main entry points: [`src/core/operations.py`](https://github.com/icherniukh/ep133-krate/blob/main/src/core/operations.py) (Operations), [`src/core/client.py`](https://github.com/icherniukh/ep133-krate/blob/main/src/core/client.py) (Client), [`src/cli/cmd_transfer.py`](https://github.com/icherniukh/ep133-krate/blob/main/src/cli/cmd_transfer.py) (CLI cmds), [`src/core/types.py`](https://github.com/icherniukh/ep133-krate/blob/main/src/core/types.py) (Protocol types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontends["Client surfaces"]
  node_node_krate["krate.py<br/>entrypoint<br/>[krate.py]"]
  node_node_cli_main["CLI main<br/>cli entry<br/>[cli_main.py]"]
  node_node_cli_parser["Parser<br/>cli router<br/>[parser.py]"]
  node_node_cli_commands["CLI cmds<br/>cli commands<br/>[cmd_transfer.py]"]
  node_node_cli_view["CLI view<br/>output layer<br/>[display.py]"]
  node_node_tui_app["TUI app<br/>textual app<br/>[app.py]"]
  node_node_tui_ui["TUI UI<br/>ui composition<br/>[ui.py]"]
  node_node_tui_worker["Worker<br/>async bridge<br/>[worker.py]"]
  node_node_mobile_app["Mobile app<br/>mobile surface<br/>[app.py]"]
  node_node_mobile_screens["Mobile screens<br/>mobile ui<br/>[slot_list.py]"]
end

subgraph group_group_core["Core domain"]
  node_node_client["Client<br/>[client.py]"]
  node_node_ops["Operations<br/>workflow engine<br/>[operations.py]"]
  node_node_protocol["Protocol types<br/>wire models<br/>[types.py]"]
  node_node_models["Models<br/>[models.py]"]
  node_node_audio["Audio flow<br/>audio pipeline<br/>[audio.py]"]
  node_node_backup["Backup<br/>device state<br/>[backup.py]"]
  node_node_waveform_store["Waveforms<br/>cache<br/>[waveform_store.py]"]
  node_node_midi_transport["MIDI transport<br/>transport adapter<br/>[midi_transport.py]"]
end

subgraph group_group_support["Protocol evidence"]
  node_node_protocol_md["PROTOCOL.md<br/>protocol evidence<br/>[PROTOCOL.md]"]
  node_node_captures[("Captures<br/>evidence corpus")]
  node_node_emulator["Emulator tests<br/>integration test harness<br/>[emulator.py]"]
end

node_node_krate -->|"starts"| node_node_cli_main
node_node_cli_main -->|"dispatches"| node_node_cli_parser
node_node_cli_parser -->|"invokes"| node_node_cli_commands
node_node_cli_commands -->|"renders via"| node_node_cli_view
node_node_cli_commands -->|"uses"| node_node_ops
node_node_tui_app -->|"composes"| node_node_tui_ui
node_node_tui_ui -->|"offloads"| node_node_tui_worker
node_node_tui_worker -->|"calls"| node_node_client
node_node_mobile_app -->|"navigates"| node_node_mobile_screens
node_node_mobile_screens -->|"reuses"| node_node_ops
node_node_ops -->|"orchestrates"| node_node_client
node_node_client -->|"transports over"| node_node_midi_transport
node_node_client -->|"encodes/decodes"| node_node_protocol
node_node_protocol -->|"shapes"| node_node_models
node_node_ops -->|"coordinates"| node_node_audio
node_node_ops -->|"manages"| node_node_backup
node_node_audio -->|"consults"| node_node_waveform_store
node_node_protocol_md -->|"defines"| node_node_protocol
node_node_captures -->|"evidences"| node_node_protocol_md
node_node_emulator -->|"verifies"| node_node_ops
node_node_emulator -->|"simulates"| node_node_client

click node_node_krate "https://github.com/icherniukh/ep133-krate/blob/main/krate.py"
click node_node_cli_main "https://github.com/icherniukh/ep133-krate/blob/main/src/cli/cli_main.py"
click node_node_cli_parser "https://github.com/icherniukh/ep133-krate/blob/main/src/cli/parser.py"
click node_node_cli_commands "https://github.com/icherniukh/ep133-krate/blob/main/src/cli/cmd_transfer.py"
click node_node_cli_view "https://github.com/icherniukh/ep133-krate/blob/main/src/cli/display.py"
click node_node_tui_app "https://github.com/icherniukh/ep133-krate/blob/main/src/tui/app.py"
click node_node_tui_ui "https://github.com/icherniukh/ep133-krate/blob/main/src/tui/ui.py"
click node_node_tui_worker "https://github.com/icherniukh/ep133-krate/blob/main/src/tui/worker.py"
click node_node_mobile_app "https://github.com/icherniukh/ep133-krate/blob/main/src/mobile/app.py"
click node_node_mobile_screens "https://github.com/icherniukh/ep133-krate/blob/main/src/mobile/screens/slot_list.py"
click node_node_client "https://github.com/icherniukh/ep133-krate/blob/main/src/core/client.py"
click node_node_ops "https://github.com/icherniukh/ep133-krate/blob/main/src/core/operations.py"
click node_node_protocol "https://github.com/icherniukh/ep133-krate/blob/main/src/core/types.py"
click node_node_models "https://github.com/icherniukh/ep133-krate/blob/main/src/core/models.py"
click node_node_audio "https://github.com/icherniukh/ep133-krate/blob/main/src/core/audio.py"
click node_node_backup "https://github.com/icherniukh/ep133-krate/blob/main/src/core/backup.py"
click node_node_waveform_store "https://github.com/icherniukh/ep133-krate/blob/main/src/core/waveform_store.py"
click node_node_midi_transport "https://github.com/icherniukh/ep133-krate/blob/main/src/core/midi_transport.py"
click node_node_protocol_md "https://github.com/icherniukh/ep133-krate/blob/main/PROTOCOL.md"
click node_node_captures "https://github.com/icherniukh/ep133-krate/tree/main/captures"
click node_node_emulator "https://github.com/icherniukh/ep133-krate/blob/main/tests/emulator.py"

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_node_krate,node_node_cli_main,node_node_cli_parser,node_node_cli_commands,node_node_cli_view,node_node_tui_app,node_node_tui_ui,node_node_tui_worker,node_node_mobile_app,node_node_mobile_screens toneBlue
class node_node_client,node_node_ops,node_node_protocol,node_node_models,node_node_audio,node_node_backup,node_node_waveform_store,node_node_midi_transport toneAmber
class node_node_protocol_md,node_node_captures,node_node_emulator toneMint
```

## Components

### Client surfaces

User-facing entry points that invoke the shared core layer.

- [krate.py](https://github.com/icherniukh/ep133-krate/blob/main/krate.py): entrypoint · Top-level script entry into the CLI experience. · `krate.py`
- [CLI main](https://github.com/icherniukh/ep133-krate/blob/main/src/cli/cli_main.py): cli entry · Initializes command-line execution and dispatch. · `src/cli/cli_main.py`
- [Parser](https://github.com/icherniukh/ep133-krate/blob/main/src/cli/parser.py): cli router · Routes subcommands into command handlers. · `src/cli/parser.py`
- [CLI cmds](https://github.com/icherniukh/ep133-krate/blob/main/src/cli/cmd_transfer.py): cli commands · Audio, slot, system, and transfer command modules. · `src/cli/cmd_transfer.py`
- [CLI view](https://github.com/icherniukh/ep133-krate/blob/main/src/cli/display.py): output layer · Output abstraction and formatters for terminal, silent, and JSON rendering. · `src/cli/display.py`
- [TUI app](https://github.com/icherniukh/ep133-krate/blob/main/src/tui/app.py): textual app · Textual-based terminal application entrypoint. · `src/tui/app.py`
- [TUI UI](https://github.com/icherniukh/ep133-krate/blob/main/src/tui/ui.py): ui composition · Screens, actions, selectors, dialogs, and state for the terminal interface. · `src/tui/ui.py`
- [Worker](https://github.com/icherniukh/ep133-krate/blob/main/src/tui/worker.py): async bridge · Runs blocking device calls off the UI thread. · `src/tui/worker.py`
- [Mobile app](https://github.com/icherniukh/ep133-krate/blob/main/src/mobile/app.py): mobile surface · Planned mobile-facing shell that reuses the shared protocol layer. · `src/mobile/app.py`
- [Mobile screens](https://github.com/icherniukh/ep133-krate/blob/main/src/mobile/screens/slot_list.py): mobile ui · Slot list and upload queue screens for the mobile roadmap. · `src/mobile/screens/slot_list.py`

### Core domain

Protocol, transport, and device workflows for the EP-133.

- [Client](https://github.com/icherniukh/ep133-krate/blob/main/src/core/client.py): transport client · Low-level MIDI-facing EP-133 client used by all frontends. · `src/core/client.py`
- [Operations](https://github.com/icherniukh/ep133-krate/blob/main/src/core/operations.py): workflow engine · Stateful multi-message workflows such as uploads and recovery. · `src/core/operations.py`
- [Protocol types](https://github.com/icherniukh/ep133-krate/blob/main/src/core/types.py): wire models · Wire primitives, packed 7-bit encoding, and protocol data structures. · `src/core/types.py`
- [Models](https://github.com/icherniukh/ep133-krate/blob/main/src/core/models.py): domain models · Protocol-facing domain objects and metadata structures. · `src/core/models.py`
- [Audio flow](https://github.com/icherniukh/ep133-krate/blob/main/src/core/audio.py): audio pipeline · PCM/sample conversion, validation, and upload/download preparation. · `src/core/audio.py`
- [Backup](https://github.com/icherniukh/ep133-krate/blob/main/src/core/backup.py): device state · Backup and restore logic for device content. · `src/core/backup.py`
- [Waveforms](https://github.com/icherniukh/ep133-krate/blob/main/src/core/waveform_store.py): cache · Fingerprint and waveform cache to avoid redundant device round-trips. · `src/core/waveform_store.py`
- [MIDI transport](https://github.com/icherniukh/ep133-krate/blob/main/src/core/midi_transport.py): transport adapter · Underlying MIDI I/O adapter beneath the client. · `src/core/midi_transport.py`

### Protocol evidence

Docs, captures, and emulator-backed verification that shape the implementation.

- [PROTOCOL.md](https://github.com/icherniukh/ep133-krate/blob/main/PROTOCOL.md): protocol evidence · Primary reverse-engineered protocol specification. · `PROTOCOL.md`
- [Captures](https://github.com/icherniukh/ep133-krate/tree/main/captures): evidence corpus · Recorded device traffic and traces used as source evidence. · `captures`
- [Emulator tests](https://github.com/icherniukh/ep133-krate/blob/main/tests/emulator.py): integration test harness · Simulated device boundary used for end-to-end verification. · `tests/emulator.py`

## Connections

- krate.py → CLI main: starts · Top-level script launches CLI execution.
- CLI main → Parser: dispatches · CLI startup routes into subcommand parsing.
- Parser → CLI cmds: invokes · Parsed subcommands enter command modules.
- CLI cmds → CLI view: renders via · Command output flows through the injected view layer.
- CLI cmds → Operations: uses · Commands call shared workflows rather than device APIs directly.
- TUI app → TUI UI: composes · Textual app builds screens and actions from UI modules.
- TUI UI → Worker: offloads · Blocking device operations are sent to the background worker.
- Worker → Client: calls · Worker executes EP-133 client operations off the UI thread.
- Mobile app → Mobile screens: navigates · Mobile shell presents the roadmap screens.
- Mobile screens → Operations: reuses · Mobile UI is expected to share the same workflow layer.
- Operations → Client: orchestrates · Workflows coordinate protocol exchanges through the client.
- Client → MIDI transport: transports over · Client depends on MIDI I/O for hardware communication.
- Client → Protocol types: encodes/decodes · Client uses wire primitives and packed 7-bit payloads.
- Protocol types → Models: shapes · Wire primitives feed protocol-domain models.
- Operations → Audio flow: coordinates · Upload/download flows convert and sequence audio payloads.
- Operations → Backup: manages · Backup and restore behavior is implemented in workflows.
- Audio flow → Waveforms: consults · Audio handling uses waveform fingerprints and cache state.
- PROTOCOL.md → Protocol types: defines · Protocol documentation informs the wire layer.
- Captures → PROTOCOL.md: evidences · Captured traffic underpins the protocol specification.
- Emulator tests → Operations: verifies · Integration tests exercise workflows against an emulated device.
- Emulator tests → Client: simulates · Emulator-backed tests stand in for the hardware boundary.