Architecture, Modules, Technologies

Architecture Overview

The following SVG image summarizes the architecture of OpenWISP, the main technologies used, the structure of the OpenWISP modules, their most important dependencies and the way they interact with one another.


For a better viewing experience, open the image in a new tab of your browser, from there you can also click on the different elements to open the README or website of each module or technology used.

The Inkscape source file of the architecture diagram is also available for download.

Inkscape is an open source vector editing software which has been used to produce this diagram.

OpenWISP Architecture Overview

OpenWISP Modules


If you want to know more about the motivations and philosophy that have shaped the modular architecture of OpenWISP, please see Applying the Unix Philosophy to Django projects: a report from the real world.


Server Side

  • OpenWISP Users: User management, multi-tenancy, authentication backend, REST API utilities and classes to implement multi-tenancy.

  • OpenWISP Controller: Configuration management and templating, automatic provisioning of VPN tunnels like OpenVPN, Wireguard, Wireguard over VXLAN, shell commands, SSH connections, x509 PKI management, geographic maps and floorplans, programmable IP address management and subnet provisioning.

    This module depends on several django apps or python libraries developed or maintained by OpenWISP:

  • OpenWISP Monitoring: Monitors and tracks device information like uptime, packet loss, round trip time, traffic, WiFi clients,memory, CPU load, flash space, ARP/neighbor information, DHCP leases, provides charts and configurable alerts, allows to write custom checks or reconfigure tolerance thresholds and charts.

  • OpenWISP Network Topology: Network topology collector and visualizer. Collects network topology data from dynamic mesh routing protocols or other popular networking software like OpenVPN, allows to visualize the network graph and save daily snapshots that can be viewed in the future.

    This module depends on two libraries developed and maintained by OpenWISP:

  • OpenWISP Firmware Upgrader: Firmware upgrade solution for OpenWRT with possibility to add support for other embedded OSes. Provides features like automatic retry for network failures, mass upgrades, REST API and more.

  • OpenWISP RADIUS: provides a web interface to a freeradius database, a rich REST HTTP API and features like user self registration, SMS verification, import of users from CSV files, generation of new users for events, Captive Portal Social Login, Captive Portal SAML login and more.

  • OpenWISP Notifications: provides email and web notifications to OpenWISP. Its main goal is to allow any OpenWISP module to notify users about meaningful events that happen in their network.

  • OpenWISP Utils: common utilities and classes shared by all the OpenWISP python modules, it includes a lot of utilities for QA checks and automated testing which are heavily used in continuous integration builds of most, if not all, the OpenWISP github repositories.

  • OpenWISP WiFi Login Pages: Configurable captive page for public/private WiFi services providing login, sign up, social login, SMS verification, change password, reset password, change phone number and more. This is a frontend of the OpenWISP RADIUS REST API and it’s designed to be used by end users of a public WiFi network.

Network Device Side

Website and Documentation

Main Technologies Used


Python is the main programming language used by the server side application (web admin, API, controller, workers).

In the past OpenWISP was built on Ruby On Rails, but we later switched to Python because it’s more suited to networking and has a wider pool of potential contributors.

Find out more on why OpenWISP chose Python as its main language.


Django is one of the most popular web frameworks for Python language.

It is used extensively in our modules. Django allows rapid development and has a very rich ecosystem.

It’s the base framework used in most of the server side modules of OpenWISP.

Find out more on why OpenWISP chose Django as its main web framework.

Django REST Framework

Django REST framework is a powerful and flexible toolkit for building Web APIs based on Django and it’s widely used in most of the Django and web based based OpenWISP modules.

Find out more on why OpenWISP chose Django REST Framework to build its REST API.


Celery is a python implementation of a distributed task queue and it is heavily used in OpenWISP to execute background tasks, perform network operations like monitoring checks, configuration updates, firmware upgrades and so on.


OpenWrt is an linux distribution designed for embedded systems, routers and networking in general.

It has a very skilled community and it is used as a base by many hardware vendors (Technicolor, Ubiquiti Networks, Linksys, Teltonika and many others).


Lua is a lightweight, multi-paradigm programming language designed primarily for embedded systems and clients.

Lua is cross-platform, since the interpreter is written in ANSI C, and has a relatively simple C API.

It is the official scripting language of OpenWRT and it’s used heavily in the OpenWrt packages of OpenWISP: openwisp-config and openwisp-monitoring.

Node.js and React JS

NodeJS is javascript runtime to build JS based applications.

In OpenWISP it’s used as a base for frontend applications along with React, like openwisp-wifi-login-pages.


Ansible is a very popular software automation tool written in python that is generally used for automating software provisioning, configuration management and application deployment.

We use Ansible to provide automated procedures to deploy OpenWISP, to compile custom OpenWRT images for different organizations, to deploy OpenWISP WiFi Login Pages and to deploy the Wireguard integration for OpenWISP Controller.


We use docker in docker-openwisp, which aims to ease the deployment of OpenWISP in a containerized infrastructure.


NetJSON is a data interchange format based on JSON designed to ease the development of software tools for computer networks.


RADIUS (Remote Authentication Dial-In User Service) is a networking protocol that used for centralized Authentication, Authorization, and Accounting management of network services.


Freeradius is the most popular open source implementation of the RADIUS protocol and is heavily relied on in OpenWISP RADIUS.

Mesh Networking

A mesh network is a local network topology in which the infrastructure nodes connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients.

OpenWrt supports the standard mesh mode (802.11s) and OpenWISP supports this mode out of the box.

It is also possible to support other popular dynamic open source routing protocols available on OpenWrt like OLSRd2, BATMAN-advanced, Babel, BMX, etc.


InfluxDB is the default open source time series DB used in OpenWISP Monitoring.


Elasticsearch is an alternative option which can be used in OpenWISP Monitoring as time series DB, related to storing and retrieving data in a fast and efficient way.


Networkx is a network graph analysis library written in Python and used under the hood by netdiff and the OpenWISP Network Topology module.

Relational Databases

Django supports several Relational Database Management Systems.

The most notable ones are:

For production usage we recommend PostgreSQL.

For development we recommend SQLite for its simplicity .

Other notable dependencies