# owulveryck/gomarkablestream architecture

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

- Interactive diagram: https://gitdiagram.com/owulveryck/gomarkablestream
- Repository: https://github.com/owulveryck/gomarkablestream

## Overview

##### Main Components
- Server/Backend (Go executable):
- HTTP Server: Handles various endpoints such as:
- “/” – serving the main web interface.
- “/stream” – where the image data stream is served.
- “/events” – WebSocket endpoint for real-time pen input events.
- “/gestures” – for touch/gesture events.
- “/version” – to check the software version.
- Authentication & Configuration: Code in auth.go and configuration via environment variables (e.g., RK_SERVER_BIND_ADDR, RK_SERVER_USERNAME, etc.).
- Internal Modules: Modularized under the “internal” folder:
- Event HTTP Handlers (internal/eventhttphandler): Separates pen and gesture event processing.
- Streaming: Contains logic for reading the display memory, processing (e.g., raw, RLE, or ZSTD compression), and sending image data.
- reMarkable Device Handling: Under internal/remarkable, which abstracts device/user interactions, screen grabbing, and event detection.
- PubSub: Used for event/message communication between different parts of the backend.
- Compression Algorithms: The RLE (and optionally ZSTD) modules handle image compression.
- Client/Frontend:
- Browser-side Code: Found in the “client” directory, which includes HTML (index.html), JavaScript modules (for canvas handling, WebGL rendering, capturing UI interactions, worker scripts for event and stream processing), and CSS styling.
- User Interface: Handles extra features such as live parameter tweaking (screen rotation, dark/light mode) and embedding presentations for live annotation.

##### Establish Relationships and Interactions
- Requests flow from the Browser Client (user interface) to the Go server via HTTP endpoints:
- The “/stream” endpoint delivers the processed image data, while “/events” and “/gestures” manage user interactions.
- Internal modules communicate using a pub/sub mechanism to coordinate event handling, streaming, and compression.
- The server itself directly interacts with the underlying reMarkable hardware to capture screen data and input events.
- Configuration (via environment variables) [RK_HTTPS, RK_COMPRESSION, etc.] dynamically influences how the server processes streams and events.
- A build and deployment workflow is supported by the provided Makefile, GitHub Actions (in .github/workflows), and optional systemd service scripts (e.g., in tools/service) for persistent deployment on the device.

##### Recognize Architectural Patterns
- Modular Monolith: The application is physically packaged as a single unit while internally organized into modules (e.g., for streaming, events, device interaction).
- Client-Server Separation: Despite being bundled together for deployment on the tablet, there is a clear separation between the backend server and the lightweight client rendering UI in the browser.
- Pub/Sub Pattern: Used to decouple components for event notification within the backend.
- Compression & Performance Optimization: Custom implementations (RLE in “internal/rle”) for minimizing the data transferred from the device to the browser.

##### Technologies and Frameworks
- Go (Golang): As the primary language for the server.
- Web technologies: HTML, JavaScript (including canvas and WebGL) for the client-side.
- WebSocket: For real-time event communication.
- GitHub Actions: For CI/CD workflows.
- Systemd: For running as a service on the reMarkable device.
- Compression Libraries/Techniques: Custom RLE (and optionally ZSTD).

##### Elements
- Labels/Components:
- “HTTP Server” (possibly with sub-labels for each endpoint: /, /stream, /events, /gestures, /version)
- “Authentication & Configuration Module”
- “Device Interaction Module (reMarkable Handler)”
- “Streaming & Compression Module”
- “Pub/Sub Communication”
- “Client/Browser (HTML/JS/WebGL UI)”

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Server/Backend"
        HTTP_Server("HTTP Server (/ , /stream, /events, /gestures, /version)"):::backend
        Auth_Config("Authentication & Configuration Module"):::backend
        Event_Handlers("Event HTTP Handlers"):::backend
            Pen_Handler("Pen Handler"):::backend
            Gesture_Handler("Gesture Handler"):::backend
        Streaming("Streaming & Compression Module"):::backend
            RLE("RLE Compression"):::backend
            ZSTD("ZSTD Compression"):::backend
        Remarkable("reMarkable Device Interaction Module"):::backend
        PubSub("Pub/Sub Communication"):::backend
    end

    subgraph "Client Layer"
        Client_UI("Client Browser UI (HTML/JS/WebGL)"):::frontend
    end

    %% Client to Server connections
    Client_UI -->|"HTTP/WebSocketRequests"| HTTP_Server

    %% Internal Server Module Relationships
    HTTP_Server -->|"configuredby"| Auth_Config
    HTTP_Server -->|"handlesEvents"| Event_Handlers
    HTTP_Server -->|"streamsData"| Streaming
    Streaming -->|"receivesScreenDataFrom"| Remarkable
    Event_Handlers -->|"pubsubComm"| PubSub
    Streaming -->|"pubsubComm"| PubSub

    %% Breakdown of Event Handlers
    Event_Handlers -->|"penEvents"| Pen_Handler
    Event_Handlers -->|"gestureEvents"| Gesture_Handler

    %% Breakdown of Streaming & Compression
    Streaming -->|"compression"| RLE
    Streaming -->|"compression"| ZSTD

    %% Click Events
    click HTTP_Server "https://github.com/owulveryck/gomarkablestream/blob/main/main.go"
    click Auth_Config "https://github.com/owulveryck/gomarkablestream/blob/main/auth.go"
    click Pen_Handler "https://github.com/owulveryck/gomarkablestream/blob/main/internal/eventhttphandler/pen_handler.go"
    click Gesture_Handler "https://github.com/owulveryck/gomarkablestream/blob/main/internal/eventhttphandler/gesture_handler.go"
    click Streaming "https://github.com/owulveryck/gomarkablestream/blob/main/internal/stream/handler.go"
    click RLE "https://github.com/owulveryck/gomarkablestream/blob/main/internal/rle/rle.go"
    click ZSTD "https://github.com/owulveryck/gomarkablestream/blob/main/zstd.go"
    click Remarkable "https://github.com/owulveryck/gomarkablestream/blob/main/internal/remarkable/device.go"
    click PubSub "https://github.com/owulveryck/gomarkablestream/blob/main/internal/pubsub/pubsub.go"
    click Client_UI "https://github.com/owulveryck/gomarkablestream/blob/main/client/index.html"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
```
