System Processes & Interactions

This section describes the technical data flows between the Hardware (E-Paper), Frontend, and Backend using sequence diagrams to illustrate the exact timing and order of operations.

1. Display Usage

Dynamic Content Rendering (Office vs. Event)

The system automatically determines the layout based on the room’s schedule. The DisplayController orchestrates the logic, deciding whether to invoke the “Event” or “Office” renderer mode based on database state.

Endpoints: GET /v1/display/content Headers: X-Mac-Address, X-API-Key

sequenceDiagram
    participant HW as E-Paper Display
    participant MW as Auth Middleware
    participant CTRL as DisplayController
    participant DB as Database (Postgres/SQLite)
    participant SVC as RendererService
    participant PY as Python Script (render.py)

    Note over HW, CTRL: Periodic Poll (e.g., every 5-15 min)
    HW->>MW: GET /display/content<br/>(Headers: X-Mac-Address, X-API-Key)
    MW->>DB: Query Display by MAC
    DB-->>MW: Return Display & Hashed Key

    alt Invalid Key
        MW-->>HW: 401 Unauthorized
    else Valid Key
        MW->>CTRL: Forward Request (Display Context)

        CTRL->>DB: GetEventsInDateRange(Now, Now)
        DB-->>CTRL: Return []Event

        alt Event Active (List not empty)
            CTRL->>SVC: RenderEventImage(Event Data)
        else Room Free (List empty)
            CTRL->>DB: GetRoomUsers(RoomUUID)
            DB-->>CTRL: Return []RoomUser + Descriptions
            CTRL->>SVC: RenderOfficeImage(Users, RoomInfo)
        end

        SVC->>PY: Execute Shell Command<br/>(python -m epaper_rendering.render ...)
        Note right of SVC: Arguments passed as JSON string
        PY-->>SVC: Stdout: Base64 PNG String
        SVC-->>CTRL: Return Image Data

        CTRL-->>HW: 200 OK (Body: Base64 Image)
    end

Cleaning Confirmation via QR Code

Facility managers scan a QR code generated on the e-paper to confirm cleaning. The CheckInController handles validation and audit logging.

Endpoints: POST /v1/checkin

sequenceDiagram
    participant User as Facility Manager
    participant FE as Mobile Web App
    participant CTRL as CheckInController
    participant DB as Database

    User->>FE: Scans QR Code
    FE->>CTRL: POST /v1/checkin<br/>{ "qr_code_uuid": "..." }

    CTRL->>DB: GetQRCode(uuid)
    DB-->>CTRL: Return QRCode Struct

    alt Token Expired or Invalid (ValidUntil < Now)
        CTRL-->>FE: 400 Bad Request
    else Token Valid
        Note right of CTRL: 1. Update Room Status
        CTRL->>DB: UpdateCleaningStatus(RoomUUID)<br/>Set LastCleanedAt = Now

        Note right of CTRL: 2. Create Audit Log
        CTRL->>DB: CreateCheckIn(User, Room, Task)

        CTRL-->>FE: 200 OK
        FE-->>User: Show Success Message
    end

Here are the system processes (QR Code Generation, Device Onboarding, etc.) rewritten to match the exact short style and detailed sequence diagram format of your “Cleaning Confirmation” example.

QR Code Generation

The RendererService dynamically generates check-in tokens during the image rendering process. If a task is scheduled but no active token exists, the service creates a new QRCode entry in the database and passes the URL to the Python script for visual embedding.

Trigger: Internal (during GET /displays/{uuid}/content)

sequenceDiagram
    participant SVC as RendererService
    participant DB as Database
    participant PY as Python Script
    participant LIB as QR Library (Python)

    Note over SVC: Rendering Process Started
    SVC->>DB: GetTasksForToday(RoomUUID)
    DB-->>SVC: Return Task List

    alt Task Exists
        SVC->>DB: GetActiveQRCode()

        alt No Valid Code Found
            SVC->>DB: CreateTemporaryQRCode()<br/>(Valid: 24h)
            DB-->>SVC: Return New UUID
        end

        SVC->>SVC: Generate URL string<br/>/checkin/{uuid}
    else No Tasks
        SVC->>SVC: Generate Static Room URL
    end

    Note over SVC, PY: Pass Data to Renderer
    SVC->>PY: Stdin: { "qr_data": "https://..." }

    PY->>LIB: Generate QR Image from String
    LIB-->>PY: Return Base64 PNG

    PY->>PY: Embed in HTML Template
    PY-->>SVC: Return Final E-Paper Image

---

2. Administration & Setup

Process: Device Onboarding

Onboarding connects a physical device to a logical Room. The DisplayController handles secure API key generation during the creation process.

Endpoints: POST /v1/displays

sequenceDiagram
    participant Admin as Admin User
    participant FE as Admin Dashboard
    participant CTRL as DisplayController
    participant DB as Database

    Admin->>FE: Enters MAC, Hardware Type, Room
    FE->>CTRL: POST /v1/displays

    CTRL->>CTRL: Validate MAC Address Format
    CTRL->>CTRL: generateSecureKey() (crypto/rand)

    CTRL->>DB: Insert Display Record<br/>(Store API Key)
    DB-->>CTRL: Success

    CTRL-->>FE: 201 Created<br/>Return { "api_key": "raw-key-..." }

    Note over FE: Key is shown ONLY once
    FE-->>Admin: Display API Key
    Admin->>Admin: Manually configures Device

Process: Data Synchronization

The system uses a Polling Architecture. Changes to room metadata (e.g., renaming a room) are propagated to the display asynchronously during the next scheduled poll.

Endpoints: PUT /v1/rooms/{uuid}

sequenceDiagram
    participant Manager as Room Manager
    participant BE as Backend API
    participant HW as E-Paper Display

    Note over Manager, BE: 1. Update Data
    Manager->>BE: Rename Room to "Conference A"
    BE->>BE: Save to Database
    BE-->>Manager: Update Successful

    Note over BE, HW: 2. Async Propagation
    Note over HW: Device Sleeps...

    HW->>BE: Poll: "Give me content"
    BE->>BE: Generate Image with NEW Name
    BE-->>HW: Return Updated Image