# ruderigo/labuche-stump architecture

> Architecture diagram of the GitHub repository ruderigo/labuche-stump, 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/ruderigo/labuche-stump
- Repository: https://github.com/ruderigo/labuche-stump
- Video tour (about a minute): https://gitdiagram.com/ruderigo/labuche-stump/video

## Overview

Project Stump is an off-grid community node split across a WiFi-connected CAM hub and a low-power Heltec mesh control plane. A walk-up visitor joins the local network, reaches the web server, and uses chat, rooms, files, bulletin-board content, and project information; chat can also bridge to Reticulum/LXMF peers over LoRa. The README documents access profiles, multilingual pages, direct messages, plugins, and firmware delivery. Some subsystems are represented from README descriptions because their source was not sampled; uncertain internal wiring is omitted.

Main entry points: [`final_firmware/barkeep.py`](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/barkeep.py) (HTTP server and router), [`final_firmware/example_node.py`](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/example_node.py) (Hub assembly), [`final_firmware/rrc.py`](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc.py) (Chat and rooms), [`final_firmware/rrc_mesh.py`](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc_mesh.py) (Chat mesh bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Hub startup"]
  node_main["Boot entry<br/>[main.py]"]
  node_boot_common["Boot retry logic<br/>[boot_common.py]"]
  node_example_node["Hub assembly<br/>[example_node.py]"]
  node_config["Node configuration<br/>[config.py]"]
end

subgraph group_web["Local web experience"]
  node_barkeep["HTTP server and router<br/>[barkeep.py]"]
  node_portal["Captive portal<br/>[captive_portal.py]"]
  node_i18n["Language support<br/>[i18n.py]"]
  node_flasher_ui["Firmware page<br/>[flasher_ui.py]"]
end

subgraph group_community["Community services"]
  node_rrc["Chat and rooms<br/>[rrc.py]"]
  node_rrc_ui["Chat interface<br/>[rrc_ui.py]"]
  node_rrc_mesh["Chat mesh bridge<br/>[rrc_mesh.py]"]
  node_billboard["Bulletin board<br/>[billboard.py]"]
  node_fserv["Files and downloads<br/>[fserv.py]"]
  node_fservbot["Chat bot<br/>[core.py]"]
end

subgraph group_mesh["Encrypted mesh"]
  node_reticulum["Reticulum routing<br/>[reticulum.py]"]
  node_transport["Packet transport<br/>[transport.py]"]
  node_lora["LoRa interface<br/>[lora.py]"]
  node_lxmf["LXMF messaging<br/>[lxmf.py]"]
  node_node_common["Identity and router setup<br/>[node_common.py]"]
end

subgraph group_identity["Identity and access"]
  node_stumpid["Access and identity<br/>[core.py]"]
end

node_visitor(("Phone visitor"))
node_cam["CAM hub"]
node_heltec["Heltec radio node"]
node_mesh_peer(("Mesh peer"))
node_sd[("SD storage")]

node_main -->|"starts boot"| node_boot_common
node_boot_common -->|"boots module"| node_example_node
node_example_node -->|"loads settings"| node_config
node_example_node -->|"starts server"| node_barkeep
node_example_node -->|"initializes chat"| node_rrc
node_example_node -->|"sets up mesh"| node_node_common
node_visitor -->|"joins WiFi"| node_cam
node_cam -->|"provides onboarding"| node_portal
node_visitor -->|"requests pages"| node_barkeep
node_barkeep -->|"handles chat"| node_rrc
node_barkeep -->|"serves interface"| node_rrc_ui
node_barkeep -->|"serves board"| node_billboard
node_barkeep -->|"serves files"| node_fserv
node_barkeep -->|"renders firmware page"| node_flasher_ui
node_barkeep -->|"translates content"| node_i18n
node_rrc -->|"checks access"| node_stumpid
node_rrc -->|"dispatches bot input"| node_fservbot
node_rrc_mesh -->|"bridges chat"| node_rrc
node_rrc_mesh -->|"sends mesh messages"| node_lxmf
node_node_common -->|"initializes routing"| node_reticulum
node_reticulum -->|"routes packets"| node_transport
node_transport -->|"sends radio traffic"| node_lora
node_lora -->|"transmits LoRa"| node_heltec
node_heltec -->|"exchanges packets"| node_mesh_peer
node_billboard -->|"reads and writes"| node_sd
node_fserv -->|"reads and writes"| node_sd
node_fservbot -->|"persists settings"| node_sd

click node_main "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/main.py"
click node_boot_common "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/boot_common.py"
click node_example_node "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/example_node.py"
click node_config "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/config.py"
click node_barkeep "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/barkeep.py"
click node_portal "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/captive_portal.py"
click node_i18n "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/i18n.py"
click node_flasher_ui "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/flasher_ui.py"
click node_rrc "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc.py"
click node_rrc_ui "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc_ui.py"
click node_rrc_mesh "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc_mesh.py"
click node_billboard "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/billboard.py"
click node_fserv "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/fserv.py"
click node_fservbot "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/fservbot/core.py"
click node_reticulum "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/reticulum.py"
click node_transport "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/transport.py"
click node_lora "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/interfaces/lora.py"
click node_lxmf "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/lxmf.py"
click node_node_common "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/node_common.py"
click node_stumpid "https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/stumpid/core.py"

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_main,node_boot_common,node_example_node,node_config toneBlue
class node_barkeep,node_portal,node_i18n,node_flasher_ui,node_sd toneAmber
class node_rrc,node_rrc_ui,node_rrc_mesh,node_billboard,node_fserv,node_fservbot toneMint
class node_reticulum,node_transport,node_lora,node_lxmf,node_node_common toneRose
class node_stumpid,node_visitor,node_cam,node_heltec,node_mesh_peer toneIndigo
```

## Components

### Hub startup

- [Boot entry](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/main.py): `final_firmware/main.py`
- [Boot retry logic](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/boot_common.py): `final_firmware/boot_common.py`
- [Hub assembly](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/example_node.py): `final_firmware/example_node.py`
- [Node configuration](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/config.py): `final_firmware/config.py`

### Local web experience

- [HTTP server and router](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/barkeep.py): `final_firmware/barkeep.py`
- [Captive portal](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/captive_portal.py): `final_firmware/captive_portal.py`
- [Language support](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/i18n.py): `final_firmware/i18n.py`
- [Firmware page](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/flasher_ui.py): `final_firmware/flasher_ui.py`

### Community services

- [Chat and rooms](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc.py): `final_firmware/rrc.py`
- [Chat interface](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc_ui.py): `final_firmware/rrc_ui.py`
- [Chat mesh bridge](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/rrc_mesh.py): `final_firmware/rrc_mesh.py`
- [Bulletin board](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/billboard.py): `final_firmware/billboard.py`
- [Files and downloads](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/fserv.py): `final_firmware/fserv.py`
- [Chat bot](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/fservbot/core.py): `final_firmware/fservbot/core.py`

### Encrypted mesh

- [Reticulum routing](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/reticulum.py): `final_firmware/urns/reticulum.py`
- [Packet transport](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/transport.py): `final_firmware/urns/transport.py`
- [LoRa interface](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/interfaces/lora.py): `final_firmware/urns/interfaces/lora.py`
- [LXMF messaging](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/urns/lxmf.py): `final_firmware/urns/lxmf.py`
- [Identity and router setup](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/node_common.py): `final_firmware/node_common.py`

### Identity and access

- [Access and identity](https://github.com/ruderigo/labuche-stump/blob/main/final_firmware/stumpid/core.py): `final_firmware/stumpid/core.py`

### Other components

- **Phone visitor**
- **CAM hub**
- **Heltec radio node**
- **Mesh peer**
- **SD storage**

## Connections

- Boot entry → Boot retry logic: starts boot
- Boot retry logic → Hub assembly: boots module
- Hub assembly → Node configuration: loads settings
- Hub assembly → HTTP server and router: starts server
- Hub assembly → Chat and rooms: initializes chat
- Hub assembly → Identity and router setup: sets up mesh
- Phone visitor → CAM hub: joins WiFi
- CAM hub → Captive portal: provides onboarding
- Phone visitor → HTTP server and router: requests pages
- HTTP server and router → Chat and rooms: handles chat
- HTTP server and router → Chat interface: serves interface
- HTTP server and router → Bulletin board: serves board
- HTTP server and router → Files and downloads: serves files
- HTTP server and router → Firmware page: renders firmware page
- HTTP server and router → Language support: translates content
- Chat and rooms → Access and identity: checks access
- Chat and rooms → Chat bot: dispatches bot input
- Chat mesh bridge → Chat and rooms: bridges chat
- Chat mesh bridge → LXMF messaging: sends mesh messages
- Identity and router setup → Reticulum routing: initializes routing
- Reticulum routing → Packet transport: routes packets
- Packet transport → LoRa interface: sends radio traffic
- LoRa interface → Heltec radio node: transmits LoRa
- Heltec radio node → Mesh peer: exchanges packets
- Bulletin board → SD storage: reads and writes
- Files and downloads → SD storage: reads and writes
- Chat bot → SD storage: persists settings