# bigjk/snd architecture

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

- Interactive diagram: https://gitdiagram.com/bigjk/snd
- Repository: https://github.com/bigjk/snd

## Overview

##### Overall Printing Pipeline
- The project centers on quickly converting customizable templates into printed outputs for a thermal printer. The rendering/printing process is composed of several clearly defined stages:
- Template definition and data binding using HTML/CSS and the Nunjucks templating language.
- Conversion of these templates (with injected data) into rendered HTML.
- Conversion of the rendered HTML into an image using the Chrome headless browser (via the Chrome Debugging Protocol).
- Transformation of the image into printer-specific commands (ESC/POS commands).
- Dispatching these commands to various printer drivers (Windows direct printing, USB, CUPS for Linux/macOS, Serial, etc.).

##### Out the Key Components Based on the File Tree
- Templating:
- Files in the frontend directory (for example, HTML/CSS and JavaScript under frontend/src) include code related to template creation and template rendering.
- The extensive usage of Nunjucks is referred to in the README and is likely embedded in JavaScript routines (e.g., templating-related modules under frontend/src/js/core/templating.ts).
- Rendering Engine:
- The conversion from HTML to an image is managed via the Chrome Debug Protocol. Although the detailed implementation is hidden, the “rendering” package (database/rendering/rendering.go) is our core component.
- Command Conversion:
- After the image is generated, a specific module converts it to ESC/POS compatible commands.
- This conversion is performed as part of the printing pipeline and may involve function calls inside the rendering or printing directories.
- Printer Drivers and Protocols:
- The printing folder hosts several printer communication methods. For example:
- printing/windows/* (for Windows Direct Printing)
- printing/usb/* (for raw USB printing)
- printing/cups/* (for Linux/macOS using CUPS)
- printing/serial/* (for serial connection)
- Other folders such as printing/remote and printing/rsnd support additional printing use cases.
- Communication and RPC:
- The rpc directory shows several endpoints (like rpc/print.go, rpc/image_utility.go, etc.) that likely manage the communication between the frontend/backend components, calling the rendering and printing modules.

##### Detailing the Rendering/Printing Process

a. Template Management & Nunjucks Templating
- Input: User-selected or community templates (HTML/CSS files found in the frontend folder)
- Process: Data is inserted using Nunjucks to produce complete HTML pages.
b. HTML Rendering Engine
- Process: Render the HTML using a headless Chrome instance (invoked via Chrome Debug Protocol tactics)
- Outcome: A fully rendered image ready for conversion.
c. Image-to-ESC/POS Converter
- Process: The rendered image is processed and converted to commands that conform to the ESC/POS specification. This acts as the bridge from rendering to physical printing.
d. Printing Subsystem (with multiple possible drivers)
- Components:
- Windows Direct (printing/windows)
- USB (printing/usb and cmd/app/libusb.go)
- CUPS (printing/cups)
- Serial (printing/serial)
- Additional drivers like remote and rsnd.
- Process: Routes the ESC/POS commands to the hardware based on the detected or specified printing method.
e. Communication / RPC Layer
- Components: Services in the rpc directory that orchestrate the entire process starting from UI command to the eventual printing.
- Role: Provide asynchronous or synchronous calls between the frontend UI and the backend printing engine.

– Ensure each component (Template Engine, Renderer, Converter, Drivers, RPC interface) is clearly labeled.
1. From Template Engine → HTML Renderer.
2. From HTML Renderer → Image Converter (HTML-to-image using Chrome).
3. From Converter → ESC/POS Command Generator.
4. From Command Generator → Printer Drivers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Template & Rendering Layer"
        A["User Input / Template Selection"]:::templating
        B["HTML Templates"]:::templating
        C["Nunjucks Template Engine"]:::templating
        D["HTML Renderer (Chrome Headless)"]:::rendering
    end
    A --> B
    B --> C
    C --> D

    subgraph "Conversion Layer"
        F["Image Generator"]:::converter
        G["ESC/POS Command Converter"]:::converter
    end
    D --> F
    F --> G

    subgraph "Printing Drivers Layer"
        P1["Windows Direct Printing"]:::printer
        P2["USB Printing (Raw)"]:::printer
        P3["USB LibUSB"]:::printer
        P4["CUPS Printing"]:::printer
        P5["Serial Printing"]:::printer
        P6["Remote Printing"]:::printer
        P7["RSND Printing"]:::printer
    end
    G --> P1
    G --> P2
    G --> P3
    G --> P4
    G --> P5
    G --> P6
    G --> P7

    subgraph "RPC Communication Layer"
        L["RPC / Status Manager"]:::rpc
    end
    P1 -- "Feedback" --> L
    P2 -- "Feedback" --> L
    P3 -- "Feedback" --> L
    P4 -- "Feedback" --> L
    P5 -- "Feedback" --> L
    P6 -- "Feedback" --> L
    P7 -- "Feedback" --> L

    %% Click Events
    click B "https://github.com/bigjk/snd/blob/master/frontend/src/index.html"
    click C "https://github.com/bigjk/snd/blob/master/frontend/src/js/core/templating.ts"
    click D "https://github.com/bigjk/snd/blob/master/rendering/rendering.go"
    click P1 "https://github.com/bigjk/snd/blob/master/printing/windows/direct.go"
    click P2 "https://github.com/bigjk/snd/blob/master/printing/usb/usb.go"
    click P3 "https://github.com/bigjk/snd/blob/master/cmd/app/libusb.go"
    click P4 "https://github.com/bigjk/snd/blob/master/printing/cups/cups.go"
    click P5 "https://github.com/bigjk/snd/blob/master/printing/serial/serial.go"
    click P6 "https://github.com/bigjk/snd/blob/master/printing/remote/remote.go"
    click P7 "https://github.com/bigjk/snd/blob/master/printing/rsnd/rsnd.go"
    click L "https://github.com/bigjk/snd/blob/master/rpc/print.go"

    %% Styles
    classDef templating fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef rendering fill:#87CEFA,stroke:#000,stroke-width:1px;
    classDef converter fill:#F0E68C,stroke:#000,stroke-width:1px;
    classDef printer fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef rpc fill:#90EE90,stroke:#000,stroke-width:1px;
```
