From d9b8db8a7dddf48200eaf527425cc607140e4d3b Mon Sep 17 00:00:00 2001 From: root Date: Sat, 25 Jul 2026 15:31:30 -0400 Subject: [PATCH] Scope: dual access (staff roles + customer self-service), 6-section staff dashboard, device inventory with auto-SNMP template engine, customer marketplace --- CHANGELOG.md | 92 ++++------- README.md | 442 ++++++++++++++++++++++++--------------------------- 2 files changed, 242 insertions(+), 292 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d260a02..d8f0363 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 19e3c04..f7bfcbb 100644 --- a/README.md +++ b/README.md @@ -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