# oxpoe/open-isp architecture

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

- Interactive diagram: https://gitdiagram.com/oxpoe/open-isp
- Repository: https://github.com/oxpoe/open-isp

## Overview

OPEN-ISP is a self-hosted ISP billing and network-management application backed by SQLite. Users enter through role-specific portals; admin, customer, technician and collector workflows reach billing, payments, support and network-management capabilities. Automation and integrations extend these workflows with scheduled billing and isolation, messaging, router/OLT/ACS management, RADIUS and operational monitoring. The README documents capabilities not fully represented in sampled source; arrows for those are limited to documented relationships or source-index references.

Main entry points: [`config/database.js`](https://github.com/oxpoe/open-isp/blob/main/config/database.js) (SQLite database), [`services/billingService.js`](https://github.com/oxpoe/open-isp/blob/main/services/billingService.js) (Billing), [`routes/adminPortal.js`](https://github.com/oxpoe/open-isp/blob/main/routes/adminPortal.js) (Admin portal), [`routes/customerPortal.js`](https://github.com/oxpoe/open-isp/blob/main/routes/customerPortal.js) (Customer portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Portals & Access"]
  node_customer_app["Customer app<br/>[app-customer.js]"]
  node_admin_portal["Admin portal<br/>[adminPortal.js]"]
  node_customer_portal["Customer portal<br/>[customerPortal.js]"]
  node_customer_api["Customer API<br/>[customerAPI.js]"]
  node_tech_portal["Technician portal<br/>[techPortal.js]"]
  node_collector_portal["Collector portal<br/>[collectorPortal.js]"]
  node_acs_portal["ACS portal<br/>[acsPortal.js]"]
end

subgraph group_billing["Customers &amp; Billing"]
  node_customer_service["Customer records<br/>[customerService.js]"]
  node_billing_service["Billing<br/>[billingService.js]"]
  node_payment_service["Payments<br/>[paymentService.js]"]
  node_qris["QRIS utilities<br/>[qrisUtil.js]"]
  node_tickets["Support tickets<br/>[ticketService.js]"]
end

subgraph group_network["Network Operations"]
  node_mikrotik["MikroTik management<br/>[mikrotikService.js]"]
  node_olt["OLT management<br/>[oltService.js]"]
  node_acs_devices["ACS devices"]
  node_radius["RADIUS server"]
end

subgraph group_communications["Messaging &amp; Automation"]
  node_whatsapp["WhatsApp gateway<br/>[whatsappService.js]"]
  node_notify["Notifications<br/>[waNotifyService.js]"]
  node_telegram["Telegram bot<br/>[telegramBot.js]"]
  node_cron["Scheduled jobs<br/>[cronService.js]"]
end

subgraph group_platform["Shared Platform"]
  node_database[("SQLite database<br/>[database.js]")]
  node_settings["Settings manager<br/>[settingsManager.js]"]
  node_session_limit["Session limits"]
  node_backup["Backup &amp; restore<br/>[backupService.js]"]
  node_monitoring["System monitoring"]
end

node_staff(("ISP staff"))
node_customers(("Customers"))

node_staff -->|"uses"| node_admin_portal
node_staff -->|"uses"| node_tech_portal
node_staff -->|"uses"| node_collector_portal
node_customers -->|"uses"| node_customer_app
node_customer_app -->|"serves"| node_customer_portal
node_admin_portal -->|"uses"| node_customer_service
node_admin_portal -->|"uses"| node_billing_service
node_admin_portal -->|"uses"| node_mikrotik
node_admin_portal -->|"uses"| node_olt
node_admin_portal -->|"uses"| node_backup
node_admin_portal -->|"uses"| node_monitoring
node_customer_portal -->|"uses"| node_billing_service
node_customer_portal -->|"uses"| node_payment_service
node_customer_portal -->|"uses"| node_tickets
node_customer_portal -->|"uses"| node_mikrotik
node_customer_api -->|"uses"| node_billing_service
node_customer_api -->|"uses"| node_payment_service
node_tech_portal -.->|"uses"| node_customer_service
node_collector_portal -.->|"uses"| node_billing_service
node_acs_portal -.->|"manages"| node_acs_devices
node_payment_service -->|"reads/writes"| node_database
node_billing_service -->|"reads/writes"| node_database
node_customer_service -->|"reads/writes"| node_database
node_tickets -->|"reads/writes"| node_database
node_mikrotik -->|"reads"| node_database
node_acs_devices -->|"reads/writes"| node_database
node_acs_devices -->|"uses"| node_mikrotik
node_olt -->|"provisions via"| node_acs_devices
node_customer_api -->|"uses"| node_qris
node_payment_service -->|"records"| node_database
node_billing_service -->|"uses"| node_customer_service
node_billing_service -->|"notifies via"| node_whatsapp
node_notify -->|"dispatches via"| node_whatsapp
node_notify -->|"notifies via"| node_telegram
node_whatsapp -->|"reads/writes"| node_database
node_cron -.->|"schedules"| node_billing_service
node_cron -.->|"automates"| node_mikrotik
node_settings -->|"configures"| node_database
node_session_limit -->|"tracks sessions"| node_database

click node_customer_app "https://github.com/oxpoe/open-isp/blob/main/app-customer.js"
click node_admin_portal "https://github.com/oxpoe/open-isp/blob/main/routes/adminPortal.js"
click node_customer_portal "https://github.com/oxpoe/open-isp/blob/main/routes/customerPortal.js"
click node_customer_api "https://github.com/oxpoe/open-isp/blob/main/routes/customerAPI.js"
click node_tech_portal "https://github.com/oxpoe/open-isp/blob/main/routes/techPortal.js"
click node_collector_portal "https://github.com/oxpoe/open-isp/blob/main/routes/collectorPortal.js"
click node_acs_portal "https://github.com/oxpoe/open-isp/blob/main/routes/acsPortal.js"
click node_customer_service "https://github.com/oxpoe/open-isp/blob/main/services/customerService.js"
click node_billing_service "https://github.com/oxpoe/open-isp/blob/main/services/billingService.js"
click node_payment_service "https://github.com/oxpoe/open-isp/blob/main/services/paymentService.js"
click node_qris "https://github.com/oxpoe/open-isp/blob/main/utils/qrisUtil.js"
click node_tickets "https://github.com/oxpoe/open-isp/blob/main/services/ticketService.js"
click node_mikrotik "https://github.com/oxpoe/open-isp/blob/main/services/mikrotikService.js"
click node_olt "https://github.com/oxpoe/open-isp/blob/main/services/oltService.js"
click node_acs_devices "https://github.com/oxpoe/open-isp/blob/main/services/customerDeviceService.js"
click node_radius "https://github.com/oxpoe/open-isp/blob/main/services/radiusServerService.js"
click node_whatsapp "https://github.com/oxpoe/open-isp/blob/main/services/whatsappService.js"
click node_notify "https://github.com/oxpoe/open-isp/blob/main/services/waNotifyService.js"
click node_telegram "https://github.com/oxpoe/open-isp/blob/main/services/telegramBot.js"
click node_cron "https://github.com/oxpoe/open-isp/blob/main/services/cronService.js"
click node_database "https://github.com/oxpoe/open-isp/blob/main/config/database.js"
click node_settings "https://github.com/oxpoe/open-isp/blob/main/config/settingsManager.js"
click node_session_limit "https://github.com/oxpoe/open-isp/blob/main/services/sessionLimitService.js"
click node_backup "https://github.com/oxpoe/open-isp/blob/main/services/backupService.js"
click node_monitoring "https://github.com/oxpoe/open-isp/blob/main/services/monitoringService.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_customer_app,node_admin_portal,node_customer_portal,node_customer_api,node_tech_portal,node_collector_portal,node_acs_portal toneBlue
class node_customer_service,node_billing_service,node_payment_service,node_qris,node_tickets toneAmber
class node_mikrotik,node_olt,node_acs_devices,node_radius toneMint
class node_whatsapp,node_notify,node_telegram,node_cron toneRose
class node_database,node_settings,node_session_limit,node_backup,node_monitoring,node_staff,node_customers toneIndigo
```

## Components

### Portals & Access

- [Customer app](https://github.com/oxpoe/open-isp/blob/main/app-customer.js): `app-customer.js`
- [Admin portal](https://github.com/oxpoe/open-isp/blob/main/routes/adminPortal.js): `routes/adminPortal.js`
- [Customer portal](https://github.com/oxpoe/open-isp/blob/main/routes/customerPortal.js): `routes/customerPortal.js`
- [Customer API](https://github.com/oxpoe/open-isp/blob/main/routes/customerAPI.js): `routes/customerAPI.js`
- [Technician portal](https://github.com/oxpoe/open-isp/blob/main/routes/techPortal.js): `routes/techPortal.js`
- [Collector portal](https://github.com/oxpoe/open-isp/blob/main/routes/collectorPortal.js): `routes/collectorPortal.js`
- [ACS portal](https://github.com/oxpoe/open-isp/blob/main/routes/acsPortal.js): `routes/acsPortal.js`

### Customers & Billing

- [Customer records](https://github.com/oxpoe/open-isp/blob/main/services/customerService.js): `services/customerService.js`
- [Billing](https://github.com/oxpoe/open-isp/blob/main/services/billingService.js): `services/billingService.js`
- [Payments](https://github.com/oxpoe/open-isp/blob/main/services/paymentService.js): `services/paymentService.js`
- [QRIS utilities](https://github.com/oxpoe/open-isp/blob/main/utils/qrisUtil.js): `utils/qrisUtil.js`
- [Support tickets](https://github.com/oxpoe/open-isp/blob/main/services/ticketService.js): `services/ticketService.js`

### Network Operations

- [MikroTik management](https://github.com/oxpoe/open-isp/blob/main/services/mikrotikService.js): `services/mikrotikService.js`
- [OLT management](https://github.com/oxpoe/open-isp/blob/main/services/oltService.js): `services/oltService.js`
- [ACS devices](https://github.com/oxpoe/open-isp/blob/main/services/customerDeviceService.js): `services/customerDeviceService.js`
- [RADIUS server](https://github.com/oxpoe/open-isp/blob/main/services/radiusServerService.js): `services/radiusServerService.js`

### Messaging & Automation

- [WhatsApp gateway](https://github.com/oxpoe/open-isp/blob/main/services/whatsappService.js): `services/whatsappService.js`
- [Notifications](https://github.com/oxpoe/open-isp/blob/main/services/waNotifyService.js): `services/waNotifyService.js`
- [Telegram bot](https://github.com/oxpoe/open-isp/blob/main/services/telegramBot.js): `services/telegramBot.js`
- [Scheduled jobs](https://github.com/oxpoe/open-isp/blob/main/services/cronService.js): `services/cronService.js`

### Shared Platform

- [SQLite database](https://github.com/oxpoe/open-isp/blob/main/config/database.js): `config/database.js`
- [Settings manager](https://github.com/oxpoe/open-isp/blob/main/config/settingsManager.js): `config/settingsManager.js`
- [Session limits](https://github.com/oxpoe/open-isp/blob/main/services/sessionLimitService.js): `services/sessionLimitService.js`
- [Backup & restore](https://github.com/oxpoe/open-isp/blob/main/services/backupService.js): `services/backupService.js`
- [System monitoring](https://github.com/oxpoe/open-isp/blob/main/services/monitoringService.js): `services/monitoringService.js`

### Other components

- **ISP staff**
- **Customers**

## Connections

- ISP staff → Admin portal: uses (evidence: `README.md`)
- ISP staff → Technician portal: uses (evidence: `README.md`)
- ISP staff → Collector portal: uses (evidence: `README.md`)
- Customers → Customer app: uses (evidence: `README.md`)
- Customer app → Customer portal: serves (evidence: `app-customer.js`)
- Admin portal → Customer records: uses (evidence: `routes/adminPortal.js`)
- Admin portal → Billing: uses (evidence: `routes/adminPortal.js`)
- Admin portal → MikroTik management: uses (evidence: `routes/adminPortal.js`)
- Admin portal → OLT management: uses (evidence: `routes/adminPortal.js`)
- Admin portal → Backup & restore: uses (evidence: `routes/adminPortal.js`)
- Admin portal → System monitoring: uses (evidence: `routes/adminPortal.js`)
- Customer portal → Billing: uses (evidence: `routes/customerPortal.js`)
- Customer portal → Payments: uses (evidence: `routes/customerPortal.js`)
- Customer portal → Support tickets: uses (evidence: `routes/customerPortal.js`)
- Customer portal → MikroTik management: uses (evidence: `routes/customerPortal.js`)
- Customer API → Billing: uses (evidence: `routes/customerAPI.js`)
- Customer API → Payments: uses (evidence: `routes/customerAPI.js`)
- Technician portal → Customer records: uses (evidence: `README.md`)
- Collector portal → Billing: uses (evidence: `README.md`)
- ACS portal → ACS devices: manages (evidence: `README.md`)
- Payments → SQLite database: reads/writes (evidence: `services/paymentService.js`)
- Billing → SQLite database: reads/writes (evidence: `services/billingService.js`)
- Customer records → SQLite database: reads/writes (evidence: `services/customerService.js`)
- Support tickets → SQLite database: reads/writes (evidence: `services/ticketService.js`)
- MikroTik management → SQLite database: reads (evidence: `services/mikrotikService.js`)
- ACS devices → SQLite database: reads/writes (evidence: `services/customerDeviceService.js`)
- ACS devices → MikroTik management: uses (evidence: `services/customerDeviceService.js`)
- OLT management → ACS devices: provisions via (evidence: `services/oltService.js`)
- Customer API → QRIS utilities: uses (evidence: `routes/customerAPI.js`)
- Payments → SQLite database: records (evidence: `services/paymentService.js`)
- Billing → Customer records: uses (evidence: `services/billingService.js`)
- Billing → WhatsApp gateway: notifies via (evidence: `services/billingService.js`)
- Notifications → WhatsApp gateway: dispatches via (evidence: `services/waNotifyService.js`)
- Notifications → Telegram bot: notifies via (evidence: `services/waNotifyService.js`)
- WhatsApp gateway → SQLite database: reads/writes (evidence: `services/whatsappService.js`)
- Scheduled jobs → Billing: schedules (evidence: `README.md`)
- Scheduled jobs → MikroTik management: automates (evidence: `README.md`)
- Settings manager → SQLite database: configures (evidence: `config/settingsManager.js`)
- Session limits → SQLite database: tracks sessions (evidence: `services/sessionLimitService.js`)