# bit-wmike/fm1-companion architecture

> Architecture diagram of the GitHub repository bit-wmike/fm1-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bit-wmike/fm1-companion
- Repository: https://github.com/bit-wmike/fm1-companion

## Overview

FM-1 Companion is a desktop suite for managing and working with M-VAVE FM-1 devices. The main user journey runs from the desktop shell into device, backup, firmware, music, and Studio workflows; the Studio can also act as a virtual device for other work. The graph preserves those documented capabilities and central runtime modules. Some UI-to-domain links come from README descriptions; unsampled implementation details and uncertain wiring are omitted.

Main entry points: [`fm1companion/ui/main_window.py`](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/main_window.py) (Main window), [`fm1companion/backup.py`](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/backup.py) (Backups), [`fm1companion/studio.py`](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/studio.py) (Digital twin), [`fm1companion/app.py`](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/app.py) (Desktop entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Desktop shell"]
  node_app["Desktop entry<br/>[app.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_ui_common["UI components<br/>[common.py]"]
  node_ui_responsive["Responsive layout<br/>[responsive.py]"]
  node_theme["Theme<br/>[theme.py]"]
  node_i18n["Translations<br/>[i18n.py]"]
end

subgraph group_device["Device and data"]
  node_config[("Settings and paths<br/>[config.py]")]
  node_devices["Device profiles<br/>[devices.py]"]
  node_protocol["Device protocol<br/>[protocol.py]"]
  node_backup["Backups<br/>[backup.py]"]
  node_backup_inspect["Backup browser<br/>[backup_inspect.py]"]
  node_sloopbk["SLOOP backup format<br/>[sloopbk.py]"]
end

subgraph group_firmware["Firmware and recovery"]
  node_catalog["Firmware catalog<br/>[catalog.py]"]
  node_firmware["Firmware versions<br/>[firmware.py]"]
  node_fwfamily["Firmware families<br/>[fwfamily.py]"]
  node_flash["Firmware installer<br/>[engine.py]"]
  node_recovery["Recovery interface<br/>[recovery.py]"]
end

subgraph group_music["Music and MIDI"]
  node_projects["Projects<br/>[projects.py]"]
  node_midi["MIDI tools<br/>[miditools.py]"]
end

subgraph group_studio["Studio and support"]
  node_studio_service["Studio service<br/>[studio_service.py]"]
  node_studio["Digital twin<br/>[studio.py]"]
  node_editor["Embedded editor<br/>[editor_host.py]"]
  node_storage[("Storage cleanup<br/>[storage.py]")]
  node_storage_ui["Storage settings<br/>[storage_tab.py]"]
  node_syscheck["System diagnostics<br/>[syscheck.py]"]
end

node_user(("FM-1 user"))

node_user -->|"starts"| node_app
node_app -->|"opens"| node_window
node_app -->|"loads settings"| node_config
node_app -->|"runs checks"| node_syscheck
node_window -->|"manages backups"| node_backup
node_window -->|"browses firmware"| node_catalog
node_window -->|"opens projects"| node_projects
node_window -->|"opens Studio"| node_studio_service
node_window -->|"opens recovery"| node_recovery
node_window -->|"opens settings"| node_storage_ui
node_window -->|"opens MIDI"| node_midi
node_devices -->|"reads profiles"| node_config
node_backup -->|"uses protocol"| node_protocol
node_backup -->|"uses format"| node_sloopbk
node_backup -->|"uses inspection"| node_backup_inspect
node_catalog -->|"resolves firmware"| node_firmware
node_firmware -->|"classifies family"| node_fwfamily
node_firmware -->|"starts installation"| node_flash
node_firmware -->|"checks simulator"| node_studio
node_recovery -.->|"guides recovery"| node_flash
node_studio_service -->|"manages twin"| node_studio
node_studio_service -->|"loads backup"| node_backup
node_studio -->|"uses protocol"| node_protocol
node_studio -->|"uses profiles"| node_devices
node_studio -->|"uses editor host"| node_editor
node_storage_ui -->|"scans and cleans"| node_storage
node_storage -->|"uses data paths"| node_config
node_syscheck -->|"checks devices"| node_devices
node_syscheck -->|"checks storage"| node_storage
node_ui_common -->|"uses theme"| node_theme
node_ui_responsive -->|"uses components"| node_ui_common
node_theme -->|"reads preferences"| node_config
node_ui_common -->|"translates labels"| node_i18n

click node_app "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/app.py"
click node_window "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/main_window.py"
click node_ui_common "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/common.py"
click node_ui_responsive "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/responsive.py"
click node_theme "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/theme.py"
click node_i18n "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/i18n.py"
click node_config "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/config.py"
click node_devices "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/devices.py"
click node_protocol "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/protocol.py"
click node_backup "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/backup.py"
click node_backup_inspect "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/backup_inspect.py"
click node_sloopbk "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/sloopbk.py"
click node_projects "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/projects.py"
click node_midi "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/miditools.py"
click node_catalog "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/catalog.py"
click node_firmware "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/firmware.py"
click node_fwfamily "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/fwfamily.py"
click node_flash "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/flash/engine.py"
click node_recovery "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/pages/recovery.py"
click node_studio_service "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/studio_service.py"
click node_studio "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/studio.py"
click node_editor "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/editor_host.py"
click node_storage "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/storage.py"
click node_storage_ui "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/storage_tab.py"
click node_syscheck "https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/syscheck.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_app,node_window,node_ui_common,node_ui_responsive,node_theme,node_i18n,node_user toneBlue
class node_config,node_devices,node_protocol,node_backup,node_backup_inspect,node_sloopbk toneAmber
class node_catalog,node_firmware,node_fwfamily,node_flash,node_recovery toneMint
class node_projects,node_midi toneRose
class node_studio_service,node_studio,node_editor,node_storage,node_storage_ui,node_syscheck toneIndigo
```

## Components

### Desktop shell

- [Desktop entry](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/app.py): `fm1companion/app.py`
- [Main window](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/main_window.py): `fm1companion/ui/main_window.py`
- [UI components](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/common.py): `fm1companion/ui/common.py`
- [Responsive layout](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/responsive.py): `fm1companion/ui/responsive.py`
- [Theme](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/theme.py): `fm1companion/ui/theme.py`
- [Translations](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/i18n.py): `fm1companion/i18n.py`

### Device and data

- [Settings and paths](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/config.py): `fm1companion/config.py`
- [Device profiles](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/devices.py): `fm1companion/devices.py`
- [Device protocol](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/protocol.py): `fm1companion/protocol.py`
- [Backups](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/backup.py): `fm1companion/backup.py`
- [Backup browser](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/backup_inspect.py): `fm1companion/backup_inspect.py`
- [SLOOP backup format](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/sloopbk.py): `fm1companion/sloopbk.py`

### Firmware and recovery

- [Firmware catalog](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/catalog.py): `fm1companion/catalog.py`
- [Firmware versions](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/firmware.py): `fm1companion/firmware.py`
- [Firmware families](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/fwfamily.py): `fm1companion/fwfamily.py`
- [Firmware installer](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/flash/engine.py): `fm1companion/flash/engine.py`
- [Recovery interface](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/pages/recovery.py): `fm1companion/ui/pages/recovery.py`

### Music and MIDI

- [Projects](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/projects.py): `fm1companion/projects.py`
- [MIDI tools](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/miditools.py): `fm1companion/miditools.py`

### Studio and support

- [Studio service](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/studio_service.py): `fm1companion/ui/studio_service.py`
- [Digital twin](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/studio.py): `fm1companion/studio.py`
- [Embedded editor](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/editor_host.py): `fm1companion/editor_host.py`
- [Storage cleanup](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/storage.py): `fm1companion/storage.py`
- [Storage settings](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/ui/storage_tab.py): `fm1companion/ui/storage_tab.py`
- [System diagnostics](https://github.com/bit-wmike/fm1-companion/blob/main/fm1companion/syscheck.py): `fm1companion/syscheck.py`

### Other components

- **FM-1 user**

## Connections

- FM-1 user → Desktop entry: starts
- Desktop entry → Main window: opens (evidence: `fm1companion/app.py`)
- Desktop entry → Settings and paths: loads settings (evidence: `fm1companion/app.py`)
- Desktop entry → System diagnostics: runs checks (evidence: `fm1companion/app.py`)
- Main window → Backups: manages backups
- Main window → Firmware catalog: browses firmware
- Main window → Projects: opens projects
- Main window → Studio service: opens Studio
- Main window → Recovery interface: opens recovery
- Main window → Storage settings: opens settings
- Main window → MIDI tools: opens MIDI
- Device profiles → Settings and paths: reads profiles (evidence: `fm1companion/devices.py`)
- Backups → Device protocol: uses protocol (evidence: `fm1companion/backup.py`)
- Backups → SLOOP backup format: uses format (evidence: `fm1companion/backup.py`)
- Backups → Backup browser: uses inspection (evidence: `fm1companion/backup.py`)
- Firmware catalog → Firmware versions: resolves firmware (evidence: `fm1companion/catalog.py`)
- Firmware versions → Firmware families: classifies family (evidence: `fm1companion/firmware.py`)
- Firmware versions → Firmware installer: starts installation (evidence: `fm1companion/firmware.py`)
- Firmware versions → Digital twin: checks simulator (evidence: `fm1companion/firmware.py`)
- Recovery interface → Firmware installer: guides recovery
- Studio service → Digital twin: manages twin (evidence: `fm1companion/ui/studio_service.py`)
- Studio service → Backups: loads backup (evidence: `fm1companion/ui/studio_service.py`)
- Digital twin → Device protocol: uses protocol (evidence: `fm1companion/studio.py`)
- Digital twin → Device profiles: uses profiles (evidence: `fm1companion/studio.py`)
- Digital twin → Embedded editor: uses editor host (evidence: `fm1companion/studio.py`)
- Storage settings → Storage cleanup: scans and cleans (evidence: `fm1companion/ui/storage_tab.py`)
- Storage cleanup → Settings and paths: uses data paths (evidence: `fm1companion/storage.py`)
- System diagnostics → Device profiles: checks devices (evidence: `fm1companion/syscheck.py`)
- System diagnostics → Storage cleanup: checks storage (evidence: `fm1companion/syscheck.py`)
- UI components → Theme: uses theme (evidence: `fm1companion/ui/common.py`)
- Responsive layout → UI components: uses components (evidence: `fm1companion/ui/responsive.py`)
- Theme → Settings and paths: reads preferences (evidence: `fm1companion/ui/theme.py`)
- UI components → Translations: translates labels (evidence: `fm1companion/ui/common.py`)
