ippadmin/forefront-wireless-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b8f492b38c9b77561f7efaf958b753a590b6a82
forefront-wireless-portal/README.md
T

14 KiB
Raw Blame History

Forefront Wireless Customer Portal

Status: Scoped & Documented — awaiting build Started: July 25, 2026 Domain: my.forefrontwireless.com Companion project: IntelSight (shared auth — same Super Search/deepseek infra)

Self-service customer portal for Forefront Wireless, a WISP operating in Texas. Aggregates data from four distinct sources — Splynx (billing/CRM), UISP/UNMS (network management), MikroTik (router telemetry), and Zabbix/SNMP (infrastructure monitoring) — into a single branded customer experience.

Architecture — Multi-Source Data Aggregation

┌──────────────────────────────────────────────────────────────────────────┐
│                        my.forefrontwireless.com                           │
│                          (React SPA)                                      │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                       FastAPI Aggregation Backend                         │
│                    (api.forefrontwireless.com)                            │
│                                                                          │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐        │
│   │ Splynx   │  │  UISP    │  │ MikroTik │  │  Zabbix / SNMP   │        │
│   │ Adapter  │  │ Adapter  │  │ Adapter  │  │    Adapter       │        │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬─────────┘        │
└───────┼──────────────┼──────────────┼─────────────────┼──────────────────┘
        │              │              │                 │
        ▼              ▼              ▼                 ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Splynx v4.2  │ │ UISP     │ │ MikroTik     │ │ Zabbix       │
│ Self-hosted  │ │ (UNMS)   │ │ RouterOS     │ │ (existing    │
│ portal.ffw   │ │ app2     │ │ REST API     │ │  on-prem or  │
│ .com/admin/  │ │ Docker   │ │ 5 × CCR2004  │ │  cloud)      │
└──────────────┘ └──────────┘ └──────────────┘ └──────────────┘
   billing/CRM     network     router stats       infra health
   customers       devices     bandwidth          SNMP data
   invoices        links       DHCP leases        device uptime
   services        outages     WiFi clients       alerts

Stack: React SPA → FastAPI aggregation backend → 4 data-source adapters
Hosting: CloudPanel on app3 (152.53.241.111)
Auth pattern: Each adapter uses the native auth for its source; backend handles user auth separately

Data Source 1: Splynx (Billing & CRM)

URL: https://portal.forefrontwireless.com/api/2.0/
Version: v4.2, self-hosted
Auth: Signature-based HMAC-SHA256 (key + nonce, secret-driven)

What It Provides

  • Customer accounts (43 total, 33 active)
  • Service plans & active subscriptions
  • Invoices, payments, transaction history
  • Internet tariffs (9 plans, $59.95–$299.95/mo)
  • Support tickets
  • Router inventory (5 × MikroTik CCR2004)

Authentication

Authorization: Splynx-EA (key=K&nonce=N&signature=S)
Nonce: round(microtime * 100) — hundredths of a second
Signature: strtoupper(hash_hmac('sha256', nonce . key, secret))

Proven Endpoints

Method Path Description Status
GET /admin/customers/customer List all customers ✓
GET /admin/customers/customer/{id} Single customer ✓
GET /admin/customers/customer-internet-services/{customer_id} Customer services ✓
GET /admin/networking/routers Router inventory ✓
GET /admin/tariffs/internet Internet plans ✓
GET /admin/finance/invoices Invoices ✓
GET /admin/finance/payments Payments ⚠ untested
GET /admin/finance/transactions Transactions ⚠ untested
GET /admin/support/tickets Tickets ⚠ untested

Data Source 2: UISP / UNMS (Network Management)

Current location: app2 (152.53.39.202), Docker deployment
Notes: UNMS was renamed to UISP. Project docs use UISP for new work, UNMS for legacy references and config paths.

What It Provides

  • Tower/AP inventory and status
  • Wireless link quality (signal, capacity, uptime)
  • Device firmware versions
  • Network topology
  • Outage/alert history
  • Client device associations

API Access Options

Method Auth Use Case
UISP REST API API token (Settings → Users → API Access) Read-only dashboard data
Local WebSocket Internal, via Nginx 443 Device communication only
Direct MongoDB mongo --port 27117 ace Emergency read-only inventory

Key UISP Resources

  • Backup sync: Daily 6 AM via unms-backup-sync.sh → s3://hermes-vps-backups/unms-backups/
  • Port architecture: Internal 443 = web UI (proxy externally), 8089 = WS tunnel (NEVER proxy — returns 426)
  • Container recovery: device-ws containers may need manual start after backup restore
  • Vault key: Destroy/recreate on migration; key is NOT stored in any config file

Data Source 3: MikroTik RouterOS (Direct Device API)

Devices: 5 × MikroTik CCR2004 (known from Splynx router list) Auth: SSH key or RouterOS REST API credentials Protocol: MikroTik REST API (port 443/8443) or SSH command line

What It Provides

  • Real-time bandwidth per interface
  • DHCP lease table (which customer has which IP)
  • Connected WiFi clients (via CAPsMAN or built-in wireless)
  • Queue/simple queue stats (per-customer bandwidth limits)
  • Interface status, errors, uptime
  • ARP table
  • RouterOS version and firmware

Integration Approach

Each router needs REST API enabled and a read-only API user. The backend adapter polls all 5 routers on a schedule and caches results. Key endpoints:

REST Resource What It Returns
/rest/interface All interfaces + current RX/TX rates
/rest/ip/dhcp-server/lease Active DHCP leases (MAC ↔ IP ↔ hostname)
/rest/queue/simple Per-customer bandwidth queues
/rest/system/resource CPU, memory, uptime
/rest/ip/arp ARP table

