ippadmin/forefront-wireless-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Scope: dual access (staff roles + customer self-service), 6-section staff dashboard, device inventory with auto-SNMP template engine, customer marketplace

Browse Source
This commit is contained in:
root
2026-07-25 15:31:30 -04:00
parent 6b8f492b38
commit d9b8db8a7d
2 changed files with 242 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+33 -59
View File
@@ -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 |
|--------|---------|------|----------|
| **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) |
| **MikroTik RouterOS** | Real-time bandwidth, DHCP leases, queue stats | REST API or SSH | 5 × CCR2004 routers on network |
| **Zabbix / SNMP** | Infrastructure monitoring, SNMP for non-UISP devices, historical graphs | Zabbix API | Currently on-prem; may move to cloud |
**Three staff roles:**
| Role | Permissions |
|------|------------|
| Admin | Full CRUD — devices, billing, templates, users |
| Tech | Troubleshoot, view all equipment, reboot CPEs — no billing |
| View Only | Read-only dashboards |
### Architecture Decision
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.
**Staff dashboard = 6 device sections:**
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? |
|:---:|---|---|
| 1 | Splynx (billing + CRM) | Yes — core self-service |
| 2 | MikroTik (router telemetry) | Yes — data usage, device lists |
| 3 | UISP (network management) | V2 — network status, outage awareness |
| 4 | Zabbix/SNMP (infra monitoring) | V2+ — SLA dashboards, historical graphs |
**Customer side:**
- Account/billing management
- Current package view
- Marketplace — browse upgrade plans, compare, request change
### Zabbix Migration Options
- **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.
**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.
---
## 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
- **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/
```
See earlier CHANGELOG entry for Splynx API reconnaissance details.
README.md
+207 -231
View File
@@ -1,281 +1,257 @@
# Forefront Wireless Customer Portal
# Forefront Wireless Operations Portal
> **Status:** Scoped & Documented — awaiting build
> **Started:** July 25, 2026
> **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 │
│ (React SPA) │
└──────────────────────────────┬───────────────────────────────────────────┘
│ ┌─────────────────────────┐ │
│ │ React SPA │ │
│ │ /staff/* │ /customer/* │ │
│ └───────────┬─────────────┘ │
└─────────────────────────────────┼────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ FastAPI Aggregation Backend │
│ (api.forefrontwireless.com) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Splynx │ │ UISP │ │ MikroTik │ │ Zabbix / SNMP │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
└───────┼──────────────┼──────────────┼─────────────────┼──────────────────┘
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ Splynx │ │ UISP │ │MikroTik │ │ Zabbix │ │ Direct SNMP │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │ Poller │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘ └───────┬────────┘ │
│ │ │ │ │ │ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴─────┐ ┌──────┴────────┐ │
│ │ Auth │ │ Role │ │ Device │ │ SNMP │ │ Template │ │
│ │ Service │ │ Manager │ │ Registry│ │ Template │ │ Engine │ │
│ └─────────┘ └─────────┘ └─────────┘ └──────────┘ └───────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ 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) │
│ Self-hosted │ │ (UNMS) │ │ RouterOS │ │ (on-prem │
│ │ │ app2 │ │ REST API │ │ or 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
billing/CRM network router stats SNMP infra
```
---
## Portal Feature Ladder
## Customer Portal Features
### 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
### Dashboard
- Active services (what plan am I on?)
- Current bill & due date
- Data usage (from MikroTik queue stats)
- Recent payments
### 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)
### Account Management
- Update contact info (email, phone, address)
- Update payment method
- View invoice history
### 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
### Marketplace — Service Upgrades
- Browse available plans (from Splynx tariffs)
- Compare current plan vs upgrades
- Request upgrade (generates Splynx ticket or service change)
- See prorated cost before confirming
### V4 — Operational
- [ ] Equipment return workflow
- [ ] Referral program
- [ ] SLA dashboard (Zabbix data)
- [ ] Network health map (UISP topology)
### Support
- Submit ticket (→ Splynx ticket system)
- View ticket status
- Outage notifications (opt-in SMS/email)
---
## Integration Dependencies & Build Order
## Device Type Catalog (Staff Dashboard)
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.
| Category | Devices | Data Source | Widget Type |
|----------|---------|-------------|-------------|
| **Routers** | 5 × MikroTik CCR2004 | REST API | Status, CPU, throughput |
| **Backhauls** | Ubiquiti AirMax/AirFiber P2P | UISP | Link dBm, capacity |
| **CPEs** | Ubiquiti subscribers | UISP | Online, signal, reboot |
| **Switches** | MikroTik switches | REST API / SNMP | Port map, PoE budget |
| **PDUs** | Algcom PDU | SNMP | Outlet status, current |
| **UPSs** | Algcom UPS | SNMP | Battery, load, runtime |
| **Environmental** | TPDIN Web Monitor 3 | SNMP + web scrape | Temp, humidity, contacts |
---
## 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.
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.
| Phase | What | Complexity |
|:---:|------|:---:|
| **1** | Splynx adapter + auth system + roles + customer dashboard | Medium |
| **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 |
|--------|:---:|:---:|:---:|
| 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) |
## Integration Dependencies
**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
- **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