# Forefront Wireless Operations Portal

> **Status:** Scoped & Documented — awaiting build
> **Started:** July 25, 2026
> **Domain:** my.forefrontwireless.com
> **Access:** Dual — staff (role-based) and customer self-service

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.

---

## 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            │                          │
│                     │  /staff/*  │ /customer/* │                          │
│                     └───────────┬─────────────┘                          │
└─────────────────────────────────┼────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                       FastAPI Aggregation Backend                         │
│                                                                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────────┐    │
│  │ 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     │ │ (on-prem     │
│              │ │ app2     │ │ REST API     │ │  or cloud)   │
└──────────────┘ └──────────┘ └──────────────┘ └──────────────┘
   billing/CRM     network     router stats       SNMP infra
```

---

## Customer Portal Features

### Dashboard
- Active services (what plan am I on?)
- Current bill & due date
- Data usage (from MikroTik queue stats)
- Recent payments

### Account Management
- Update contact info (email, phone, address)
- Update payment method
- View invoice history

### 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

### Support
- Submit ticket (→ Splynx ticket system)
- View ticket status
- Outage notifications (opt-in SMS/email)

---

## Device Type Catalog (Staff Dashboard)

| 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 |

---

## Build Phases

| 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 |

---

## Integration Dependencies

| 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/
- **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