# 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 - **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 - **MikroTik REST API:** https://help.mikrotik.com/docs/display/ROS/REST+API - **Zabbix API:** https://www.zabbix.com/documentation/current/en/manual/api - **Git:** https://git.itpropartner.com/ippadmin/forefront-wireless-portal