# luk707/trmnl-server architecture

> Architecture diagram of the GitHub repository luk707/trmnl-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luk707/trmnl-server
- Repository: https://github.com/luk707/trmnl-server
- Video tour (about a minute): https://gitdiagram.com/luk707/trmnl-server/video

## Overview

trmnl-server is a Rust BYOS server for TRMNL devices. Devices register through setup to receive an API key, then request display responses while reporting status; management endpoints list devices, retrieve device details, and get or update image rotations. The API also accepts device logs, though the README says they are not persisted. The sampled setup and display handlers show repository-backed device registration and status updates; management handler internals were not sampled, so their persistence links are not inferred.

Main entry points: [`src/app.rs`](https://github.com/luk707/trmnl-server/blob/main/src/app.rs) (Route Table), [`src/main.rs`](https://github.com/luk707/trmnl-server/blob/main/src/main.rs) (Server Startup), [`src/repositories/device/mod.rs`](https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/mod.rs) (Device Repository), [`src/repositories/device/sqlite.rs`](https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/sqlite.rs) (SQLite Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["Route Table<br/>[app.rs]"]
end

subgraph group_device["Device Workflow"]
  node_setup["Device Setup<br/>[setup.rs]"]
  node_display["Display Request<br/>[display.rs]"]
  node_log["Device Logs<br/>[log.rs]"]
end

subgraph group_management["Management API"]
  node_list_devices["List Devices<br/>[list_devices.rs]"]
  node_get_device["Device Details<br/>[get_device.rs]"]
  node_get_images["Read Images"]
  node_put_images["Update Images"]
end

subgraph group_runtime["Runtime And Persistence"]
  node_config["Server Settings<br/>[config.rs]"]
  node_repo_layer["Repository Injection<br/>[device.rs]"]
  node_device_repo["Device Repository<br/>[mod.rs]"]
  node_sqlite_repo["SQLite Adapter<br/>[sqlite.rs]"]
  node_db_setup["Database Setup<br/>[db.rs]"]
  node_sqlite[("Device Database")]
  node_server["Server Startup<br/>[main.rs]"]
end

node_device_actor(("TRMNL Device"))
node_manager_actor(("Management Client"))

node_device_actor -->|"sends requests"| node_app
node_manager_actor -->|"sends requests"| node_app
node_app -->|"routes setup"| node_setup
node_app -->|"routes display"| node_display
node_app -->|"routes logs"| node_log
node_app -->|"routes listing"| node_list_devices
node_app -->|"routes details"| node_get_device
node_app -->|"routes image reads"| node_get_images
node_app -->|"routes image updates"| node_put_images
node_server -->|"loads settings"| node_config
node_server -->|"starts router"| node_app
node_server -->|"installs layer"| node_repo_layer
node_server -->|"connects and migrates"| node_db_setup
node_repo_layer -->|"constructs adapter"| node_sqlite_repo
node_setup -->|"checks and creates device"| node_device_repo
node_display -->|"looks up and updates status"| node_device_repo
node_device_repo -->|"implemented by"| node_sqlite_repo
node_sqlite_repo -->|"reads and writes"| node_sqlite
node_db_setup -->|"initializes"| node_sqlite
node_server -->|"serves requests for"| node_device_actor

click node_app "https://github.com/luk707/trmnl-server/blob/main/src/app.rs"
click node_setup "https://github.com/luk707/trmnl-server/blob/main/src/handlers/setup.rs"
click node_display "https://github.com/luk707/trmnl-server/blob/main/src/handlers/display.rs"
click node_log "https://github.com/luk707/trmnl-server/blob/main/src/handlers/log.rs"
click node_list_devices "https://github.com/luk707/trmnl-server/blob/main/src/handlers/list_devices.rs"
click node_get_device "https://github.com/luk707/trmnl-server/blob/main/src/handlers/get_device.rs"
click node_get_images "https://github.com/luk707/trmnl-server/blob/main/src/handlers/get_device_images.rs"
click node_put_images "https://github.com/luk707/trmnl-server/blob/main/src/handlers/put_device_images.rs"
click node_config "https://github.com/luk707/trmnl-server/blob/main/src/config.rs"
click node_repo_layer "https://github.com/luk707/trmnl-server/blob/main/src/layers/device.rs"
click node_device_repo "https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/mod.rs"
click node_sqlite_repo "https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/sqlite.rs"
click node_db_setup "https://github.com/luk707/trmnl-server/blob/main/src/db.rs"
click node_server "https://github.com/luk707/trmnl-server/blob/main/src/main.rs"

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_app,node_manager_actor toneBlue
class node_setup,node_display,node_log toneAmber
class node_list_devices,node_get_device,node_get_images,node_put_images toneMint
class node_config,node_repo_layer,node_device_repo,node_sqlite_repo,node_db_setup,node_sqlite,node_server toneRose
class node_device_actor toneIndigo
```

## Components

### HTTP API

- [Route Table](https://github.com/luk707/trmnl-server/blob/main/src/app.rs): `src/app.rs`

### Device Workflow

- [Device Setup](https://github.com/luk707/trmnl-server/blob/main/src/handlers/setup.rs): `src/handlers/setup.rs`
- [Display Request](https://github.com/luk707/trmnl-server/blob/main/src/handlers/display.rs): `src/handlers/display.rs`
- [Device Logs](https://github.com/luk707/trmnl-server/blob/main/src/handlers/log.rs): `src/handlers/log.rs`

### Management API

- [List Devices](https://github.com/luk707/trmnl-server/blob/main/src/handlers/list_devices.rs): `src/handlers/list_devices.rs`
- [Device Details](https://github.com/luk707/trmnl-server/blob/main/src/handlers/get_device.rs): `src/handlers/get_device.rs`
- [Read Images](https://github.com/luk707/trmnl-server/blob/main/src/handlers/get_device_images.rs): `src/handlers/get_device_images.rs`
- [Update Images](https://github.com/luk707/trmnl-server/blob/main/src/handlers/put_device_images.rs): `src/handlers/put_device_images.rs`

### Runtime And Persistence

- [Server Settings](https://github.com/luk707/trmnl-server/blob/main/src/config.rs): `src/config.rs`
- [Repository Injection](https://github.com/luk707/trmnl-server/blob/main/src/layers/device.rs): `src/layers/device.rs`
- [Device Repository](https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/mod.rs): `src/repositories/device/mod.rs`
- [SQLite Adapter](https://github.com/luk707/trmnl-server/blob/main/src/repositories/device/sqlite.rs): `src/repositories/device/sqlite.rs`
- [Database Setup](https://github.com/luk707/trmnl-server/blob/main/src/db.rs): `src/db.rs`
- **Device Database**
- [Server Startup](https://github.com/luk707/trmnl-server/blob/main/src/main.rs): `src/main.rs`

### Other components

- **TRMNL Device**
- **Management Client**

## Connections

- TRMNL Device → Route Table: sends requests
- Management Client → Route Table: sends requests
- Route Table → Device Setup: routes setup
- Route Table → Display Request: routes display
- Route Table → Device Logs: routes logs
- Route Table → List Devices: routes listing
- Route Table → Device Details: routes details
- Route Table → Read Images: routes image reads
- Route Table → Update Images: routes image updates
- Server Startup → Server Settings: loads settings
- Server Startup → Route Table: starts router
- Server Startup → Repository Injection: installs layer
- Server Startup → Database Setup: connects and migrates
- Repository Injection → SQLite Adapter: constructs adapter
- Device Setup → Device Repository: checks and creates device
- Display Request → Device Repository: looks up and updates status
- Device Repository → SQLite Adapter: implemented by
- SQLite Adapter → Device Database: reads and writes
- Database Setup → Device Database: initializes
- Server Startup → TRMNL Device: serves requests for