# artisan-roaster-scope/artisan architecture

> Architecture diagram of the GitHub repository artisan-roaster-scope/artisan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artisan-roaster-scope/artisan
- Repository: https://github.com/artisan-roaster-scope/artisan

## Overview

#### Purpose and Runtime
Artisan is a cross-platform Python desktop application for recording, analyzing, and controlling coffee-roasting profiles. It combines a Qt GUI, live device acquisition, roast-event workflows, profile persistence/import-export, and optional cloud-connected business features. Primary launch path: `src/artisan.py`, which delegates application orchestration to `src/artisanlib/main.py`. Packaging targets Windows, macOS, Linux, and Raspberry Pi via PyInstaller/spec and platform scripts.

#### Application Shell and UI
The central application/controller layer manages startup, settings, windows, and user-driven roast operations. `src/artisanlib/main.py` is the primary coordinator; `src/artisanlib/canvas.py` provides the interactive roast graph/visual scope; `src/artisanlib/dialogs.py` hosts configuration and operational dialogs. Qt Designer sources and generated UI modules support specialized widgets: `src/ui/SetupWidget.ui`, `src/uic/SetupWidget.py`.

#### Live Acquisition and Device Boundary
Hardware communication is isolated behind ports, device adapters, and asynchronous transport. Core connectivity includes `src/artisanlib/comm.py`, `src/artisanlib/async_comm.py`, and `src/artisanlib/ports.py`. Protocol-specific boundaries include Modbus (`src/artisanlib/modbusport.py`), Siemens S7 (`src/artisanlib/s7port.py`), MQTT (`src/artisanlib/mqttport.py`), WebSockets (`src/artisanlib/wsport.py`), BLE (`src/artisanlib/ble_port.py`), and Phidgets (`src/artisanlib/phidgets.py`). Vendor adapters translate machine-specific protocols into the application’s readings/control model, e.g. `src/artisanlib/giesen.py`, `src/artisanlib/aillio_r2.py`, and `src/artisanlib/santoker.py`.

#### Roast Session Data Flow
During a roast, sampled device values feed the canvas and derived calculations; user/device events annotate the profile; alarms and automation can issue actions. Event and phase state are managed by `src/artisanlib/events.py` and `src/artisanlib/phases.py`; alarms by `src/artisanlib/alarms.py`; signal cleanup/derived processing by `src/artisanlib/filters.py` and `src/artisanlib/curves.py`. This is the key real-time boundary: acquisition/control must remain resilient and non-blocking while Qt renders and records the session.

#### Control and Automation
PID logic converts configured setpoints and measured process values into machine commands through the communications layer. Core modules are `src/artisanlib/pid.py`, `src/artisanlib/pid_control.py`, and `src/artisanlib/command_utility.py`. Alarms, event buttons, replay/program features, and predefined machine setup files provide higher-level control behavior. Bundled setup presets are data-driven assets under `src/includes/Machines/`, for example `src/includes/Machines/Giesen/W15A.aset`.

#### Profiles, Persistence, and Reporting
Roast profiles are loaded, saved, compared, transformed, and exported through `src/artisanlib/roastlog.py`, `src/artisanlib/roastpath.py`, and `src/artisanlib/comparator.py`. The repository includes `.alog` profile assets and import coverage for third-party formats, with adapters such as `src/artisanlib/cropster.py`, `src/artisanlib/ikawa.py`, and `src/artisanlib/stronghold.py`. HTML/report presentation assets reside in `src/includes/report-template.htm` and `src/includes/roast-template.htm`.

#### External Service Integration
The optional Artisan Plus domain is a separate package boundary under `src/plus/`. It handles account/authentication, remote API connection, synchronization, and business objects: `src/plus/connection.py`, `src/plus/sync.py`, `src/plus/controller.py`. It supports inventory, blends, roast data, schedules, stock, and notifications without being the core local roasting runtime.

#### Distribution and Embedded Assets
Runtime assets include translations in `src/translations/`, themes in `src/includes/Themes/`, roast wheels in `src/Wheels/`, and generated help modules in `src/help/`. Platform packaging is defined by `src/artisan-win.spec`, `src/artisan-mac.spec`, `src/artisan-linux.spec`, plus scripts such as `src/build-linux.sh`. Linux installation includes udev rules for USB hardware access at `src/debian/etc/udev/rules.d/99-artisan.rules`.

