# gotthardp/lorawan-server architecture

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

- Interactive diagram: https://gitdiagram.com/gotthardp/lorawan-server
- Repository: https://github.com/gotthardp/lorawan-server

## Overview

This is an Erlang LoRaWAN network and application server for private networks. The principal flow is gateway traffic into the server, LoRaWAN frame validation and device handling, then delivery to internal application logic, MongoDB, or external application connectors. Operators configure and monitor the network through the administration interface and REST API. The README documents capabilities, but most Erlang implementations were not sampled, so subsystem paths follow the tree and edges are limited to documented relationships; the sampled React admin also contains a fixed API endpoint.

Main entry points: [`src/lorawan_mac.erl`](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac.erl) (Frame security and MAC), [`src/lorawan_db.erl`](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_db.erl) (Device and application state), [`src/lorawan_application.erl`](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_application.erl) (Internal applications), [`admin/src/index.js`](https://github.com/gotthardp/lorawan-server/blob/master/admin/src/index.js) (React administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway connectivity"]
  node_packet_forwarder["Packet forwarder"]
  node_basic_station["Basic Station LNS<br/>[lorawan_gw_lns.erl]"]
  node_gateway_router["Gateway router"]
end

subgraph group_network["LoRaWAN network"]
  node_frame_mac["Frame security and MAC<br/>[lorawan_mac.erl]"]
  node_mac_commands["MAC commands"]
  node_regional_params["Regional parameters"]
  node_device_state[("Device and application state<br/>[lorawan_db.erl]")]
end

subgraph group_apps["Applications and integrations"]
  node_application_logic["Internal applications"]
  node_mote_app["Semtech mote application"]
  node_backend_handlers["Backend handlers"]
  node_connector_factory["Connector dispatch"]
  node_connectors["External connectors"]
  node_mongodb_connector["MongoDB connector"]
end

subgraph group_admin["Administration"]
  node_admin_api["Admin API<br/>[lorawan_admin.erl]"]
  node_legacy_admin["Web administration<br/>[admin.js]"]
  node_react_admin["React administration<br/>[index.js]"]
  node_user_management["User management views<br/>[Users.js]"]
end

node_gateway_actor(("LoRaWAN gateways"))
node_external_apps(("External applications"))
node_admin_user(("Network operator"))

node_gateway_actor -->|"sends packets"| node_packet_forwarder
node_gateway_actor -->|"sends packets"| node_basic_station
node_packet_forwarder -.->|"forwards traffic"| node_gateway_router
node_basic_station -.->|"forwards traffic"| node_gateway_router
node_gateway_router -.->|"routes traffic"| node_frame_mac
node_frame_mac -.->|"checks device state"| node_device_state
node_frame_mac -.->|"processes commands"| node_mac_commands
node_frame_mac -->|"uses region rules"| node_regional_params
node_device_state -.->|"provides device data"| node_application_logic
node_application_logic -->|"dispatches application logic"| node_mote_app
node_application_logic -->|"invokes handlers"| node_backend_handlers
node_backend_handlers -.->|"selects connectors"| node_connector_factory
node_connector_factory -.->|"dispatches output"| node_connectors
node_connectors -->|"delivers events"| node_external_apps
node_device_state -->|"stores uplinks"| node_mongodb_connector
node_admin_user -->|"manages network"| node_legacy_admin
node_admin_user -->|"manages users"| node_react_admin
node_legacy_admin -->|"calls API"| node_admin_api
node_react_admin -->|"requests API data"| node_admin_api
node_react_admin -->|"renders user views"| node_user_management
node_admin_api -.->|"manages configuration"| node_device_state

click node_packet_forwarder "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_forwarder.erl"
click node_basic_station "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_lns.erl"
click node_gateway_router "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_router.erl"
click node_frame_mac "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac.erl"
click node_mac_commands "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac_commands.erl"
click node_regional_params "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac_region.erl"
click node_device_state "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_db.erl"
click node_application_logic "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_application.erl"
click node_mote_app "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_application_semtech_mote.erl"
click node_backend_handlers "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_handler.erl"
click node_connector_factory "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_backend_factory.erl"
click node_connectors "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_connector.erl"
click node_mongodb_connector "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_connector_mongodb.erl"
click node_admin_api "https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_admin.erl"
click node_legacy_admin "https://github.com/gotthardp/lorawan-server/blob/master/priv/admin/admin.js"
click node_react_admin "https://github.com/gotthardp/lorawan-server/blob/master/admin/src/index.js"
click node_user_management "https://github.com/gotthardp/lorawan-server/blob/master/admin/src/Users.js"

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_packet_forwarder,node_basic_station,node_gateway_router toneBlue
class node_frame_mac,node_mac_commands,node_regional_params,node_device_state toneAmber
class node_application_logic,node_mote_app,node_backend_handlers,node_connector_factory,node_connectors,node_mongodb_connector toneMint
class node_admin_api,node_legacy_admin,node_react_admin,node_user_management toneRose
class node_gateway_actor,node_external_apps,node_admin_user toneIndigo
```

## Components

### Gateway connectivity

- [Packet forwarder](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_forwarder.erl): `src/lorawan_gw_forwarder.erl`
- [Basic Station LNS](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_lns.erl): `src/lorawan_gw_lns.erl`
- [Gateway router](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_gw_router.erl): `src/lorawan_gw_router.erl`

### LoRaWAN network

- [Frame security and MAC](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac.erl): `src/lorawan_mac.erl`
- [MAC commands](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac_commands.erl): `src/lorawan_mac_commands.erl`
- [Regional parameters](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_mac_region.erl): `src/lorawan_mac_region.erl`
- [Device and application state](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_db.erl): `src/lorawan_db.erl`

### Applications and integrations

- [Internal applications](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_application.erl): `src/lorawan_application.erl`
- [Semtech mote application](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_application_semtech_mote.erl): `src/lorawan_application_semtech_mote.erl`
- [Backend handlers](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_handler.erl): `src/lorawan_handler.erl`
- [Connector dispatch](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_backend_factory.erl): `src/lorawan_backend_factory.erl`
- [External connectors](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_connector.erl): `src/lorawan_connector.erl`
- [MongoDB connector](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_connector_mongodb.erl): `src/lorawan_connector_mongodb.erl`

### Administration

- [Admin API](https://github.com/gotthardp/lorawan-server/blob/master/src/lorawan_admin.erl): `src/lorawan_admin.erl`
- [Web administration](https://github.com/gotthardp/lorawan-server/blob/master/priv/admin/admin.js): `priv/admin/admin.js`
- [React administration](https://github.com/gotthardp/lorawan-server/blob/master/admin/src/index.js): `admin/src/index.js`
- [User management views](https://github.com/gotthardp/lorawan-server/blob/master/admin/src/Users.js): `admin/src/Users.js`

### Other components

- **LoRaWAN gateways**
- **External applications**
- **Network operator**

## Connections

- LoRaWAN gateways → Packet forwarder: sends packets (evidence: `README.md`)
- LoRaWAN gateways → Basic Station LNS: sends packets (evidence: `README.md`)
- Packet forwarder → Gateway router: forwards traffic
- Basic Station LNS → Gateway router: forwards traffic
- Gateway router → Frame security and MAC: routes traffic
- Frame security and MAC → Device and application state: checks device state
- Frame security and MAC → MAC commands: processes commands
- Frame security and MAC → Regional parameters: uses region rules (evidence: `README.md`)
- Device and application state → Internal applications: provides device data
- Internal applications → Semtech mote application: dispatches application logic (evidence: `README.md`)
- Internal applications → Backend handlers: invokes handlers (evidence: `README.md`)
- Backend handlers → Connector dispatch: selects connectors
- Connector dispatch → External connectors: dispatches output
- External connectors → External applications: delivers events (evidence: `README.md`)
- Device and application state → MongoDB connector: stores uplinks (evidence: `README.md`)
- Network operator → Web administration: manages network (evidence: `README.md`)
- Network operator → React administration: manages users (evidence: `README.md`)
- Web administration → Admin API: calls API (evidence: `README.md`)
- React administration → Admin API: requests API data (evidence: `admin/src/index.js`)
- React administration → User management views: renders user views (evidence: `admin/src/index.js`)
- Admin API → Device and application state: manages configuration
