# simeononsecurity/meshtastic-ai-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/simeononsecurity/meshtastic-ai-bridge
- Repository: https://github.com/simeononsecurity/meshtastic-ai-bridge

## Overview

Local Meshtastic AI Bridge turns mesh text requests into AI-assisted radio replies, with deterministic help/status commands and optional retrieval context. The main workflow runs through the bridge’s packet filtering and queued processing, routes eligible requests to retrieval adapters, sends context and prompts to an OpenAI-compatible model endpoint, then chunks and returns the answer over Meshtastic. The dashboard reads bridge status and logs and manages selected services and model settings. Some bridge source is omitted, so links between orchestration stages are limited to documented behavior and visible calls.

Main entry points: [`bridge/bridge.py`](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py) (Bridge runtime), [`dashboard/dashboard.py`](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/dashboard/dashboard.py) (Web dashboard), [`bridge/retrieval.py`](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/retrieval.py) (Retrieval adapters), [`bridge/local_wiki.py`](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_wiki.py) (SQLite wiki search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mesh["Mesh interface"]
  node_meshtasticd["meshtasticd"]
end

subgraph group_assistant["Assistant runtime"]
  node_bridge["Bridge runtime<br/>[bridge.py]"]
  node_request_queue["Request queue<br/>[bridge.py]"]
  node_ai_api["AI API"]
  node_response_log["Response history<br/>[bridge.py]"]
  node_bridge_control["Bridge control API<br/>[bridge.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_retrieval["Retrieval adapters<br/>[retrieval.py]"]
  node_local_wiki["SQLite wiki search<br/>[local_wiki.py]"]
  node_wiki_index[("Wiki index<br/>[local_wiki.py]")]
  node_kiwix_search["Kiwix search<br/>[local_kiwix.py]"]
  node_kiwix["Kiwix server"]
  node_weather_service["wttr.in"]
  node_news_service["Google News RSS"]
  node_sensor_service["Local sensor endpoint"]
end

subgraph group_operations["Operations dashboard"]
  node_dashboard["Web dashboard<br/>[dashboard.py]"]
  node_model_config["Live model config<br/>[dashboard.py]"]
  node_ollama["Ollama service"]
  node_system_services["Host services"]
end

node_mesh_user(("Mesh user"))

node_mesh_user -->|"sends message"| node_meshtasticd
node_meshtasticd -->|"delivers packets"| node_bridge
node_bridge -->|"queues requests"| node_request_queue
node_request_queue -->|"processes request"| node_bridge
node_bridge -->|"routes retrieval"| node_retrieval
node_retrieval -.->|"fetches weather"| node_weather_service
node_retrieval -.->|"fetches news"| node_news_service
node_retrieval -.->|"reads telemetry"| node_sensor_service
node_bridge -->|"searches offline"| node_kiwix_search
node_kiwix_search -->|"queries library"| node_kiwix
node_bridge -->|"searches index"| node_local_wiki
node_local_wiki -->|"queries"| node_wiki_index
node_bridge -->|"requests completion"| node_ai_api
node_bridge -->|"sends reply"| node_meshtasticd
node_bridge -->|"appends interaction"| node_response_log
node_dashboard -->|"requests status"| node_bridge_control
node_dashboard -->|"reads history"| node_response_log
node_dashboard -->|"updates model"| node_model_config
node_dashboard -->|"manages services"| node_system_services
node_dashboard -->|"lists or pulls models"| node_ollama

click node_bridge "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py"
click node_request_queue "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py"
click node_retrieval "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/retrieval.py"
click node_local_wiki "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_wiki.py"
click node_wiki_index "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_wiki.py"
click node_kiwix_search "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_kiwix.py"
click node_response_log "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py"
click node_dashboard "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/dashboard/dashboard.py"
click node_bridge_control "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py"
click node_model_config "https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/dashboard/dashboard.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_meshtasticd,node_mesh_user toneBlue
class node_bridge,node_request_queue,node_ai_api,node_response_log,node_bridge_control toneAmber
class node_retrieval,node_local_wiki,node_wiki_index,node_kiwix_search,node_kiwix,node_weather_service,node_news_service,node_sensor_service toneMint
class node_dashboard,node_model_config,node_ollama,node_system_services toneRose
```

## Components

### Mesh interface

- **meshtasticd**

### Assistant runtime

- [Bridge runtime](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py): `bridge/bridge.py`
- [Request queue](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py): `bridge/bridge.py`
- **AI API**
- [Response history](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py): `bridge/bridge.py`
- [Bridge control API](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/bridge.py): `bridge/bridge.py`

### Knowledge retrieval

- [Retrieval adapters](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/retrieval.py): `bridge/retrieval.py`
- [SQLite wiki search](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_wiki.py): `bridge/local_wiki.py`
- [Wiki index](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_wiki.py): `bridge/local_wiki.py`
- [Kiwix search](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/bridge/local_kiwix.py): `bridge/local_kiwix.py`
- **Kiwix server**
- **wttr.in**
- **Google News RSS**
- **Local sensor endpoint**

### Operations dashboard

- [Web dashboard](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/dashboard/dashboard.py): `dashboard/dashboard.py`
- [Live model config](https://github.com/simeononsecurity/meshtastic-ai-bridge/blob/master/dashboard/dashboard.py): `dashboard/dashboard.py`
- **Ollama service**
- **Host services**

### Other components

- **Mesh user**

## Connections

- Mesh user → meshtasticd: sends message
- meshtasticd → Bridge runtime: delivers packets
- Bridge runtime → Request queue: queues requests
- Request queue → Bridge runtime: processes request
- Bridge runtime → Retrieval adapters: routes retrieval
- Retrieval adapters → wttr.in: fetches weather
- Retrieval adapters → Google News RSS: fetches news
- Retrieval adapters → Local sensor endpoint: reads telemetry
- Bridge runtime → Kiwix search: searches offline
- Kiwix search → Kiwix server: queries library
- Bridge runtime → SQLite wiki search: searches index
- SQLite wiki search → Wiki index: queries
- Bridge runtime → AI API: requests completion
- Bridge runtime → meshtasticd: sends reply
- Bridge runtime → Response history: appends interaction
- Web dashboard → Bridge control API: requests status
- Web dashboard → Response history: reads history
- Web dashboard → Live model config: updates model
- Web dashboard → Host services: manages services
- Web dashboard → Ollama service: lists or pulls models