Main entry points: [`src/artisanlib/main.py`](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/main.py) (Application coordinator), [`src/artisanlib/comm.py`](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/comm.py) (Communications core), [`src/artisanlib/events.py`](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/events.py) (Events and phases), [`src/artisanlib/filters.py`](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/filters.py) (Signal processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Runtime"]
  node_entry["Application entry<br/>Python launcher<br/>[artisan.py]"]
  node_main["Application coordinator<br/>Qt application controller<br/>[main.py]"]
  node_canvas["Roast canvas<br/>interactive Qt view<br/>[canvas.py]"]
  node_dialogs["Operational dialogs<br/>Qt dialogs<br/>[dialogs.py]"]
  node_setup_ui["Setup widget<br/>Qt Designer UI<br/>[SetupWidget.ui]"]
end

subgraph group_device["Device Integration"]
  node_comm["Communications core<br/>device I/O boundary<br/>[comm.py]"]
  node_async_comm["Async transport<br/>asynchronous I/O<br/>[async_comm.py]"]
  node_ports["Port abstraction<br/>connection manager<br/>[ports.py]"]
  node_protocols["Protocol transports<br/>[modbusport.py]"]
  node_adapters["Roaster adapters<br/>vendor machine adapters<br/>[giesen.py]"]
  node_machine_presets["Machine presets<br/>setup assets<br/>[W15A.aset]"]
end

subgraph group_session["Roast Session"]
  node_events["Events and phases<br/>session workflow<br/>[events.py]"]
  node_processing["Signal processing<br/>filters and curves<br/>[filters.py]"]
  node_alarms["Alarms<br/>automation rules<br/>[alarms.py]"]
  node_pid["PID control<br/>setpoint controller<br/>[pid_control.py]"]
end

subgraph group_profiles["Profiles &amp; Services"]
  node_profiles_node[("Profile persistence<br/>roast logs and paths<br/>[roastlog.py]")]
  node_imports["Third-party importers<br/>profile adapters<br/>[cropster.py]"]
  node_reports["Report templates<br/>HTML assets"]
  node_plus["Artisan Plus<br/>optional cloud domain<br/>[controller.py]"]
end

subgraph group_distribution["Distribution Assets"]
  node_runtime_assets["Runtime assets<br/>translations, themes, wheels, help"]
  node_packaging["Platform packaging<br/>PyInstaller and install scripts<br/>[artisan-win.spec]"]
end

node_entry -->|"launches"| node_main
node_main -->|"drives"| node_canvas
node_main -->|"opens"| node_dialogs
node_dialogs -->|"uses"| node_setup_ui
node_main -->|"starts acquisition"| node_comm
node_comm -->|"uses"| node_async_comm
node_comm -->|"manages"| node_ports
node_ports -->|"connects through"| node_protocols
node_protocols -->|"supports"| node_adapters
node_machine_presets -.->|"configures"| node_adapters
node_comm -->|"sampled values"| node_processing
node_processing -->|"derived curves"| node_canvas
node_events -->|"annotates"| node_canvas
node_main -->|"records operations"| node_events
node_processing -->|"monitors values"| node_alarms
node_alarms -->|"triggers actions"| node_pid
node_pid -->|"issues commands"| node_comm
node_events -->|"records profile"| node_profiles_node
node_profiles_node -->|"imports formats"| node_imports
node_profiles_node -->|"renders reports"| node_reports
node_main -.->|"optional integration"| node_plus
node_packaging -->|"bundles"| node_entry
node_packaging -->|"includes"| node_runtime_assets

click node_entry "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisan.py"
click node_main "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/main.py"
click node_canvas "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/canvas.py"
click node_dialogs "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/dialogs.py"
click node_setup_ui "https://github.com/artisan-roaster-scope/artisan/blob/master/src/ui/SetupWidget.ui"
click node_comm "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/comm.py"
click node_async_comm "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/async_comm.py"
click node_ports "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/ports.py"
click node_protocols "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/modbusport.py"
click node_adapters "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/giesen.py"
click node_machine_presets "https://github.com/artisan-roaster-scope/artisan/blob/master/src/includes/Machines/Giesen/W15A.aset"
click node_events "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/events.py"
click node_processing "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/filters.py"
click node_alarms "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/alarms.py"
click node_pid "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/pid_control.py"
click node_profiles_node "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/roastlog.py"
click node_imports "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/cropster.py"
click node_reports "https://github.com/artisan-roaster-scope/artisan/blob/master/src/includes/report-template.htm"
click node_plus "https://github.com/artisan-roaster-scope/artisan/blob/master/src/plus/controller.py"
click node_runtime_assets "https://github.com/artisan-roaster-scope/artisan/tree/master/src/translations"
click node_packaging "https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisan-win.spec"

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_entry,node_main,node_canvas,node_dialogs,node_setup_ui toneBlue
class node_comm,node_async_comm,node_ports,node_protocols,node_adapters,node_machine_presets toneAmber
class node_events,node_processing,node_alarms,node_pid toneMint
class node_profiles_node,node_imports,node_reports,node_plus toneRose
class node_runtime_assets,node_packaging toneIndigo
```

## Components

### Desktop Runtime

- [Application entry](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisan.py): Python launcher · `src/artisan.py`
- [Application coordinator](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/main.py): Qt application controller · Owns startup, settings, windows, and roast operations. · `src/artisanlib/main.py`
- [Roast canvas](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/canvas.py): interactive Qt view · Renders the live roast graph and visual scope. · `src/artisanlib/canvas.py`
- [Operational dialogs](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/dialogs.py): Qt dialogs · `src/artisanlib/dialogs.py`
- [Setup widget](https://github.com/artisan-roaster-scope/artisan/blob/master/src/ui/SetupWidget.ui): Qt Designer UI · `src/ui/SetupWidget.ui`

### Device Integration

- [Communications core](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/comm.py): device I/O boundary · Coordinates ports and non-blocking acquisition. · `src/artisanlib/comm.py`
- [Async transport](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/async_comm.py): asynchronous I/O · `src/artisanlib/async_comm.py`
- [Port abstraction](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/ports.py): connection manager · `src/artisanlib/ports.py`
- [Protocol transports](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/modbusport.py): Modbus · S7 · MQTT · WebSocket · BLE · Phidgets · `src/artisanlib/modbusport.py`
- [Roaster adapters](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/giesen.py): vendor machine adapters · Maps machine protocols to readings and controls. · `src/artisanlib/giesen.py`
- [Machine presets](https://github.com/artisan-roaster-scope/artisan/blob/master/src/includes/Machines/Giesen/W15A.aset): setup assets · `src/includes/Machines/Giesen/W15A.aset`

### Roast Session

- [Events and phases](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/events.py): session workflow · `src/artisanlib/events.py`
- [Signal processing](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/filters.py): filters and curves · Cleans samples and derives roast metrics. · `src/artisanlib/filters.py`
- [Alarms](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/alarms.py): automation rules · `src/artisanlib/alarms.py`
- [PID control](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/pid_control.py): setpoint controller · Converts process values and setpoints into machine commands. · `src/artisanlib/pid_control.py`

### Profiles & Services

- [Profile persistence](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/roastlog.py): roast logs and paths · Loads, saves, transforms, and exports roast profiles. · `src/artisanlib/roastlog.py`
- [Third-party importers](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisanlib/cropster.py): profile adapters · `src/artisanlib/cropster.py`
- [Report templates](https://github.com/artisan-roaster-scope/artisan/blob/master/src/includes/report-template.htm): HTML assets · `src/includes/report-template.htm`
- [Artisan Plus](https://github.com/artisan-roaster-scope/artisan/blob/master/src/plus/controller.py): optional cloud domain · Provides authentication, sync, and business objects outside the local roast runtime. · `src/plus/controller.py`

### Distribution Assets

- [Runtime assets](https://github.com/artisan-roaster-scope/artisan/tree/master/src/translations): translations, themes, wheels, help · `src/translations`
- [Platform packaging](https://github.com/artisan-roaster-scope/artisan/blob/master/src/artisan-win.spec): PyInstaller and install scripts · Builds Windows, macOS, Linux, and Raspberry Pi distributions. · `src/artisan-win.spec`

## Connections

- Application entry → Application coordinator: launches
- Application coordinator → Roast canvas: drives
- Application coordinator → Operational dialogs: opens
- Operational dialogs → Setup widget: uses
- Application coordinator → Communications core: starts acquisition
- Communications core → Async transport: uses
- Communications core → Port abstraction: manages
- Port abstraction → Protocol transports: connects through
- Protocol transports → Roaster adapters: supports
- Machine presets → Roaster adapters: configures
- Communications core → Signal processing: sampled values
- Signal processing → Roast canvas: derived curves
- Events and phases → Roast canvas: annotates
- Application coordinator → Events and phases: records operations
- Signal processing → Alarms: monitors values
- Alarms → PID control: triggers actions
- PID control → Communications core: issues commands
- Events and phases → Profile persistence: records profile
- Profile persistence → Third-party importers: imports formats
- Profile persistence → Report templates: renders reports
- Application coordinator → Artisan Plus: optional integration
- Platform packaging → Application entry: bundles
- Platform packaging → Runtime assets: includes
