# labbots/niimprintx architecture

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

- Interactive diagram: https://gitdiagram.com/labbots/niimprintx
- Repository: https://github.com/labbots/niimprintx

## Overview

##### Project Type and Purpose
- NiimPrintX is a cross-platform Python desktop application and library that provides both a Command-Line Interface (CLI) and a Graphical User Interface (GUI) for designing and printing labels on NiimBot Bluetooth printers.
- It wraps low-level Bluetooth protocols and printer-specific packet formats in a “nimmy” core, and exposes high-level commands (CLI) and interactive design widgets (GUI).

##### File Structure
Top-level directories and their roles:
- NiimPrintX/cli: Entry point for the CLI, using Click for command dispatch (info, print).
- NiimPrintX/nimmy: Core library for printer connectivity, packet construction, Bluetooth I/O, error handling, logging.
- bin, docs, assets/images: Supporting scripts (e.g., image preprocessing), documentation, sample media.
- spec_files and .github/workflows: Build/deployment definitions for Windows, macOS, Linux (PyInstaller specs, CI workflows).

##### README for Additional Insights
- Confirms Python 3.12+, ImageMagick dependency, Poetry for packaging.
- Highlights two user-facing interfaces (CLI and GUI), Bluetooth connectivity, supported printer models, and advanced print settings.

##### Main Components & Their Relationships
a. User Interfaces
- CLI App (NiimPrintX.cli)
- GUI App (NiimPrintX.ui)
b. Core Library
- Printer Abstraction Layer (nimmy.printer)
- Packet Builder (nimmy.packet)
- Bluetooth Transport (nimmy.bluetooth)
- Helpers (nimmy.helper) and Logging (nimmy.logger_config)
c. External Dependencies
- ImageMagick (image processing)
- Bluetooth stack (OS-level/Bluetooth library)
d. Target Hardware
- NiimBot printers (models D11, B21, B1, D110, B18)

##### Architectural Patterns & Design Principles
- Layered architecture: UI/CLI → Core Library → Transport → Hardware
- Single Responsibility: Each nimmy submodule focuses on one aspect (packet, transport, printer model).
- Modularity: CLI and GUI are thin presentation layers reusing the same core.
- Cross-platform packaging via PyInstaller specs and CI workflows.