Pitfall: MikroTik REST API returns data in RouterOS-specific data structures (not standard JSON). Lists may be nested, IDs are hex strings, timestamps are RouterOS epoch. The adapter must normalize all of this.

Data Source 4: Zabbix / SNMP (Infrastructure Monitoring)

Current state: Zabbix server running on-premises within the Forefront network
Future direction: Move to cloud (netcup/app3) or run remote Zabbix proxy

What It Provides

  • SNMP data from devices NOT in UISP (switches, power equipment, environmental sensors)
  • Historical bandwidth graphs (interface counters via SNMP)
  • Device uptime, CPU, temperature
  • Custom alert triggers (tower power loss, temp thresholds)
  • SLA reporting data

Integration Options

Option Pros Cons
Zabbix API Direct access to all data, triggers, graphs Requires Zabbix reachable from portal backend
Remote Zabbix proxy Proxy polls on-prem, reports to cloud server Extra component to manage
Direct SNMP from backend No Zabbix dependency, simpler Have to reimplement alerting logic
Zabbix → InfluxDB → Portal Time-series optimized, Grafana-compatible Additional database, more moving parts

Recommended Architecture (when ready)

Forefront Network                    Cloud (netcup/app3)
┌─────────────┐     ┌──────────────┐     ┌────────────────┐
│ SNMP devices│────▶│ Zabbix Proxy │────▶│ Zabbix Server  │
│ (switches,  │     │ (lightweight │     │ (full instance)│
│  PDUs, etc) │     │  collector)  │     │                │
└─────────────┘     └──────────────┘     └───────┬────────┘
                                                  │ Zabbix API
                                                  ▼
                                         ┌────────────────┐
                                         │ Portal Backend │
                                         │ (read-only)    │
                                         └────────────────┘

Zabbix proxy stays on-prem collecting SNMP; Zabbix server moves to cloud. Portal queries the cloud server's API. No firewall holes needed inbound — proxy initiates outbound connection to server.

Data Aggregation Model

The FastAPI backend acts as a read-only aggregation layer — it never writes to Splynx, UISP, MikroTik, or Zabbix directly. All mutations go through the respective native tools.

Customer-facing page                  Data sources behind it
─────────────────────                 ──────────────────────
Dashboard                            Splynx (account + bill)
  ├─ Current bill →                  Splynx invoices
  ├─ Data usage →                    MikroTik queues
  ├─ Network status →                UISP device state
  └─ Any outages? →                  Zabbix triggers

Services                             Splynx + MikroTik
  ├─ Plan →                          Splynx tariff
  ├─ IP address →                    MikroTik DHCP lease
  └─ Equipment →                     UISP device list

Support                              Splynx tickets + UISP alerts
Network Status                       UISP topology + MikroTik interfaces

Portal Feature Ladder

V1 — Core Self-Service

  • Customer login (email + password, or magic link)
  • Dashboard: active services, current bill, data usage
  • View & pay invoices (Stripe integration)
  • Update contact info, phone, email

V2 — Network Visibility

  • Real-time bandwidth usage (MikroTik queue stats)
  • Connected devices (MikroTik DHCP + ARP)
  • Network status indicator (UISP device health)
  • Outage notifications (Zabbix triggers → email/SMS)
  • Support ticket submission & tracking (Splynx)

V3 — Enhanced

  • Service upgrade/downgrade with proration
  • Usage graphs — daily/weekly/monthly (MikroTik + SNMP)
  • Auto-pay setup (Stripe)
  • Seasonal hold / vacation pause
  • Speed test integration

V4 — Operational

  • Equipment return workflow
  • Referral program
  • SLA dashboard (Zabbix data)
  • Network health map (UISP topology)

Integration Dependencies & Build Order

Because each data source has its own setup complexity, the build should be phased:

Phase Sources Complexity Dependencies
1. Splynx Billing + CRM Low API already proven, key configured
2. MikroTik Router telemetry Medium Need REST API user on each CCR2004
3. UISP Network management Medium Need UISP API token; app2 is live
4. Zabbix/SNMP Infrastructure monitoring High Decision needed: cloud migration vs proxy

Phases 1–2 can be V1. Phases 3–4 unlock V2 and beyond.

Splynx Quirks (Lessons Learned)

  1. Signature auth is required — Basic auth returns 401 unless "Unsecure access" is enabled on the key. Signature uses HMAC-SHA256 with a microtime nonce.
  2. Services need customer_id in URL — GET /admin/customers/customer-internet-services/{id} works, but GET /admin/customers/customer-internet-services?customer_id=2 returns 405.
  3. Tariff names may need separate resolution — The list endpoint may return tariff IDs only; names require a follow-up call.
  4. Data is filtered by permissions — Current API key has full permissions on all resources.

Zabbix Migration Considerations (When Ready)

Option Cost Complexity Latency
Cloud Zabbix + on-prem proxy +$30–50/mo VPS Medium — proxy + server setup Proxy-local (SNMP), API over WAN
Full cloud, direct SNMP +$30–50/mo VPS High — VPN to each device WAN-dependent
Keep on-prem, API tunnel $0 incremental Low — just expose API Need secure tunnel (Tailscale)

Recommendation: Cloud Zabbix + on-prem proxy. Keeps SNMP polling local (low latency, no firewall holes), moves the heavy server to managed infra, and gives the portal a stable API endpoint.

Related

Reference in New Issue View Git Blame Copy Permalink