# jeanloickdt/instantiot-server architecture

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

- Interactive diagram: https://gitdiagram.com/jeanloickdt/instantiot-server
- Repository: https://github.com/jeanloickdt/instantiot-server

## Overview

InstantIoT is a self-hosted IoT relay and web-admin server. Its primary workflow is a board connecting over TCP and sending signal values, which the server relays to app WebSockets and stores as time-series history; authenticated users manage projects, devices, and signals through the admin/API, while automation can react to relay events. The README documents discovery, backups, and multi-tier history. The graph uses those documented relationships plus the shown source references; some runtime wiring and unsampled implementation details are intentionally omitted.

Main entry points: [`src/main/kotlin/com/jeanloickdt/Application.kt`](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/Application.kt) (Ktor server), [`src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt`](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt) (Automation engine), [`src/main/kotlin/com/jeanloickdt/relay/DeviceRelay.kt`](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/DeviceRelay.kt) (Device TCP relay), [`src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt`](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt) (Signal ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and access"]
  node_serverapp["Ktor server<br/>[Application.kt]"]
  node_auth["Accounts and JWT<br/>[AuthRoutes.kt]"]
  node_users[("User storage")]
end

subgraph group_assets["Projects and signals"]
  node_projects["Projects<br/>[ProjectRoutes.kt]"]
  node_projectstore[("Project storage")]
  node_devices["Device management<br/>[DeviceRoutes.kt]"]
  node_devicestore[("Device storage")]
  node_signals["Signal API<br/>[SignalRoutes.kt]"]
  node_history[("Signal history")]
end

subgraph group_relay["Live relay"]
  node_tcp["Device TCP relay<br/>[DeviceRelay.kt]"]
  node_ingest["Signal ingest<br/>[SignalIngest.kt]"]
  node_connections["Connection registry"]
  node_ws["App WebSocket relay<br/>[AppRelay.kt]"]
  node_eventbus["Relay event sinks<br/>[EventSinks.kt]"]
end

subgraph group_automation["Rules and actions"]
  node_rulesapi["Rule management<br/>[RuleRoutes.kt]"]
  node_engine["Automation engine"]
  node_runs[("Automation runs<br/>[AutomationRuns.kt]")]
  node_delivery["Action delivery<br/>[DeliveryWorker.kt]"]
end

subgraph group_operations["Operations"]
  node_discovery["LAN discovery<br/>[MdnsPublisher.kt]"]
  node_backups["Database backups<br/>[BackupManager.kt]"]
  node_database[("SQLite database<br/>[DatabaseFactory.kt]")]
end

node_admin(("Admin user"))
node_board(("IoT board"))
node_mobile(("InstantIoT app"))

node_admin -->|"uses admin panel"| node_serverapp
node_mobile -->|"uses server"| node_serverapp
node_board -->|"sends TCP frames"| node_tcp
node_serverapp -->|"configures"| node_auth
node_auth -->|"reads and writes"| node_users
node_serverapp -->|"registers routes"| node_projects
node_projects -->|"accesses projects"| node_projectstore
node_serverapp -->|"registers routes"| node_devices
node_devices -->|"accesses devices"| node_devicestore
node_serverapp -->|"registers routes"| node_signals
node_signals -->|"queries history"| node_history
node_tcp -.->|"dispatches values"| node_ingest
node_ingest -.->|"stores samples"| node_history
node_tcp -.->|"registers sessions"| node_connections
node_ws -.->|"uses sessions"| node_connections
node_ws -->|"relays live values"| node_mobile
node_ingest -->|"publishes events"| node_eventbus
node_eventbus -->|"provides events"| node_engine
node_serverapp -.->|"registers routes"| node_rulesapi
node_rulesapi -->|"configures rules"| node_engine
node_engine -->|"records runs"| node_runs
node_engine -->|"dispatches actions"| node_delivery
node_serverapp -.->|"starts discovery"| node_discovery
node_serverapp -.->|"starts backup service"| node_backups
node_backups -->|"snapshots database"| node_database
node_serverapp -->|"initializes storage"| node_database

click node_serverapp "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/Application.kt"
click node_auth "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/auth/AuthRoutes.kt"
click node_users "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/auth/data/SqliteUserRepository.kt"
click node_projects "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/project/ProjectRoutes.kt"
click node_projectstore "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/project/data/ExposedProjectRepository.kt"
click node_devices "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/device/DeviceRoutes.kt"
click node_devicestore "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/device/data/ExposedDeviceRepository.kt"
click node_signals "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/SignalRoutes.kt"
click node_history "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/data/ExposedSignalHistoryRepository.kt"
click node_tcp "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/DeviceRelay.kt"
click node_ingest "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt"
click node_connections "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/ConnectionRegistry.kt"
click node_ws "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/AppRelay.kt"
click node_eventbus "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/event/EventSinks.kt"
click node_rulesapi "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/RuleRoutes.kt"
click node_engine "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt"
click node_runs "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/v2/AutomationRuns.kt"
click node_delivery "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/DeliveryWorker.kt"
click node_discovery "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/discovery/MdnsPublisher.kt"
click node_backups "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/backup/BackupManager.kt"
click node_database "https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/database/DatabaseFactory.kt"

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_serverapp,node_auth,node_users,node_admin toneBlue
class node_projects,node_projectstore,node_devices,node_devicestore,node_signals,node_history toneAmber
class node_tcp,node_ingest,node_connections,node_ws,node_eventbus toneMint
class node_rulesapi,node_engine,node_runs,node_delivery toneRose
class node_discovery,node_backups,node_database,node_board,node_mobile toneIndigo
```

## Components

### Server and access

- [Ktor server](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/Application.kt): `src/main/kotlin/com/jeanloickdt/Application.kt`
- [Accounts and JWT](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/auth/AuthRoutes.kt): `src/main/kotlin/com/jeanloickdt/auth/AuthRoutes.kt`
- [User storage](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/auth/data/SqliteUserRepository.kt): `src/main/kotlin/com/jeanloickdt/auth/data/SqliteUserRepository.kt`

### Projects and signals

- [Projects](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/project/ProjectRoutes.kt): `src/main/kotlin/com/jeanloickdt/project/ProjectRoutes.kt`
- [Project storage](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/project/data/ExposedProjectRepository.kt): `src/main/kotlin/com/jeanloickdt/project/data/ExposedProjectRepository.kt`
- [Device management](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/device/DeviceRoutes.kt): `src/main/kotlin/com/jeanloickdt/device/DeviceRoutes.kt`
- [Device storage](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/device/data/ExposedDeviceRepository.kt): `src/main/kotlin/com/jeanloickdt/device/data/ExposedDeviceRepository.kt`
- [Signal API](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/SignalRoutes.kt): `src/main/kotlin/com/jeanloickdt/signal/SignalRoutes.kt`
- [Signal history](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/data/ExposedSignalHistoryRepository.kt): `src/main/kotlin/com/jeanloickdt/signal/data/ExposedSignalHistoryRepository.kt`

### Live relay

- [Device TCP relay](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/DeviceRelay.kt): `src/main/kotlin/com/jeanloickdt/relay/DeviceRelay.kt`
- [Signal ingest](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt): `src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt`
- [Connection registry](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/ConnectionRegistry.kt): `src/main/kotlin/com/jeanloickdt/relay/ConnectionRegistry.kt`
- [App WebSocket relay](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/relay/AppRelay.kt): `src/main/kotlin/com/jeanloickdt/relay/AppRelay.kt`
- [Relay event sinks](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/event/EventSinks.kt): `src/main/kotlin/com/jeanloickdt/event/EventSinks.kt`

### Rules and actions

- [Rule management](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/RuleRoutes.kt): `src/main/kotlin/com/jeanloickdt/automation/RuleRoutes.kt`
- [Automation engine](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt): `src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt`
- [Automation runs](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/v2/AutomationRuns.kt): `src/main/kotlin/com/jeanloickdt/automation/v2/AutomationRuns.kt`
- [Action delivery](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/automation/DeliveryWorker.kt): `src/main/kotlin/com/jeanloickdt/automation/DeliveryWorker.kt`

### Operations

- [LAN discovery](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/discovery/MdnsPublisher.kt): `src/main/kotlin/com/jeanloickdt/discovery/MdnsPublisher.kt`
- [Database backups](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/backup/BackupManager.kt): `src/main/kotlin/com/jeanloickdt/backup/BackupManager.kt`
- [SQLite database](https://github.com/jeanloickdt/instantiot-server/blob/main/src/main/kotlin/com/jeanloickdt/database/DatabaseFactory.kt): `src/main/kotlin/com/jeanloickdt/database/DatabaseFactory.kt`

### Other components

- **Admin user**
- **IoT board**
- **InstantIoT app**

## Connections

- Admin user → Ktor server: uses admin panel (evidence: `README.md`)
- InstantIoT app → Ktor server: uses server (evidence: `README.md`)
- IoT board → Device TCP relay: sends TCP frames (evidence: `README.md`)
- Ktor server → Accounts and JWT: configures (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Accounts and JWT → User storage: reads and writes
- Ktor server → Projects: registers routes (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Projects → Project storage: accesses projects (evidence: `src/main/kotlin/com/jeanloickdt/project/ProjectRoutes.kt`)
- Ktor server → Device management: registers routes (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Device management → Device storage: accesses devices (evidence: `src/main/kotlin/com/jeanloickdt/device/DeviceRoutes.kt`)
- Ktor server → Signal API: registers routes (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Signal API → Signal history: queries history (evidence: `src/main/kotlin/com/jeanloickdt/signal/SignalRoutes.kt`)
- Device TCP relay → Signal ingest: dispatches values
- Signal ingest → Signal history: stores samples
- Device TCP relay → Connection registry: registers sessions
- App WebSocket relay → Connection registry: uses sessions
- App WebSocket relay → InstantIoT app: relays live values (evidence: `README.md`)
- Signal ingest → Relay event sinks: publishes events (evidence: `src/main/kotlin/com/jeanloickdt/signal/SignalIngest.kt`)
- Relay event sinks → Automation engine: provides events (evidence: `src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt`)
- Ktor server → Rule management: registers routes
- Rule management → Automation engine: configures rules (evidence: `src/main/kotlin/com/jeanloickdt/automation/RuleRoutes.kt`)
- Automation engine → Automation runs: records runs (evidence: `src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt`)
- Automation engine → Action delivery: dispatches actions (evidence: `src/main/kotlin/com/jeanloickdt/automation/v2/AutomationEngine.kt`)
- Ktor server → LAN discovery: starts discovery (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Ktor server → Database backups: starts backup service (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
- Database backups → SQLite database: snapshots database (evidence: `src/main/kotlin/com/jeanloickdt/backup/BackupManager.kt`)
- Ktor server → SQLite database: initializes storage (evidence: `src/main/kotlin/com/jeanloickdt/Application.kt`)
