Scope: dual access (staff roles + customer self-service), 6-section staff dashboard, device inventory with auto-SNMP template engine, customer marketplace
This commit is contained in:
root
+33
-59
@@ -1,74 +1,48 @@
|
|||||||
# CHANGELOG — Forefront Wireless Customer Portal
|
# CHANGELOG — Forefront Wireless Operations Portal
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2026-07-25 (PM) — Multi-Source Architecture Scoped
|
## 2026-07-25 (PM) — Dual Access & Device Management Scoped
|
||||||
|
|
||||||
**Scope expansion:** The portal at my.forefrontwireless.com will aggregate data from four sources, not just Splynx:
|
### Major Design Decisions
|
||||||
|
|
||||||
### Data Sources
|
**Dual-access portal** — same domain, different views:
|
||||||
|
- `/staff/*` — role-gated (Admin, Tech, View Only)
|
||||||
|
- `/customer/*` — tied to Splynx customer record
|
||||||
|
|
||||||
| Source | Purpose | Auth | Location |
|
**Three staff roles:**
|
||||||
|--------|---------|------|----------|
|
| Role | Permissions |
|
||||||
| **Splynx v4.2** | Billing, CRM, customers, invoices, services | HMAC-SHA256 signature | Self-hosted at portal.forefrontwireless.com |
|
|------|------------|
|
||||||
| **UISP (UNMS)** | Network management, tower/AP inventory, link quality | API token | app2 Docker (unms.forefrontwireless.com) |
|
| Admin | Full CRUD — devices, billing, templates, users |
|
||||||
| **MikroTik RouterOS** | Real-time bandwidth, DHCP leases, queue stats | REST API or SSH | 5 × CCR2004 routers on network |
|
| Tech | Troubleshoot, view all equipment, reboot CPEs — no billing |
|
||||||
| **Zabbix / SNMP** | Infrastructure monitoring, SNMP for non-UISP devices, historical graphs | Zabbix API | Currently on-prem; may move to cloud |
|
| View Only | Read-only dashboards |
|
||||||
|
|
||||||
### Architecture Decision
|
**Staff dashboard = 6 device sections:**
|
||||||
The FastAPI backend is now an **aggregation layer** — read-only adapters for each source, normalizing data into a unified customer view. The backend never writes to Splynx/UISP/MikroTik/Zabbix directly; all mutations stay in the native tools.
|
1. MikroTik routers (5 × CCR2004) — status, CPU, throughput
|
||||||
|
2. Ubiquiti backhauls — point-to-point link signal/capacity
|
||||||
|
3. Customer CPEs — subscriber device health, reboot action
|
||||||
|
4. MikroTik switches — port map, PoE budget
|
||||||
|
5. Algcom PDUs & UPSs — SNMP-polled outlet/battery status
|
||||||
|
6. TPDIN Web Monitor 3s — environmental (temp/humidity/contacts)
|
||||||
|
|
||||||
### Build Phases
|
**Device inventory with auto-SNMP templates:**
|
||||||
|
- Staff add devices with make, model, IP, SNMP community, web URL
|
||||||
|
- Backend probes SNMP for unknown make/model combos
|
||||||
|
- Maps discovered OIDs → widget suggestions
|
||||||
|
- Staff approves → reusable template saved
|
||||||
|
- Any new device with same make/model inherits template automatically
|
||||||
|
|
||||||
| Phase | Sources | V1? |
|
**Customer side:**
|
||||||
|:---:|---|---|
|
- Account/billing management
|
||||||
| 1 | Splynx (billing + CRM) | Yes — core self-service |
|
- Current package view
|
||||||
| 2 | MikroTik (router telemetry) | Yes — data usage, device lists |
|
- Marketplace — browse upgrade plans, compare, request change
|
||||||
| 3 | UISP (network management) | V2 — network status, outage awareness |
|
|
||||||
| 4 | Zabbix/SNMP (infra monitoring) | V2+ — SLA dashboards, historical graphs |
|
|
||||||
|
|
||||||
### Zabbix Migration Options
|
**Portal auth separate from Splynx** — Splynx is billing source-of-truth; the portal runs its own user table with roles. Customer accounts are linked to Splynx customer IDs.
|
||||||
- **Recommended:** Cloud Zabbix + on-prem proxy — SNMP stays local, server moves to managed infra
|
|
||||||
- **Alternative:** Keep on-prem, API tunnel via Tailscale — zero cost, simple
|
|
||||||
- **For later:** Decision deferred until portal reaches Phase 4
|
|
||||||
|
|
||||||
### Page-to-Source Mapping
|
|
||||||
Every customer-facing feature mapped to its backend data provider — see README Data Aggregation Model section.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2026-07-25 (AM) — Splynx API Connection
|
## 2026-07-25 (AM) — 4-Source Architecture
|
||||||
|
|
||||||
**Context:** Germaine shared Splynx API credentials for Forefront Wireless, his WISP company. The self-hosted Splynx instance (v4.2) runs at `portal.forefrontwireless.com/admin/`. The goal is to build a branded customer portal at `my.forefrontwireless.com`.
|
Multi-source aggregation architecture: Splynx (billing/CRM), UISP (network management), MikroTik (router telemetry), Zabbix/SNMP (infrastructure monitoring). Build phases 1-4 defined. Zabbix migration options documented.
|
||||||
|
|
||||||
### Completed
|
See earlier CHANGELOG entry for Splynx API reconnaissance details.
|
||||||
|
|
||||||
- **API connection established** — Splynx API v2.0 at `/api/2.0/` verified working
|
|
||||||
- **Authentication cracked** — Signature-based auth (HMAC-SHA256) with microtime nonce. Three methods tested:
|
|
||||||
- ✅ Signature: `Splynx-EA (key=K&nonce=N&signature=S)` — works
|
|
||||||
- ✅ Access Token: POST `/admin/auth/tokens` — generates token with 30-min expiry
|
|
||||||
- ⚠️ Basic Auth: returns 403 unless "Unsecure access" is enabled on the API key
|
|
||||||
- **API key configured** — Full permissions on all resources (customers, services, finance, networking, support, tariffs, scheduling, inventory)
|
|
||||||
- **Endpoint reconnaissance** — Verified working:
|
|
||||||
- `GET /admin/customers/customer` — 43 customers (33 active, 9 disabled)
|
|
||||||
- `GET /admin/customers/customer-internet-services/{id}` — per-customer services
|
|
||||||
- `GET /admin/networking/routers` — 5 MikroTik CCR2004 routers
|
|
||||||
- `GET /admin/tariffs/internet` — 9 plans ($59.95-$299.95/mo)
|
|
||||||
- `GET /admin/finance/invoices` — billing records
|
|
||||||
- **Splynx quirks documented** — 405 on query-param service endpoints, tariff name resolution, signature nonce format
|
|
||||||
|
|
||||||
### Decisions
|
|
||||||
|
|
||||||
- **Stack:** React SPA → FastAPI backend → Splynx API v2.0. Same pattern as IntelSight and VoIPSimplicity.
|
|
||||||
- **Hosting:** CloudPanel on app3 (152.53.241.111) — keeps customer portals together
|
|
||||||
- **Auth pattern:** Server-to-server signature auth (not per-user Access Tokens) — portal handles its own user auth, backend proxies to Splynx
|
|
||||||
- **Domain:** my.forefrontwireless.com (follows ITPP product convention: my.*.com)
|
|
||||||
- **Building after:** IntelSight + LaunchCheck (shared infrastructure, shared auth patterns, reusable Super Search engine)
|
|
||||||
|
|
||||||
### Reference: API Credentials
|
|
||||||
|
|
||||||
```
|
|
||||||
Key: 5a8dc490716424f435306f2c18b4fdcb
|
|
||||||
Secret: 5773f779e5ae5aac965845a66bd857a0
|
|
||||||
Base: https://portal.forefrontwireless.com/api/2.0/
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -1,281 +1,257 @@
|
|||||||
# Forefront Wireless Customer Portal
|
# Forefront Wireless Operations Portal
|
||||||
|
|
||||||
> **Status:** Scoped & Documented — awaiting build
|
> **Status:** Scoped & Documented — awaiting build
|
||||||
> **Started:** July 25, 2026
|
> **Started:** July 25, 2026
|
||||||
> **Domain:** my.forefrontwireless.com
|
> **Domain:** my.forefrontwireless.com
|
||||||
> **Companion project:** IntelSight (shared auth — same Super Search/deepseek infra)
|
> **Access:** Dual — staff (role-based) and customer self-service
|
||||||
|
|
||||||
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.
|
Single pane of glass for Forefront Wireless operations and customer self-service. Staff get a real-time network dashboard aggregating MikroTik routers, Ubiquiti backhauls & CPEs, switches, PDUs, UPSs, and environmental monitors. Customers get account management and a service upgrade marketplace. All driven by four backend data sources — Splynx, UISP, MikroTik RouterOS, and Zabbix/SNMP.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architecture — Multi-Source Data Aggregation
|
## Access Model — Role-Based (Staff) + Customer
|
||||||
|
|
||||||
|
```
|
||||||
|
my.forefrontwireless.com
|
||||||
|
├── /login
|
||||||
|
├── /staff/* ← role-gated
|
||||||
|
└── /customer/* ← customer-gated
|
||||||
|
```
|
||||||
|
|
||||||
|
### Staff Roles
|
||||||
|
|
||||||
|
| Role | Permissions | Who |
|
||||||
|
|------|------------|-----|
|
||||||
|
| **Admin** | Full CRUD — devices, customers, SNMP templates, billing overrides, user management | Germaine |
|
||||||
|
| **Tech** | Read-write limited — troubleshoot customer issues, view all equipment, run diagnostics, reset CPEs, but no billing changes or user management | Contractors, support staff |
|
||||||
|
| **View Only** | Read-only across all dashboards — no config changes, no customer data mutation | Auditors, occasional helpers |
|
||||||
|
|
||||||
|
**Implementation:** Role stored in portal's own user table (not Splynx roles — Splynx is source-of-truth for billing, portal has its own auth). Contractors get Tech role by default.
|
||||||
|
|
||||||
|
### Customer Access
|
||||||
|
- Login (email + password, or magic link)
|
||||||
|
- Tied to their Splynx customer record
|
||||||
|
- Can only see their own account, services, and usage
|
||||||
|
- No network-level visibility
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Staff Dashboard — Real-Time Network Ops
|
||||||
|
|
||||||
|
The staff landing page is a grid of live-status cards grouped by device category:
|
||||||
|
|
||||||
|
### Section 1: MikroTik Routers
|
||||||
|
**Source:** MikroTik REST API (direct)
|
||||||
|
**Devices:** 5 × CCR2004
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| Router status | Online/offline, uptime |
|
||||||
|
| CPU / Memory | Live gauges |
|
||||||
|
| Aggregate throughput | Total in/out across all interfaces |
|
||||||
|
| Per-router drill-down | Interface stats, queues, DHCP leases, ARP |
|
||||||
|
|
||||||
|
### Section 2: Ubiquiti Backhauls (Point-to-Point Links)
|
||||||
|
**Source:** UISP API
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| Link status | Up/down, signal strength (dBm) |
|
||||||
|
| Capacity | Current throughput vs max |
|
||||||
|
| List view | All P2P links with AirMax stats |
|
||||||
|
|
||||||
|
### Section 3: Customer CPEs (Ubiquiti)
|
||||||
|
**Source:** UISP API
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| CPE status | Online/offline count, last seen |
|
||||||
|
| Signal health | Signal/chain stats from subscriber devices |
|
||||||
|
| Search | By customer name → linked CPE |
|
||||||
|
| Actions (Tech) | Reboot CPE, re-associate |
|
||||||
|
|
||||||
|
### Section 4: MikroTik Switches
|
||||||
|
**Source:** MikroTik REST API (or SNMP via Zabbix proxy)
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| Switch status | Online/offline per switch |
|
||||||
|
| Port utilization | % used, PoE budget |
|
||||||
|
| VLAN membership | Trunk/access port map |
|
||||||
|
|
||||||
|
### Section 5: PDUs & UPSs (Algcom)
|
||||||
|
**Source:** SNMP (via Zabbix or direct SNMP poll)
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| PDU outlet status | On/off per outlet, current draw |
|
||||||
|
| UPS status | Battery charge %, load %, runtime remaining |
|
||||||
|
| Alerts | On battery, low battery, overload |
|
||||||
|
|
||||||
|
### Section 6: Environmental (TPDIN Web Monitor 3)
|
||||||
|
**Source:** SNMP (via Zabbix or direct) **+** web URL scrape
|
||||||
|
|
||||||
|
| Widget | Data |
|
||||||
|
|--------|------|
|
||||||
|
| Temperature | Current, min/max 24h |
|
||||||
|
| Humidity | Current % |
|
||||||
|
| Contact sensors | Door open/closed, water detected |
|
||||||
|
| Web UI link | Direct link to TPDIN interface |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Device Inventory & SNMP Template Auto-Generation
|
||||||
|
|
||||||
|
Staff (Admin/Tech) can add new devices via the portal UI:
|
||||||
|
|
||||||
|
### Add Device Form
|
||||||
|
| Field | Example | Purpose |
|
||||||
|
|-------|---------|---------|
|
||||||
|
| **Make** | Algcom, MikroTik, TPDIN, Ubiquiti | Manufacturer |
|
||||||
|
| **Model** | ALG-PDU-8, CCR2004, W-M3 | Model identifier |
|
||||||
|
| **Category** | Router / Switch / PDU / UPS / Environmental / Backhaul / CPE | Dashboard section |
|
||||||
|
| **IP Address** | 10.x.x.x | SNMP target |
|
||||||
|
| **SNMP Community** | public / custom | For SNMP polling |
|
||||||
|
| **Web URL** | http://10.x.x.x | Direct link from dashboard |
|
||||||
|
| **SNMP Template** | algcom-pdu, tpdin-wm3, mikrotik-switch | Dropdown — existing templates |
|
||||||
|
|
||||||
|
### Auto-Template Engine
|
||||||
|
When a new make/model is added that has no existing template, the backend:
|
||||||
|
|
||||||
|
1. **Probes SNMP** — walks `1.3.6.1.2.1` (standard MIB) to discover available OIDs
|
||||||
|
2. **Identifies device** — matches sysDescr / sysObjectID against known patterns
|
||||||
|
3. **Suggests template** — maps discovered OIDs to widget types (gauge, status, counter, text)
|
||||||
|
4. **Staff approves** — one-click to save as reusable template for that make/model
|
||||||
|
|
||||||
|
Once a template exists for a make+model, any new device added with that combination inherits it automatically.
|
||||||
|
|
||||||
|
### Template Schema (per make/model)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"make": "Algcom",
|
||||||
|
"model": "ALG-PDU-8",
|
||||||
|
"category": "pdu",
|
||||||
|
"poll_interval_seconds": 60,
|
||||||
|
"widgets": [
|
||||||
|
{
|
||||||
|
"name": "Outlet 1 Current",
|
||||||
|
"oid": "1.3.6.1.4.1.x.x.x.1",
|
||||||
|
"type": "gauge",
|
||||||
|
"unit": "A",
|
||||||
|
"warning_threshold": 8,
|
||||||
|
"critical_threshold": 10
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture — 4-Source Aggregation
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────────────────────────────────────────────────────────────────────┐
|
┌──────────────────────────────────────────────────────────────────────────┐
|
||||||
│ my.forefrontwireless.com │
|
│ my.forefrontwireless.com │
|
||||||
│ (React SPA) │
|
│ ┌─────────────────────────┐ │
|
||||||
└──────────────────────────────┬───────────────────────────────────────────┘
|
│ │ React SPA │ │
|
||||||
|
│ │ /staff/* │ /customer/* │ │
|
||||||
|
│ └───────────┬─────────────┘ │
|
||||||
|
└─────────────────────────────────┼────────────────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌──────────────────────────────────────────────────────────────────────────┐
|
┌──────────────────────────────────────────────────────────────────────────┐
|
||||||
│ FastAPI Aggregation Backend │
|
│ FastAPI Aggregation Backend │
|
||||||
│ (api.forefrontwireless.com) │
|
|
||||||
│ │
|
│ │
|
||||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │
|
||||||
│ │ Splynx │ │ UISP │ │ MikroTik │ │ Zabbix / SNMP │ │
|
│ │ Splynx │ │ UISP │ │MikroTik │ │ Zabbix │ │ Direct SNMP │ │
|
||||||
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │
|
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │ Poller │ │
|
||||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
|
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘ └───────┬────────┘ │
|
||||||
└───────┼──────────────┼──────────────┼─────────────────┼──────────────────┘
|
│ │ │ │ │ │ │
|
||||||
|
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴─────┐ ┌──────┴────────┐ │
|
||||||
|
│ │ Auth │ │ Role │ │ Device │ │ SNMP │ │ Template │ │
|
||||||
|
│ │ Service │ │ Manager │ │ Registry│ │ Template │ │ Engine │ │
|
||||||
|
│ └─────────┘ └─────────┘ └─────────┘ └──────────┘ └───────────────┘ │
|
||||||
|
└──────────────────────────────────────────────────────────────────────────┘
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
▼ ▼ ▼ ▼
|
▼ ▼ ▼ ▼
|
||||||
┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
|
┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
|
||||||
│ Splynx v4.2 │ │ UISP │ │ MikroTik │ │ Zabbix │
|
│ Splynx v4.2 │ │ UISP │ │ MikroTik │ │ Zabbix │
|
||||||
│ Self-hosted │ │ (UNMS) │ │ RouterOS │ │ (existing │
|
│ Self-hosted │ │ (UNMS) │ │ RouterOS │ │ (on-prem │
|
||||||
│ portal.ffw │ │ app2 │ │ REST API │ │ on-prem or │
|
│ │ │ app2 │ │ REST API │ │ or cloud) │
|
||||||
│ .com/admin/ │ │ Docker │ │ 5 × CCR2004 │ │ cloud) │
|
|
||||||
└──────────────┘ └──────────┘ └──────────────┘ └──────────────┘
|
└──────────────┘ └──────────┘ └──────────────┘ └──────────────┘
|
||||||
billing/CRM network router stats infra health
|
billing/CRM network router stats SNMP infra
|
||||||
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
|
## Customer Portal Features
|
||||||
|
|
||||||
### V1 — Core Self-Service
|
### Dashboard
|
||||||
- [ ] Customer login (email + password, or magic link)
|
- Active services (what plan am I on?)
|
||||||
- [ ] Dashboard: active services, current bill, data usage
|
- Current bill & due date
|
||||||
- [ ] View & pay invoices (Stripe integration)
|
- Data usage (from MikroTik queue stats)
|
||||||
- [ ] Update contact info, phone, email
|
- Recent payments
|
||||||
|
|
||||||
### V2 — Network Visibility
|
### Account Management
|
||||||
- [ ] Real-time bandwidth usage (MikroTik queue stats)
|
- Update contact info (email, phone, address)
|
||||||
- [ ] Connected devices (MikroTik DHCP + ARP)
|
- Update payment method
|
||||||
- [ ] Network status indicator (UISP device health)
|
- View invoice history
|
||||||
- [ ] Outage notifications (Zabbix triggers → email/SMS)
|
|
||||||
- [ ] Support ticket submission & tracking (Splynx)
|
|
||||||
|
|
||||||
### V3 — Enhanced
|
### Marketplace — Service Upgrades
|
||||||
- [ ] Service upgrade/downgrade with proration
|
- Browse available plans (from Splynx tariffs)
|
||||||
- [ ] Usage graphs — daily/weekly/monthly (MikroTik + SNMP)
|
- Compare current plan vs upgrades
|
||||||
- [ ] Auto-pay setup (Stripe)
|
- Request upgrade (generates Splynx ticket or service change)
|
||||||
- [ ] Seasonal hold / vacation pause
|
- See prorated cost before confirming
|
||||||
- [ ] Speed test integration
|
|
||||||
|
|
||||||
### V4 — Operational
|
### Support
|
||||||
- [ ] Equipment return workflow
|
- Submit ticket (→ Splynx ticket system)
|
||||||
- [ ] Referral program
|
- View ticket status
|
||||||
- [ ] SLA dashboard (Zabbix data)
|
- Outage notifications (opt-in SMS/email)
|
||||||
- [ ] Network health map (UISP topology)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Integration Dependencies & Build Order
|
## Device Type Catalog (Staff Dashboard)
|
||||||
|
|
||||||
Because each data source has its own setup complexity, the build should be phased:
|
| Category | Devices | Data Source | Widget Type |
|
||||||
|
|----------|---------|-------------|-------------|
|
||||||
| Phase | Sources | Complexity | Dependencies |
|
| **Routers** | 5 × MikroTik CCR2004 | REST API | Status, CPU, throughput |
|
||||||
|:---:|---|:---:|---|
|
| **Backhauls** | Ubiquiti AirMax/AirFiber P2P | UISP | Link dBm, capacity |
|
||||||
| **1. Splynx** | Billing + CRM | Low | API already proven, key configured |
|
| **CPEs** | Ubiquiti subscribers | UISP | Online, signal, reboot |
|
||||||
| **2. MikroTik** | Router telemetry | Medium | Need REST API user on each CCR2004 |
|
| **Switches** | MikroTik switches | REST API / SNMP | Port map, PoE budget |
|
||||||
| **3. UISP** | Network management | Medium | Need UISP API token; app2 is live |
|
| **PDUs** | Algcom PDU | SNMP | Outlet status, current |
|
||||||
| **4. Zabbix/SNMP** | Infrastructure monitoring | High | Decision needed: cloud migration vs proxy |
|
| **UPSs** | Algcom UPS | SNMP | Battery, load, runtime |
|
||||||
|
| **Environmental** | TPDIN Web Monitor 3 | SNMP + web scrape | Temp, humidity, contacts |
|
||||||
Phases 1–2 can be V1. Phases 3–4 unlock V2 and beyond.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Splynx Quirks (Lessons Learned)
|
## Build Phases
|
||||||
|
|
||||||
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.
|
| Phase | What | Complexity |
|
||||||
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.
|
| **1** | Splynx adapter + auth system + roles + customer dashboard | Medium |
|
||||||
4. **Data is filtered by permissions** — Current API key has full permissions on all resources.
|
| **2** | MikroTik adapter + staff router/switch dashboard | Medium |
|
||||||
|
| **3** | UISP adapter + backhaul/CPE dashboard | Medium |
|
||||||
|
| **4** | SNMP poller + template engine + PDU/UPS/environmental dashboard | High |
|
||||||
|
| **5** | Customer marketplace (plan comparison + upgrade flow) | Medium |
|
||||||
|
| **6** | Device registry UI + auto-template generation | High |
|
||||||
|
|
||||||
## Zabbix Migration Considerations (When Ready)
|
---
|
||||||
|
|
||||||
| Option | Cost | Complexity | Latency |
|
## Integration Dependencies
|
||||||
|--------|:---:|:---:|:---:|
|
|
||||||
| 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.
|
| Source | Adapter Type | Auth | Status |
|
||||||
|
|--------|-------------|------|:---:|
|
||||||
|
| Splynx | REST (HMAC-SHA256 signature) | Key + secret | ✓ Proven |
|
||||||
|
| UISP | REST (API token) | Settings → Users → API Access | Token needed |
|
||||||
|
| MikroTik | REST (basic auth) | Read-only API user per router | Users needed |
|
||||||
|
| Zabbix | REST (API token) | Zabbix API user | TBD — cloud migration |
|
||||||
|
| SNMP | Direct UDP poll | Community string per device | Template needed |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
- **Splynx v2 docs:** https://api-doc.splynx.com/
|
- **Splynx v2 docs:** https://api-doc.splynx.com/
|
||||||
- **Splynx v4.2 wiki:** https://wiki.splynx.com/4_2/
|
|
||||||
- **UISP docs:** https://help.ui.com/hc/en-us/categories/360001181833-UISP
|
- **UISP docs:** https://help.ui.com/hc/en-us/categories/360001181833-UISP
|
||||||
- **MikroTik REST API:** https://help.mikrotik.com/docs/display/ROS/REST+API
|
- **MikroTik REST API:** https://help.mikrotik.com/docs/display/ROS/REST+API
|
||||||
- **Zabbix API:** https://www.zabbix.com/documentation/current/en/manual/api
|
- **Zabbix API:** https://www.zabbix.com/documentation/current/en/manual/api
|
||||||
|
|||||||
Reference in New Issue
Block a user