# jeanloickdt/instantiot architecture

> Architecture diagram of the GitHub repository jeanloickdt/instantiot, 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
- Repository: https://github.com/jeanloickdt/instantiot

## Overview

InstantIoT is an Arduino library that connects a board to the InstantIoT app. A sketch starts a link and optional destination, services the connection in `loop()`, sends addressed values, and handles app-originated signals or control gestures through file-scope DSL blocks. Internally, the facade delegates protocol work to the core, which encodes frames and uses a platform-selected transport. The README documents multiple link modes, TLS, replayed state, rate limiting, diagnostics, and timers. Some transport wiring is visible only through the source index; unsampled internals are not inferred.

Main entry points: [`src/core/InstantIoTCore.hpp`](https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTCore.hpp) (Runtime core), [`src/core/Transport.h`](https://github.com/jeanloickdt/instantiot/blob/main/src/core/Transport.h) (Transport interface), [`src/Links.hpp`](https://github.com/jeanloickdt/instantiot/blob/main/src/Links.hpp) (Link selection), [`src/transport/wifi`](https://github.com/jeanloickdt/instantiot/tree/main/src/transport/wifi) (Wi-Fi transports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Sketch API"]
  node_facade["InstantIoT facade<br/>[InstantIoT.h]"]
  node_dsl["Event DSL<br/>[InstantIoTWhen.hpp]"]
  node_timer["Timers"]
end

subgraph group_protocol["Signals and protocol"]
  node_core["Runtime core<br/>[InstantIoTCore.hpp]"]
  node_codec["Binary codec<br/>[BinaryCodec.hpp]"]
  node_signals["Signal model"]
  node_events["Event dispatch<br/>[SignalEvents.hpp]"]
  node_widgetmap["Signal mapping<br/>[SignalToWidget.hpp]"]
  node_messages["Protocol messages"]
  node_deviceconfig["Device config"]
  node_sender["Message sender<br/>[MessageSender.h]"]
end

subgraph group_connectivity["Links and transports"]
  node_links["Link selection<br/>[Links.hpp]"]
  node_destinations["Destinations<br/>[Destinations.hpp]"]
  node_transport["Transport interface<br/>[Transport.h]"]
  node_session["TCP session<br/>[TcpSession.hpp]"]
  node_wifi["Wi-Fi transports"]
  node_ethernet["Ethernet transports"]
  node_wireless["Bluetooth transports"]
  node_serial["Serial transports"]
end

subgraph group_support["Runtime support"]
  node_config["Platform config<br/>[InstantIoTConfig.h]"]
  node_roots["TLS trust roots"]
  node_debug["Connection diagnostics"]
end

node_sketch(("Arduino sketch"))
node_app(("InstantIoT app"))
node_server(("Cloud or hosted server"))

node_sketch -->|"starts and calls"| node_facade
node_facade -->|"delegates runtime"| node_core
node_sketch -->|"declares handlers"| node_dsl
node_sketch -->|"schedules callbacks"| node_timer
node_facade -->|"selects link"| node_links
node_facade -->|"accepts destination"| node_destinations
node_links -->|"combines link and destination"| node_destinations
node_links -->|"selects platform transport"| node_wifi
node_links -->|"selects platform transport"| node_ethernet
node_links -->|"selects Bluetooth transport"| node_wireless
node_links -->|"selects serial transport"| node_serial
node_wifi -->|"uses TCP session"| node_session
node_ethernet -->|"uses TCP session"| node_session
node_session -->|"implements interface"| node_transport
node_wifi -->|"implements interface"| node_transport
node_wireless -->|"implements interface"| node_transport
node_serial -->|"implements interface"| node_transport
node_core -->|"polls and transfers frames"| node_transport
node_core -->|"encodes and decodes"| node_codec
node_core -->|"uses signal model"| node_signals
node_core -->|"dispatches incoming events"| node_events
node_events -->|"uses signal definitions"| node_signals
node_dsl -->|"maps incoming signals"| node_widgetmap
node_widgetmap -->|"uses message types"| node_messages
node_core -->|"processes messages"| node_messages
node_core -->|"uses device config"| node_deviceconfig
node_core -->|"uses sender"| node_sender
node_config -->|"configures runtime limits"| node_core
node_roots -->|"provides TLS trust roots"| node_wifi
node_wifi -->|"reports Wi-Fi reasons"| node_debug
node_app -->|"sends values and gestures"| node_server
node_server -->|"replays stored state"| node_app
node_app -.->|"exchanges app frames"| node_transport
node_transport -->|"connects to destination"| node_server
node_server -.->|"delivers frames"| node_transport
node_transport -->|"returns received bytes"| node_core
node_core -->|"invokes handlers"| node_sketch

click node_facade "https://github.com/jeanloickdt/instantiot/blob/main/src/InstantIoT.h"
click node_dsl "https://github.com/jeanloickdt/instantiot/blob/main/src/utils/InstantIoTWhen.hpp"
click node_timer "https://github.com/jeanloickdt/instantiot/blob/main/src/utils/InstantIoTTimer.hpp"
click node_core "https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTCore.hpp"
click node_codec "https://github.com/jeanloickdt/instantiot/blob/main/src/core/BinaryCodec.hpp"
click node_signals "https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTSignals.hpp"
click node_events "https://github.com/jeanloickdt/instantiot/blob/main/src/core/SignalEvents.hpp"
click node_widgetmap "https://github.com/jeanloickdt/instantiot/blob/main/src/core/SignalToWidget.hpp"
click node_messages "https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTMessage.hpp"
click node_deviceconfig "https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTDeviceConfig.hpp"
click node_sender "https://github.com/jeanloickdt/instantiot/blob/main/src/core/MessageSender.h"
click node_config "https://github.com/jeanloickdt/instantiot/blob/main/src/InstantIoTConfig.h"
click node_links "https://github.com/jeanloickdt/instantiot/blob/main/src/Links.hpp"
click node_destinations "https://github.com/jeanloickdt/instantiot/blob/main/src/Destinations.hpp"
click node_transport "https://github.com/jeanloickdt/instantiot/blob/main/src/core/Transport.h"
click node_session "https://github.com/jeanloickdt/instantiot/blob/main/src/transport/TcpSession.hpp"
click node_wifi "https://github.com/jeanloickdt/instantiot/tree/main/src/transport/wifi"
click node_ethernet "https://github.com/jeanloickdt/instantiot/tree/main/src/transport/ethernet"
click node_wireless "https://github.com/jeanloickdt/instantiot/tree/main/src/transport/bluetooth"
click node_serial "https://github.com/jeanloickdt/instantiot/tree/main/src/transport/serial"
click node_roots "https://github.com/jeanloickdt/instantiot/blob/main/src/certs/InstantIoT_LE_Roots.h"
click node_debug "https://github.com/jeanloickdt/instantiot/blob/main/src/transport/wifi/WiFiReason_ESP32.hpp"

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_facade,node_dsl,node_timer toneBlue
class node_core,node_codec,node_signals,node_events,node_widgetmap,node_messages,node_deviceconfig,node_sender toneAmber
class node_links,node_destinations,node_transport,node_session,node_wifi,node_ethernet,node_wireless,node_serial,node_server toneMint
class node_config,node_roots,node_debug toneRose
class node_sketch,node_app toneIndigo
```

## Components

### Sketch API

- [InstantIoT facade](https://github.com/jeanloickdt/instantiot/blob/main/src/InstantIoT.h): `src/InstantIoT.h`
- [Event DSL](https://github.com/jeanloickdt/instantiot/blob/main/src/utils/InstantIoTWhen.hpp): `src/utils/InstantIoTWhen.hpp`
- [Timers](https://github.com/jeanloickdt/instantiot/blob/main/src/utils/InstantIoTTimer.hpp): `src/utils/InstantIoTTimer.hpp`

### Signals and protocol

- [Runtime core](https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTCore.hpp): `src/core/InstantIoTCore.hpp`
- [Binary codec](https://github.com/jeanloickdt/instantiot/blob/main/src/core/BinaryCodec.hpp): `src/core/BinaryCodec.hpp`
- [Signal model](https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTSignals.hpp): `src/core/InstantIoTSignals.hpp`
- [Event dispatch](https://github.com/jeanloickdt/instantiot/blob/main/src/core/SignalEvents.hpp): `src/core/SignalEvents.hpp`
- [Signal mapping](https://github.com/jeanloickdt/instantiot/blob/main/src/core/SignalToWidget.hpp): `src/core/SignalToWidget.hpp`
- [Protocol messages](https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTMessage.hpp): `src/core/InstantIoTMessage.hpp`
- [Device config](https://github.com/jeanloickdt/instantiot/blob/main/src/core/InstantIoTDeviceConfig.hpp): `src/core/InstantIoTDeviceConfig.hpp`
- [Message sender](https://github.com/jeanloickdt/instantiot/blob/main/src/core/MessageSender.h): `src/core/MessageSender.h`

### Links and transports

- [Link selection](https://github.com/jeanloickdt/instantiot/blob/main/src/Links.hpp): `src/Links.hpp`
- [Destinations](https://github.com/jeanloickdt/instantiot/blob/main/src/Destinations.hpp): `src/Destinations.hpp`
- [Transport interface](https://github.com/jeanloickdt/instantiot/blob/main/src/core/Transport.h): `src/core/Transport.h`
- [TCP session](https://github.com/jeanloickdt/instantiot/blob/main/src/transport/TcpSession.hpp): `src/transport/TcpSession.hpp`
- [Wi-Fi transports](https://github.com/jeanloickdt/instantiot/tree/main/src/transport/wifi): `src/transport/wifi`
- [Ethernet transports](https://github.com/jeanloickdt/instantiot/tree/main/src/transport/ethernet): `src/transport/ethernet`
- [Bluetooth transports](https://github.com/jeanloickdt/instantiot/tree/main/src/transport/bluetooth): `src/transport/bluetooth`
- [Serial transports](https://github.com/jeanloickdt/instantiot/tree/main/src/transport/serial): `src/transport/serial`

### Runtime support

- [Platform config](https://github.com/jeanloickdt/instantiot/blob/main/src/InstantIoTConfig.h): `src/InstantIoTConfig.h`
- [TLS trust roots](https://github.com/jeanloickdt/instantiot/blob/main/src/certs/InstantIoT_LE_Roots.h): `src/certs/InstantIoT_LE_Roots.h`
- [Connection diagnostics](https://github.com/jeanloickdt/instantiot/blob/main/src/transport/wifi/WiFiReason_ESP32.hpp): `src/transport/wifi/WiFiReason_ESP32.hpp`

### Other components

- **Arduino sketch**
- **InstantIoT app**
- **Cloud or hosted server**

## Connections

- Arduino sketch → InstantIoT facade: starts and calls (evidence: `README.md`)
- InstantIoT facade → Runtime core: delegates runtime (evidence: `src/InstantIoT.h`)
- Arduino sketch → Event DSL: declares handlers (evidence: `README.md`)
- Arduino sketch → Timers: schedules callbacks (evidence: `README.md`)
- InstantIoT facade → Link selection: selects link (evidence: `src/InstantIoT.h`)
- InstantIoT facade → Destinations: accepts destination (evidence: `src/InstantIoT.h`)
- Link selection → Destinations: combines link and destination (evidence: `src/Links.hpp`)
- Link selection → Wi-Fi transports: selects platform transport (evidence: `src/Links.hpp`)
- Link selection → Ethernet transports: selects platform transport (evidence: `src/Links.hpp`)
- Link selection → Bluetooth transports: selects Bluetooth transport (evidence: `src/Links.hpp`)
- Link selection → Serial transports: selects serial transport (evidence: `src/Links.hpp`)
- Wi-Fi transports → TCP session: uses TCP session (evidence: `src/transport/wifi/TlsClient_ESP8266.hpp`)
- Ethernet transports → TCP session: uses TCP session (evidence: `src/transport/ethernet/EthClient_W5x00.hpp`)
- TCP session → Transport interface: implements interface (evidence: `src/transport/TcpSession.hpp`)
- Wi-Fi transports → Transport interface: implements interface (evidence: `src/transport/wifi/TlsClient_ESP32.hpp`)
- Bluetooth transports → Transport interface: implements interface (evidence: `src/transport/bluetooth/BLE_ESP32.hpp`)
- Serial transports → Transport interface: implements interface (evidence: `src/transport/serial/HardSerial.hpp`)
- Runtime core → Transport interface: polls and transfers frames (evidence: `src/core/InstantIoTCore.hpp`)
- Runtime core → Binary codec: encodes and decodes (evidence: `src/core/InstantIoTCore.hpp`)
- Runtime core → Signal model: uses signal model (evidence: `src/core/InstantIoTCore.hpp`)
- Runtime core → Event dispatch: dispatches incoming events (evidence: `src/core/InstantIoTCore.hpp`)
- Event dispatch → Signal model: uses signal definitions (evidence: `src/core/SignalEvents.hpp`)
- Event DSL → Signal mapping: maps incoming signals (evidence: `src/utils/InstantIoTWhen.hpp`)
- Signal mapping → Protocol messages: uses message types (evidence: `src/core/SignalToWidget.hpp`)
- Runtime core → Protocol messages: processes messages (evidence: `src/core/InstantIoTCore.hpp`)
- Runtime core → Device config: uses device config (evidence: `src/core/InstantIoTCore.hpp`)
- Runtime core → Message sender: uses sender (evidence: `src/core/InstantIoTCore.hpp`)
- Platform config → Runtime core: configures runtime limits (evidence: `src/core/InstantIoTCore.hpp`)
- TLS trust roots → Wi-Fi transports: provides TLS trust roots (evidence: `src/certs/InstantIoT_LE_Roots.h`)
- Wi-Fi transports → Connection diagnostics: reports Wi-Fi reasons (evidence: `src/transport/wifi/TlsClient_ESP32.hpp`)
- InstantIoT app → Cloud or hosted server: sends values and gestures (evidence: `README.md`)
- Cloud or hosted server → InstantIoT app: replays stored state (evidence: `README.md`)
- InstantIoT app → Transport interface: exchanges app frames
- Transport interface → Cloud or hosted server: connects to destination (evidence: `README.md`)
- Cloud or hosted server → Transport interface: delivers frames
- Transport interface → Runtime core: returns received bytes (evidence: `src/core/Transport.h`)
- Runtime core → Arduino sketch: invokes handlers (evidence: `README.md`)
