# matrixbox-dev/matrixbox architecture

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

- Interactive diagram: https://gitdiagram.com/matrixbox-dev/matrixbox
- Repository: https://github.com/matrixbox-dev/matrixbox

## Overview

MatrixBOX is CircuitPython firmware for a programmable LED-matrix device, with a built-in web interface and a collection of device apps. The main workflow loads settings, initializes the display and network, serves a home page, then launches the selected app; users can also configure Wi-Fi and device settings remotely. Departures is a substantial standalone app with its own settings, data-processing, rendering, skin and web layers. The graph reflects documented and indexed relationships; unsampled app implementations are represented by their exact source paths, without inferred internal call chains.

Main entry points: [`main.py`](https://github.com/matrixbox-dev/matrixbox/blob/main/main.py) (Runtime Loop), [`apps/departures/functions.py`](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/functions.py) (Departure Processing), [`apps/departures/varinit.py`](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/varinit.py) (Departures State), [`apps/departures/web.py`](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/web.py) (Departures Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware Core"]
  node_main["Runtime Loop<br/>[main.py]"]
  node_boot["Boot Setup<br/>[boot.py]"]
  node_settings["Settings<br/>[load_settings.py]"]
  node_display["Matrix Display<br/>[load_screen.py]"]
  node_fonts["Display Fonts<br/>[font_large.py]"]
  node_button["Button Input<br/>[check_button.py]"]
end

subgraph group_web["Web And Network"]
  node_http["HTTP Router<br/>[ampule.py]"]
  node_webui["Device Web UI<br/>[web_interface.py]"]
  node_wifi["Wi-Fi Manager<br/>[wlan.py]"]
  node_filemanager["File Manager<br/>[filemanager.py]"]
  node_ai["AI Assistant<br/>[ai_agent.py]"]
  node_requests["HTTP Client"]
  node_connection["Socket Manager"]
end

subgraph group_apps["Device Apps"]
  node_clock["Clock<br/>[code.py]"]
  node_paint["Paint<br/>[code.py]"]
  node_weather["Weather<br/>[code.py]"]
  node_stocks["Stocks<br/>[code.py]"]
  node_lastfm["Last.fm<br/>[code.py]"]
  node_screensaver["Screensavers<br/>[code.py]"]
  node_otherapps["Other Official Apps"]
end

subgraph group_departures["Departures App"]
  node_depentry["Departures App Entry<br/>[code.py]"]
  node_depstate["Departures State<br/>[varinit.py]"]
  node_depdata["Departure Processing<br/>[functions.py]"]
  node_depdicts["Transit Data And Text<br/>[dicts.py]"]
  node_deprender["Display Rendering<br/>[createhtml.py]"]
  node_depskins["Skin Loader<br/>[skinloader.py]"]
  node_depweb["Departures Web UI<br/>[web.py]"]
end

node_owner(("Device User"))
node_transit(("Transit Service"))

node_owner -->|"operates"| node_main
node_main -->|"loads settings"| node_settings
node_main -->|"uses display"| node_display
node_main -->|"checks input"| node_button
node_main -->|"connects network"| node_wifi
node_main -->|"loads interface"| node_webui
node_main -->|"registers routes"| node_http
node_boot -->|"loads settings"| node_settings
node_display -->|"renders text"| node_fonts
node_webui -->|"registers routes"| node_http
node_webui -->|"loads manager"| node_filemanager
node_webui -->|"calls assistant"| node_ai
node_wifi -->|"registers routes"| node_http
node_main -->|"gets SSL context"| node_connection
node_main -->|"creates session"| node_requests
node_main -->|"launches app"| node_clock
node_main -->|"launches app"| node_paint
node_main -->|"launches app"| node_weather
node_main -->|"launches app"| node_stocks
node_main -->|"launches app"| node_lastfm
node_main -->|"selects saver"| node_screensaver
node_main -.->|"loads selected app"| node_otherapps
node_main -.->|"launches app"| node_depentry
node_depentry -.->|"initializes state"| node_depstate
node_depstate -->|"imports processing"| node_depdata
node_depstate -->|"loads dictionaries"| node_depdicts
node_depdata -->|"uses settings"| node_depstate
node_depdata -->|"uses rendering"| node_deprender
node_depdata -.->|"uses text data"| node_depdicts
node_depdata -.->|"retrieves departures"| node_transit
node_depentry -.->|"serves app UI"| node_depweb
node_depweb -->|"uses settings"| node_depstate
node_depweb -->|"uses processing"| node_depdata
node_depweb -->|"uses dictionaries"| node_depdicts
node_depweb -->|"loads skins"| node_depskins
node_deprender -->|"uses state"| node_depstate
node_deprender -->|"uses processing"| node_depdata
node_deprender -->|"uses skins"| node_depskins

click node_main "https://github.com/matrixbox-dev/matrixbox/blob/main/main.py"
click node_boot "https://github.com/matrixbox-dev/matrixbox/blob/main/boot.py"
click node_settings "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/load_settings.py"
click node_display "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/load_screen.py"
click node_fonts "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/font_large.py"
click node_button "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/check_button.py"
click node_http "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/ampule.py"
click node_webui "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/web_interface.py"
click node_wifi "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/wlan.py"
click node_filemanager "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/filemanager.py"
click node_ai "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/ai_agent.py"
click node_requests "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/adafruit_requests.py"
click node_connection "https://github.com/matrixbox-dev/matrixbox/blob/main/lib/adafruit_connection_manager.py"
click node_clock "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/clock/code.py"
click node_paint "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/paint/code.py"
click node_weather "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/weather/code.py"
click node_stocks "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/stocks/code.py"
click node_lastfm "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/lastfm/code.py"
click node_screensaver "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/screensaver/code.py"
click node_otherapps "https://github.com/matrixbox-dev/matrixbox/tree/main/apps"
click node_depentry "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/code.py"
click node_depstate "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/varinit.py"
click node_depdata "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/functions.py"
click node_depdicts "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/dicts.py"
click node_deprender "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/createhtml.py"
click node_depskins "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/skinloader.py"
click node_depweb "https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/web.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,node_settings,node_display,node_fonts,node_button,node_owner toneBlue
class node_http,node_webui,node_wifi,node_filemanager,node_ai,node_requests,node_connection toneAmber
class node_clock,node_paint,node_weather,node_stocks,node_lastfm,node_screensaver,node_otherapps toneMint
class node_depentry,node_depstate,node_depdata,node_depdicts,node_deprender,node_depskins,node_depweb toneRose
class node_transit toneIndigo
```

## Components

### Firmware Core

- [Runtime Loop](https://github.com/matrixbox-dev/matrixbox/blob/main/main.py): `main.py`
- [Boot Setup](https://github.com/matrixbox-dev/matrixbox/blob/main/boot.py): `boot.py`
- [Settings](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/load_settings.py): `lib/load_settings.py`
- [Matrix Display](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/load_screen.py): `lib/load_screen.py`
- [Display Fonts](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/font_large.py): `lib/font_large.py`
- [Button Input](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/check_button.py): `lib/check_button.py`

### Web And Network

- [HTTP Router](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/ampule.py): `lib/ampule.py`
- [Device Web UI](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/web_interface.py): `lib/web_interface.py`
- [Wi-Fi Manager](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/wlan.py): `lib/wlan.py`
- [File Manager](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/filemanager.py): `lib/filemanager.py`
- [AI Assistant](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/ai_agent.py): `lib/ai_agent.py`
- [HTTP Client](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/adafruit_requests.py): `lib/adafruit_requests.py`
- [Socket Manager](https://github.com/matrixbox-dev/matrixbox/blob/main/lib/adafruit_connection_manager.py): `lib/adafruit_connection_manager.py`

### Device Apps

- [Clock](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/clock/code.py): `apps/clock/code.py`
- [Paint](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/paint/code.py): `apps/paint/code.py`
- [Weather](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/weather/code.py): `apps/weather/code.py`
- [Stocks](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/stocks/code.py): `apps/stocks/code.py`
- [Last.fm](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/lastfm/code.py): `apps/lastfm/code.py`
- [Screensavers](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/screensaver/code.py): `apps/screensaver/code.py`
- [Other Official Apps](https://github.com/matrixbox-dev/matrixbox/tree/main/apps): `apps`

### Departures App

- [Departures App Entry](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/code.py): `apps/departures/code.py`
- [Departures State](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/varinit.py): `apps/departures/varinit.py`
- [Departure Processing](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/functions.py): `apps/departures/functions.py`
- [Transit Data And Text](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/dicts.py): `apps/departures/dicts.py`
- [Display Rendering](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/createhtml.py): `apps/departures/createhtml.py`
- [Skin Loader](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/skinloader.py): `apps/departures/skinloader.py`
- [Departures Web UI](https://github.com/matrixbox-dev/matrixbox/blob/main/apps/departures/web.py): `apps/departures/web.py`

### Other components

- **Device User**
- **Transit Service**

## Connections

- Device User → Runtime Loop: operates (evidence: `README.md`)
- Runtime Loop → Settings: loads settings (evidence: `main.py`)
- Runtime Loop → Matrix Display: uses display (evidence: `main.py`)
- Runtime Loop → Button Input: checks input (evidence: `main.py`)
- Runtime Loop → Wi-Fi Manager: connects network (evidence: `main.py`)
- Runtime Loop → Device Web UI: loads interface (evidence: `main.py`)
- Runtime Loop → HTTP Router: registers routes (evidence: `main.py`)
- Boot Setup → Settings: loads settings (evidence: `boot.py`)
- Matrix Display → Display Fonts: renders text (evidence: `lib/load_screen.py`)
- Device Web UI → HTTP Router: registers routes (evidence: `lib/web_interface.py`)
- Device Web UI → File Manager: loads manager (evidence: `lib/web_interface.py`)
- Device Web UI → AI Assistant: calls assistant (evidence: `lib/web_interface.py`)
- Wi-Fi Manager → HTTP Router: registers routes (evidence: `lib/wlan.py`)
- Runtime Loop → Socket Manager: gets SSL context (evidence: `main.py`)
- Runtime Loop → HTTP Client: creates session (evidence: `main.py`)
- Runtime Loop → Clock: launches app (evidence: `main.py`)
- Runtime Loop → Paint: launches app (evidence: `main.py`)
- Runtime Loop → Weather: launches app (evidence: `main.py`)
- Runtime Loop → Stocks: launches app (evidence: `main.py`)
- Runtime Loop → Last.fm: launches app (evidence: `main.py`)
- Runtime Loop → Screensavers: selects saver (evidence: `main.py`)
- Runtime Loop → Other Official Apps: loads selected app (evidence: `main.py`)
- Runtime Loop → Departures App Entry: launches app
- Departures App Entry → Departures State: initializes state
- Departures State → Departure Processing: imports processing (evidence: `apps/departures/varinit.py`)
- Departures State → Transit Data And Text: loads dictionaries (evidence: `apps/departures/varinit.py`)
- Departure Processing → Departures State: uses settings (evidence: `apps/departures/functions.py`)
- Departure Processing → Display Rendering: uses rendering (evidence: `apps/departures/functions.py`)
- Departure Processing → Transit Data And Text: uses text data
- Departure Processing → Transit Service: retrieves departures
- Departures App Entry → Departures Web UI: serves app UI
- Departures Web UI → Departures State: uses settings (evidence: `apps/departures/web.py`)
- Departures Web UI → Departure Processing: uses processing (evidence: `apps/departures/web.py`)
- Departures Web UI → Transit Data And Text: uses dictionaries (evidence: `apps/departures/web.py`)
- Departures Web UI → Skin Loader: loads skins (evidence: `apps/departures/web.py`)
- Display Rendering → Departures State: uses state (evidence: `apps/departures/createhtml.py`)
- Display Rendering → Departure Processing: uses processing (evidence: `apps/departures/createhtml.py`)
- Display Rendering → Skin Loader: uses skins (evidence: `apps/departures/createhtml.py`)