##### Detailed Coverage
- Build pipeline: GitHub Actions → PyInstaller specs → platform installers.
- Helper scripts (bin/process_png.py) as part of the image-prep sub-flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::hardware
        CLI["CLI Application\n(Click: Click, Python 3.12)"]:::presentation
        GUI["GUI Application\n(Click: Qt(Tk), Python 3.12)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        CommandDispatcher["Command Dispatcher\n(NiimPrintX/cli/command.py)"]:::application
        UIControllers["UI Controllers\n(AppConfig, Main, Splash, Widgets)"]:::application
    end

    %% Core Library
    subgraph "Core Library (nimmy)"
        direction TB
        Printer["nimmy.printer"]:::core
        Packet["nimmy.packet"]:::core
        BluetoothCore["nimmy.bluetooth"]:::core
        Helper["nimmy.helper"]:::core
        Logger["nimmy.logger_config"]:::core
        Exception["nimmy.exception"]:::core
        InitCore["nimmy/__init__.py"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ImageMagick["ImageMagick\n(image processing)"]:::external
        BluetoothStack["OS Bluetooth Stack\n(RFCOMM/BLE)"]:::external
        ProcessPNG["Image Prep Script\n(bin/process_png.py)"]:::external
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Printers["NiimBot Printers\n(D11, B21, B1, D110, B18)"]:::hardware
    end

    %% CI/Build Pipeline
    subgraph "Build & CI"
        direction TB
        Workflows["GitHub Actions Workflows\n(.github/workflows/)"]:::external
        SpecsCLI["PyInstaller Specs CLI\n(spec_files/cli_app/)"]:::external
        SpecsGUI["PyInstaller Specs GUI\n(spec_files/ui_app/)"]:::external
        Docs["Documentation\n(docs/)"]:::external
        Samples["Sample Images\n(assets/images/)"]:::external
    end

    %% Connections
    User -->|"runs"| CLI
    User -->|"runs"| GUI
    CLI -->|"dispatch commands"| CommandDispatcher
    GUI -->|"interacts with"| UIControllers
    CommandDispatcher -->|"calls Core API"| Printer
    UIControllers -->|"calls Core API"| Packet
    Printer -->|"uses"| BluetoothCore
    Packet -->|"formats data"| Helper
    Helper -->|"logs through"| Logger
    Exception -->|"handles errors in"| Printer
    Packet -->|"image transforms"| ImageMagick
    BluetoothCore -->|"uses"| BluetoothStack
    BluetoothStack -->|"connects to"| Printers
    ProcessPNG -->|"prepares images for"| ImageMagick
    Workflows -->|"generate installers via"| SpecsCLI
    Workflows -->|"generate installers via"| SpecsGUI
    SpecsCLI -->|"produce"| CLI
    SpecsGUI -->|"produce"| GUI

    %% Click Events
    click CLI "https://github.com/labbots/niimprintx/tree/main/NiimPrintX/cli"
    click CLI "https://github.com/labbots/niimprintx/tree/main/__main__" "NiimPrintX/cli/__main__.py"
    click CommandDispatcher "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/cli/command.py"
    click GUI "https://github.com/labbots/niimprintx/tree/main/NiimPrintX/ui"
    click AppConfig "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/ui/AppConfig.py"
    click MainLauncher "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/ui/main.py"
    click Splash "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/ui/SplashScreen.py"
    click GUIEntry "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/ui/__main__.py"
    click WidgetDir "https://github.com/labbots/niimprintx/tree/main/NiimPrintX/ui/widget/"
    click ComponentDir "https://github.com/labbots/niimprintx/tree/main/NiimPrintX/ui/component/"
    click IconICNS "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/ui/assets/icon.icns"
    click IconsDir "https://github.com/labbots/niimprintx/tree/main/NiimPrintX/ui/icons/"
    click Printer "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/printer.py"
    click Packet "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/packet.py"
    click BluetoothCore "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/bluetooth.py"
    click Helper "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/helper.py"
    click Logger "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/logger_config.py"
    click Exception "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/exception.py"
    click InitCore "https://github.com/labbots/niimprintx/blob/main/NiimPrintX/nimmy/__init__.py"
    click ProcessPNG "https://github.com/labbots/niimprintx/blob/main/bin/process_png.py"
    click Docs "https://github.com/labbots/niimprintx/tree/main/docs/"
    click Samples "https://github.com/labbots/niimprintx/tree/main/assets/images/"
    click Workflows "https://github.com/labbots/niimprintx/blob/main/.github/workflows/_build-linux.yaml"
    click SpecsCLI "https://github.com/labbots/niimprintx/blob/main/spec_files/cli_app/NiimPrintX-linux.spec"
    click SpecsCLI "https://github.com/labbots/niimprintx/blob/main/spec_files/cli_app/NiimPrintX-mac.spec"
    click SpecsCLI "https://github.com/labbots/niimprintx/blob/main/spec_files/cli_app/NiimPrintX-windows.spec"
    click SpecsGUI "https://github.com/labbots/niimprintx/blob/main/spec_files/ui_app/NiimPrintX-linux.spec"
    click SpecsGUI "https://github.com/labbots/niimprintx/blob/main/spec_files/ui_app/NiimPrintX-mac.spec"
    click SpecsGUI "https://github.com/labbots/niimprintx/blob/main/spec_files/ui_app/NiimPrintX-windows.spec"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#0366d6,color:#0366d6;
    classDef application fill:#e6f7ff,stroke:#0050b3,color:#0050b3;
    classDef core fill:#ccffcc,stroke:#237804,color:#237804;
    classDef external fill:#ffe5cc,stroke:#fa8c16,color:#d46b08;
    classDef hardware fill:#e0e0e0,stroke:#595959,color:#262626;
```
