# rama-mwenda/monarch-wireless architecture

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

- Interactive diagram: https://gitdiagram.com/rama-mwenda/monarch-wireless
- Repository: https://github.com/rama-mwenda/monarch-wireless

## Overview

Monarch Wireless manages a mesh Wi-Fi hotspot business: guests select access and pay or redeem a voucher, while administrators and site managers operate the network and business through role-specific dashboards. The backend coordinates portal and admin APIs, stored records, payments, Omada access control, and SMS; a scheduled job expires sessions. The README documents broader reporting, loyalty, and operational capabilities. Some route and service implementations were not sampled, so uncertain internal call links are omitted.

Main entry points: [`backend/src/app.js`](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/app.js) (Express API), [`backend/src/db/index.js`](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/db/index.js) (SQLite database), [`frontend/src/services/api.js`](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/services/api.js) (App and API client), [`backend/src/services/omada.js`](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/omada.js) (Omada controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User experiences"]
  node_portal["Captive portal<br/>[portal.js]"]
  node_dashboard["Admin dashboard<br/>[Dashboard.jsx]"]
  node_networkui["Network views<br/>[Network.jsx]"]
  node_clientui["Live clients<br/>[LiveClients.jsx]"]
  node_businessui["Business tools<br/>[Reports.jsx]"]
  node_frontend["App and API client<br/>[api.js]"]
end

subgraph group_api["Backend capabilities"]
  node_app["Express API<br/>[app.js]"]
  node_authroutes["Authentication<br/>[auth.js]"]
  node_catalogroutes["Packages and vouchers<br/>[packages.js]"]
  node_networkroutes["Network API<br/>[network.js]"]
  node_paymentroutes["Payments<br/>[mpesa.js]"]
  node_businessroutes["Users, reports, settings<br/>[users.js]"]
  node_sessionhelper["Session authorization<br/>[mac-auth-helper.js]"]
  node_expiry["Session expiry job<br/>[session-expiry.js]"]
end

subgraph group_integrations["External integrations"]
  node_mpesa["M-Pesa service<br/>[mpesa.js]"]
  node_omada["Omada controller<br/>[omada.js]"]
  node_sms["SMS service<br/>[sms.js]"]
  node_controller["Omada controller service"]
  node_paymentprovider["M-Pesa provider"]
  node_smsprovider["SMS provider"]
end

subgraph group_state["Security and state"]
  node_authmw["JWT and audit<br/>[auth.js]"]
  node_db[("SQLite database<br/>[index.js]")]
end

node_guest(("Hotspot guest"))
node_admin(("Admin or host"))

node_guest -->|"opens portal"| node_portal
node_admin -->|"uses dashboard"| node_dashboard
node_dashboard -->|"requests data"| node_frontend
node_networkui -->|"requests data"| node_frontend
node_clientui -->|"requests clients"| node_frontend
node_businessui -->|"requests data"| node_frontend
node_frontend -->|"sends API requests"| node_app
node_app -->|"dispatches auth"| node_authroutes
node_app -->|"dispatches catalog"| node_catalogroutes
node_app -->|"dispatches network"| node_networkroutes
node_app -->|"dispatches payments"| node_paymentroutes
node_app -->|"dispatches business"| node_businessroutes
node_app -->|"dispatches portal"| node_portal
node_authroutes -->|"protects routes"| node_authmw
node_authroutes -->|"reads and writes"| node_db
node_catalogroutes -->|"reads and writes"| node_db
node_businessroutes -->|"reads and writes"| node_db
node_networkroutes -->|"queries controller"| node_omada
node_paymentroutes -->|"initiates payment"| node_mpesa
node_paymentroutes -->|"records transactions"| node_db
node_portal -->|"reads and writes"| node_db
node_sessionhelper -->|"checks sessions"| node_db
node_sessionhelper -->|"authorizes devices"| node_omada
node_expiry -->|"expires sessions"| node_db
node_expiry -->|"deauthorizes devices"| node_omada
node_expiry -->|"sends expiry notices"| node_sms
node_mpesa -->|"calls API"| node_paymentprovider
node_omada -->|"calls controller"| node_controller
node_sms -.->|"sends messages"| node_smsprovider

click node_portal "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/portal.js"
click node_dashboard "https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Dashboard.jsx"
click node_networkui "https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Network.jsx"
click node_clientui "https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/LiveClients.jsx"
click node_businessui "https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Reports.jsx"
click node_frontend "https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/services/api.js"
click node_app "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/app.js"
click node_authroutes "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/auth.js"
click node_catalogroutes "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/packages.js"
click node_networkroutes "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/network.js"
click node_paymentroutes "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/mpesa.js"
click node_businessroutes "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/users.js"
click node_sessionhelper "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/helpers/mac-auth-helper.js"
click node_expiry "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/jobs/session-expiry.js"
click node_authmw "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/middleware/auth.js"
click node_db "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/db/index.js"
click node_mpesa "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/mpesa.js"
click node_omada "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/omada.js"
click node_sms "https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/sms.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_portal,node_dashboard,node_networkui,node_clientui,node_businessui,node_frontend toneBlue
class node_app,node_authroutes,node_catalogroutes,node_networkroutes,node_paymentroutes,node_businessroutes,node_sessionhelper,node_expiry toneAmber
class node_mpesa,node_omada,node_sms,node_controller,node_paymentprovider,node_smsprovider toneMint
class node_authmw,node_db toneRose
class node_guest,node_admin toneIndigo
```

## Components

### User experiences

- [Captive portal](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/portal.js): `backend/src/routes/portal.js`
- [Admin dashboard](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Network views](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Network.jsx): `frontend/src/pages/Network.jsx`
- [Live clients](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/LiveClients.jsx): `frontend/src/pages/LiveClients.jsx`
- [Business tools](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`
- [App and API client](https://github.com/rama-mwenda/monarch-wireless/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Backend capabilities

- [Express API](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/app.js): `backend/src/app.js`
- [Authentication](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Packages and vouchers](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/packages.js): `backend/src/routes/packages.js`
- [Network API](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/network.js): `backend/src/routes/network.js`
- [Payments](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/mpesa.js): `backend/src/routes/mpesa.js`
- [Users, reports, settings](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/routes/users.js): `backend/src/routes/users.js`
- [Session authorization](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/helpers/mac-auth-helper.js): `backend/src/helpers/mac-auth-helper.js`
- [Session expiry job](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/jobs/session-expiry.js): `backend/src/jobs/session-expiry.js`

### External integrations

- [M-Pesa service](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/mpesa.js): `backend/src/services/mpesa.js`
- [Omada controller](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/omada.js): `backend/src/services/omada.js`
- [SMS service](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/services/sms.js): `backend/src/services/sms.js`
- **Omada controller service**
- **M-Pesa provider**
- **SMS provider**

### Security and state

- [JWT and audit](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [SQLite database](https://github.com/rama-mwenda/monarch-wireless/blob/main/backend/src/db/index.js): `backend/src/db/index.js`

### Other components

- **Hotspot guest**
- **Admin or host**

## Connections

- Hotspot guest → Captive portal: opens portal
- Admin or host → Admin dashboard: uses dashboard
- Admin dashboard → App and API client: requests data
- Network views → App and API client: requests data
- Live clients → App and API client: requests clients
- Business tools → App and API client: requests data
- App and API client → Express API: sends API requests
- Express API → Authentication: dispatches auth
- Express API → Packages and vouchers: dispatches catalog
- Express API → Network API: dispatches network
- Express API → Payments: dispatches payments
- Express API → Users, reports, settings: dispatches business
- Express API → Captive portal: dispatches portal
- Authentication → JWT and audit: protects routes
- Authentication → SQLite database: reads and writes
- Packages and vouchers → SQLite database: reads and writes
- Users, reports, settings → SQLite database: reads and writes
- Network API → Omada controller: queries controller
- Payments → M-Pesa service: initiates payment
- Payments → SQLite database: records transactions
- Captive portal → SQLite database: reads and writes
- Session authorization → SQLite database: checks sessions
- Session authorization → Omada controller: authorizes devices
- Session expiry job → SQLite database: expires sessions
- Session expiry job → Omada controller: deauthorizes devices
- Session expiry job → SMS service: sends expiry notices
- M-Pesa service → M-Pesa provider: calls API
- Omada controller → Omada controller service: calls controller
- SMS service → SMS provider: sends messages