# deshan555/openrelay architecture

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

- Interactive diagram: https://gitdiagram.com/deshan555/openrelay
- Repository: https://github.com/deshan555/openrelay

## Overview

OpenRelay is a self-hosted SMS gateway: administrators authenticate and submit individual or campaign messages, the backend queues work and assigns it to connected Android devices, and devices send SMS through their carrier. The dashboard also monitors devices, logs, queue activity, and administrator accounts. Backend calls and startup wiring are supported by the excerpts and SOURCE INDEX; some dashboard-to-API and Android runtime details are documented but their implementing Flutter sources are absent from the supplied tree, so those links are marked unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/deshan555/openrelay/blob/master/frontend/src/App.tsx) (Dashboard app), [`backend/app/api/v2/endpoints/websocket.py`](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/websocket.py) (Device WebSocket), [`backend/app/main.py`](https://github.com/deshan555/openrelay/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/api/v2/endpoints/admin_auth.py`](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/admin_auth.py) (Admin authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Admin dashboard"]
  node_app["Dashboard app<br/>[App.tsx]"]
  node_login["Login and setup<br/>[LoginScreen.tsx]"]
  node_setup["Initial setup<br/>[SetupScreen.tsx]"]
  node_device_view["Device monitor<br/>[DevicesTab.tsx]"]
  node_sms_view["SMS console<br/>[SmsTab.tsx]"]
  node_campaign_view["Campaign manager<br/>[BulkTab.tsx]"]
  node_logs_view["SMS logs<br/>[LogsTab.tsx]"]
  node_queue_view["Queue monitor<br/>[QueueFlowTab.tsx]"]
  node_admin_view["Admin management<br/>[AdminTab.tsx]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI application<br/>[main.py]"]
  node_admin_api["Admin authentication<br/>[admin_auth.py]"]
  node_device_api["Device endpoints<br/>[devices.py]"]
  node_sms_api["SMS endpoints<br/>[sms.py]"]
  node_campaign_api["Campaign endpoints<br/>[bulk_sms.py]"]
  node_ws_api["Device WebSocket<br/>[websocket.py]"]
end

subgraph group_runtime["Queue and state"]
  node_auth["JWT and passwords<br/>[auth.py]"]
  node_queue["Queue engine<br/>[queue_manager.py]"]
  node_connections["Connection registry<br/>[websocket.py]"]
  node_mongo[("MongoDB state<br/>[database_mongo.py]")]
end

subgraph group_device["Android gateway"]
  node_device_app["Android device client<br/>[MainActivity.kt]"]
  node_sms_bridge["Native SMS bridge"]
end

node_admin(("Administrator"))
node_carrier{{"Carrier network"}}

node_admin -.->|"uses"| node_app
node_app -->|"renders"| node_login
node_app -->|"renders"| node_setup
node_app -->|"renders"| node_device_view
node_app -->|"renders"| node_sms_view
node_app -->|"renders"| node_campaign_view
node_app -->|"renders"| node_logs_view
node_app -->|"renders"| node_queue_view
node_app -->|"renders"| node_admin_view
node_app -->|"fetches devices"| node_device_api
node_login -.->|"authenticates via"| node_admin_api
node_setup -.->|"initializes via"| node_admin_api
node_sms_view -.->|"submits SMS"| node_sms_api
node_campaign_view -.->|"uploads campaigns"| node_campaign_api
node_device_view -.->|"monitors devices"| node_device_api
node_logs_view -.->|"queries logs"| node_campaign_api
node_queue_view -.->|"observes queue"| node_ws_api
node_admin_view -.->|"manages accounts"| node_admin_api
node_server -->|"registers routes"| node_admin_api
node_server -->|"registers routes"| node_device_api
node_server -->|"registers routes"| node_sms_api
node_server -->|"registers routes"| node_campaign_api
node_server -->|"registers routes"| node_ws_api
node_server -->|"starts workers"| node_queue
node_admin_api -->|"uses"| node_auth
node_device_api -->|"checks tokens"| node_auth
node_sms_api -->|"checks tokens"| node_auth
node_campaign_api -->|"checks tokens"| node_auth
node_ws_api -->|"checks tokens"| node_auth
node_admin_api -->|"reads and writes"| node_mongo
node_device_api -->|"reads and writes"| node_mongo
node_sms_api -->|"reads and writes"| node_mongo
node_campaign_api -->|"reads and writes"| node_mongo
node_ws_api -->|"updates device state"| node_mongo
node_ws_api -->|"registers connections"| node_connections
node_ws_api -->|"reports results"| node_queue
node_queue -->|"claims and updates jobs"| node_mongo
node_queue -->|"sends device messages"| node_connections
node_device_app -.->|"connects by WebSocket"| node_ws_api
node_device_app -.->|"invokes native SMS"| node_sms_bridge
node_sms_bridge -.->|"sends SMS"| node_carrier

click node_app "https://github.com/deshan555/openrelay/blob/master/frontend/src/App.tsx"
click node_login "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/LoginScreen.tsx"
click node_setup "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/SetupScreen.tsx"
click node_device_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/DevicesTab.tsx"
click node_sms_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/SmsTab.tsx"
click node_campaign_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/BulkTab.tsx"
click node_logs_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/LogsTab.tsx"
click node_queue_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/QueueFlowTab.tsx"
click node_admin_view "https://github.com/deshan555/openrelay/blob/master/frontend/src/components/AdminTab.tsx"
click node_server "https://github.com/deshan555/openrelay/blob/master/backend/app/main.py"
click node_admin_api "https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/admin_auth.py"
click node_device_api "https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/devices.py"
click node_sms_api "https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/sms.py"
click node_campaign_api "https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/bulk_sms.py"
click node_ws_api "https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/websocket.py"
click node_auth "https://github.com/deshan555/openrelay/blob/master/backend/app/auth.py"
click node_queue "https://github.com/deshan555/openrelay/blob/master/backend/app/queue_manager.py"
click node_connections "https://github.com/deshan555/openrelay/blob/master/backend/app/websocket.py"
click node_mongo "https://github.com/deshan555/openrelay/blob/master/backend/app/database_mongo.py"
click node_device_app "https://github.com/deshan555/openrelay/blob/master/android/android/app/src/main/kotlin/com/openrelay/openrelay/MainActivity.kt"
click node_sms_bridge "https://github.com/deshan555/openrelay/blob/master/android/sms_channel/android/src/main/kotlin/com/openrelay/sms_channel/SmsChannelPlugin.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_app,node_login,node_setup,node_device_view,node_sms_view,node_campaign_view,node_logs_view,node_queue_view,node_admin_view toneBlue
class node_server,node_admin_api,node_device_api,node_sms_api,node_campaign_api,node_ws_api toneAmber
class node_auth,node_queue,node_connections,node_mongo toneMint
class node_device_app,node_sms_bridge toneRose
class node_admin,node_carrier toneIndigo
```

## Components

### Admin dashboard

- [Dashboard app](https://github.com/deshan555/openrelay/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login and setup](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/LoginScreen.tsx): `frontend/src/components/LoginScreen.tsx`
- [Initial setup](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/SetupScreen.tsx): `frontend/src/components/SetupScreen.tsx`
- [Device monitor](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/DevicesTab.tsx): `frontend/src/components/DevicesTab.tsx`
- [SMS console](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/SmsTab.tsx): `frontend/src/components/SmsTab.tsx`
- [Campaign manager](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/BulkTab.tsx): `frontend/src/components/BulkTab.tsx`
- [SMS logs](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/LogsTab.tsx): `frontend/src/components/LogsTab.tsx`
- [Queue monitor](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/QueueFlowTab.tsx): `frontend/src/components/QueueFlowTab.tsx`
- [Admin management](https://github.com/deshan555/openrelay/blob/master/frontend/src/components/AdminTab.tsx): `frontend/src/components/AdminTab.tsx`

### Backend API

- [FastAPI application](https://github.com/deshan555/openrelay/blob/master/backend/app/main.py): `backend/app/main.py`
- [Admin authentication](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/admin_auth.py): `backend/app/api/v2/endpoints/admin_auth.py`
- [Device endpoints](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/devices.py): `backend/app/api/v2/endpoints/devices.py`
- [SMS endpoints](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/sms.py): `backend/app/api/v2/endpoints/sms.py`
- [Campaign endpoints](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/bulk_sms.py): `backend/app/api/v2/endpoints/bulk_sms.py`
- [Device WebSocket](https://github.com/deshan555/openrelay/blob/master/backend/app/api/v2/endpoints/websocket.py): `backend/app/api/v2/endpoints/websocket.py`

### Queue and state

- [JWT and passwords](https://github.com/deshan555/openrelay/blob/master/backend/app/auth.py): `backend/app/auth.py`
- [Queue engine](https://github.com/deshan555/openrelay/blob/master/backend/app/queue_manager.py): `backend/app/queue_manager.py`
- [Connection registry](https://github.com/deshan555/openrelay/blob/master/backend/app/websocket.py): `backend/app/websocket.py`
- [MongoDB state](https://github.com/deshan555/openrelay/blob/master/backend/app/database_mongo.py): `backend/app/database_mongo.py`

### Android gateway

- [Android device client](https://github.com/deshan555/openrelay/blob/master/android/android/app/src/main/kotlin/com/openrelay/openrelay/MainActivity.kt): `android/android/app/src/main/kotlin/com/openrelay/openrelay/MainActivity.kt`
- [Native SMS bridge](https://github.com/deshan555/openrelay/blob/master/android/sms_channel/android/src/main/kotlin/com/openrelay/sms_channel/SmsChannelPlugin.kt): `android/sms_channel/android/src/main/kotlin/com/openrelay/sms_channel/SmsChannelPlugin.kt`

### Other components

- **Administrator**
- **Carrier network**

## Connections

- Administrator → Dashboard app: uses
- Dashboard app → Login and setup: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Initial setup: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Device monitor: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → SMS console: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Campaign manager: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → SMS logs: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Queue monitor: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Admin management: renders (evidence: `frontend/src/App.tsx`)
- Dashboard app → Device endpoints: fetches devices (evidence: `frontend/src/App.tsx`)
- Login and setup → Admin authentication: authenticates via
- Initial setup → Admin authentication: initializes via
- SMS console → SMS endpoints: submits SMS
- Campaign manager → Campaign endpoints: uploads campaigns
- Device monitor → Device endpoints: monitors devices
- SMS logs → Campaign endpoints: queries logs
- Queue monitor → Device WebSocket: observes queue
- Admin management → Admin authentication: manages accounts
- FastAPI application → Admin authentication: registers routes
- FastAPI application → Device endpoints: registers routes
- FastAPI application → SMS endpoints: registers routes
- FastAPI application → Campaign endpoints: registers routes
- FastAPI application → Device WebSocket: registers routes
- FastAPI application → Queue engine: starts workers (evidence: `backend/app/main.py`)
- Admin authentication → JWT and passwords: uses (evidence: `backend/app/api/v2/endpoints/admin_auth.py`)
- Device endpoints → JWT and passwords: checks tokens (evidence: `backend/app/api/v2/endpoints/devices.py`)
- SMS endpoints → JWT and passwords: checks tokens (evidence: `backend/app/api/v2/endpoints/sms.py`)
- Campaign endpoints → JWT and passwords: checks tokens (evidence: `backend/app/api/v2/endpoints/bulk_sms.py`)
- Device WebSocket → JWT and passwords: checks tokens (evidence: `backend/app/api/v2/endpoints/websocket.py`)
- Admin authentication → MongoDB state: reads and writes (evidence: `backend/app/api/v2/endpoints/admin_auth.py`)
- Device endpoints → MongoDB state: reads and writes (evidence: `backend/app/api/v2/endpoints/devices.py`)
- SMS endpoints → MongoDB state: reads and writes (evidence: `backend/app/api/v2/endpoints/sms.py`)
- Campaign endpoints → MongoDB state: reads and writes (evidence: `backend/app/api/v2/endpoints/bulk_sms.py`)
- Device WebSocket → MongoDB state: updates device state (evidence: `backend/app/api/v2/endpoints/websocket.py`)
- Device WebSocket → Connection registry: registers connections (evidence: `backend/app/api/v2/endpoints/websocket.py`)
- Device WebSocket → Queue engine: reports results (evidence: `backend/app/api/v2/endpoints/websocket.py`)
- Queue engine → MongoDB state: claims and updates jobs (evidence: `backend/app/queue_manager.py`)
- Queue engine → Connection registry: sends device messages (evidence: `backend/app/queue_manager.py`)
- Android device client → Device WebSocket: connects by WebSocket
- Android device client → Native SMS bridge: invokes native SMS
- Native SMS bridge → Carrier network: sends SMS