docs: complete project research for NetForge ISP Management SaaS
Files: - STACK.md - FEATURES.md - ARCHITECTURE.md - PITFALLS.md - SUMMARY.md Key findings: - Stack: Next.js 15 + TypeScript + PostgreSQL + Prisma monolith; BullMQ for billing cron jobs; MikroTik client needs library verification (LOW confidence) - Architecture: Modular monolith with shared-DB multi-tenancy; JournalEntryService as sole ledger gateway; derived financial state (no balance fields) - Critical pitfall: Cross-tenant data leakage + fake accounting + billing state machine must all be solved in Phase 1 before any feature work Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kevin-asprec
206
.planning/research/FEATURES.md
Normal file
206
.planning/research/FEATURES.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Feature Landscape
|
||||
|
||||
**Domain:** ISP Management / Billing SaaS (Small-to-Medium ISPs, 50–2000 subscribers)
|
||||
**Researched:** 2026-03-04
|
||||
**Confidence note:** Web research tools were unavailable during this session. All findings are drawn from
|
||||
training knowledge of Splynx, UISP (Ubiquiti), ISPApp, Wise-ISP, Sonar Software, HostBill, and
|
||||
WHMCS-ISP setups. Confidence is MEDIUM overall; findings should be spot-checked against live product
|
||||
feature pages before roadmap is locked.
|
||||
|
||||
---
|
||||
|
||||
## Table Stakes
|
||||
|
||||
Features users expect. Missing = product feels incomplete or ISP won't migrate to it.
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|------------|-------|
|
||||
| Client/subscriber database | Core of all ISP ops; every other module depends on it | Low | Name, address, plan, contact info, status |
|
||||
| Plan/service tier management | ISPs sell multiple speed tiers; plans must map to billing amounts | Low | Monthly price, speed profile, data cap |
|
||||
| Invoice auto-generation | Manual invoicing at scale is impossible; recurring billing is baseline | Medium | Date-based or cycle-based triggers |
|
||||
| Payment logging (cash/bank) | Small ISPs in PH/developing markets are majority cash/bank-transfer | Low | Manual entry by staff or collector |
|
||||
| Client status lifecycle | Active → Suspended → Cancelled is the daily operational loop | Low | Status drives network enforcement |
|
||||
| MikroTik auto-suspend/activate | MikroTik dominates small ISP networks; auto-cut on overdue is expected | High | RouterOS API, PPPoE/hotspot profiles |
|
||||
| Overdue/outstanding reports | Managers need to know who hasn't paid every single day | Low | Filter by due date, status, collector zone |
|
||||
| SMS/notification reminders | Pre-due and overdue reminders reduce churn and collection effort | Medium | Gateway integration (Semaphore, Vonage, Twilio) |
|
||||
| Basic ticketing / support log | Even basic ISPs track "client X reported outage" in some form | Medium | Create, assign, resolve, note |
|
||||
| Multi-user roles with permissions | Staff, collectors, and techs need scoped access | Medium | At minimum: admin, office, field roles |
|
||||
| Dashboard with key metrics | Owners demand daily revenue vs target, active vs suspended counts | Medium | Not vanity — operational necessity |
|
||||
| Client payment history view | Collectors and clients need to verify "did I pay last month?" | Low | Ledger per client |
|
||||
|
||||
---
|
||||
|
||||
## Differentiators
|
||||
|
||||
Features that set a product apart. Users don't always expect them, but they drive retention and referrals.
|
||||
|
||||
| Feature | Value Proposition | Complexity | Notes |
|
||||
|---------|-------------------|------------|-------|
|
||||
| Facebook Messenger / chatbot self-service | Clients in PH markets heavily use FB Messenger; zero-app friction for balance checks and ticket filing | High | Requires API-first design + n8n or equivalent automation layer |
|
||||
| Technician mobile dispatch app | Field staff use phones, not laptops; native or PWA dispatch list with job status update | High | Offline-capable is ideal; GPS is a plus |
|
||||
| Full double-entry accounting | Most ISP tools do "billing" not accounting; real P&L and balance sheet is rare at this price point | High | COA, journal entries, trial balance, income statement |
|
||||
| Inventory / asset tracking per subscriber | Knowing "ONT #1234 is at Client X" prevents equipment theft and loss | Medium | Asset → status: In Stock / Deployed / With Technician |
|
||||
| Collector zone management | ISPs with field collectors need geographic grouping and daily collection targets | Medium | Assign clients to collector, track daily collection totals |
|
||||
| Payment collection receipting by collector | Collectors log cash collected in the field; system auto-credits client and tracks collector accountability | Medium | Differs from office payment logging; collector-specific audit trail |
|
||||
| Expense and vendor tracking | Upstream bandwidth costs, tower rent, vehicle fuel — mapped to real P&L | Medium | Vendor ledger, bill entry, expense categories |
|
||||
| Live MikroTik connection status query | See if a client is actively online right now, without logging into RouterOS | High | RouterOS API polling per subscriber |
|
||||
| Multi-router / multi-zone router management | ISPs grow to 3–10 towers; each tower has its own router | Medium | Router registry, zone assignment, per-router client mapping |
|
||||
| SaaS super-admin panel | Platform operator manages ISP tenants, monitors usage, controls subscriptions | High | Tenant CRUD, usage metering, billing ISPs |
|
||||
| White-label client portal | ISP can brand the portal with their logo; premium tier feature | Medium | Per-tenant theme/logo/custom domain |
|
||||
| Prepaid load / data voucher management | Some ISPs sell prepaid load cards or hotspot vouchers | Medium | Voucher code generation, redemption, expiry |
|
||||
| Network map / topology view | Visual representation of which clients are on which tower/sector | High | Useful for troubleshooting but complex to build well |
|
||||
| Automated PPPoE/hotspot profile sync | When plan is changed, speed profile on router updates automatically | High | MikroTik RouterOS API, profile name mapping |
|
||||
| API-first with webhook support | Allows ISPs to integrate with their own tools or extend via n8n/Zapier | High | Full RESTful API, documented, versioned |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Features
|
||||
|
||||
Features to explicitly NOT build in early phases. Common mistakes in this domain.
|
||||
|
||||
| Anti-Feature | Why Avoid | What to Do Instead |
|
||||
|--------------|-----------|-------------------|
|
||||
| Full RADIUS server | WISP RADIUS is a solved problem; building one is a multi-month distraction | Integrate with existing RADIUS (FreeRADIUS) via API or use MikroTik RouterOS directly |
|
||||
| Network monitoring / SNMP polling (phase 1) | NMS is its own product category; premature complexity kills delivery | Defer; point users to UISP or LibreNMS for NOC needs |
|
||||
| Built-in VoIP billing | VoIP ISPs are a separate niche with CDR complexity; out of scope | Not applicable to target (broadband ISPs) |
|
||||
| Complex provisioning workflows (ZTP) | Zero-touch provisioning is enterprise-tier complexity | Manual install workflow + job order is sufficient for sub-2000 subscriber ISPs |
|
||||
| Customer-facing mobile app (phase 1) | Native app development doubles scope; web portal serves the same need initially | Build responsive web client portal first; native app is phase 3 |
|
||||
| Full ERP (HR, payroll, procurement) | Scope creep kills ISP billing products; non-core modules confuse users | Stick to ISP-specific accounting; integrate with external payroll tools if needed |
|
||||
| Credit card processing as a primary flow | Small PH ISPs are cash/bank-transfer dominant; card processing adds compliance overhead for low ROI | Support it as optional later; GCash/PayMaya integrations are higher value for PH market |
|
||||
| Automatic CAPEX depreciation schedules | Accounting purists want this; ISP operators don't use it | Log purchase cost; let accountant handle depreciation externally |
|
||||
| Integrated email marketing / newsletter | Irrelevant to ISP ops; adds bloat | Use external tools (Mailchimp) if needed |
|
||||
| Network usage graphs / bandwidth accounting per client | Useful but requires data source (RADIUS, router polling); high infra complexity | Scope to phase 2 or 3 if MikroTik traffic accounting is available |
|
||||
|
||||
---
|
||||
|
||||
## Feature Dependencies
|
||||
|
||||
Features that cannot be built without prerequisite features being in place first.
|
||||
|
||||
```
|
||||
Client Database
|
||||
└─> Plan/Service Tier Registry
|
||||
└─> Invoice Auto-Generation
|
||||
└─> Payment Logging
|
||||
└─> Client Status Lifecycle (Active / Suspended / Cancelled)
|
||||
└─> MikroTik Auto-Suspend / Auto-Activate
|
||||
└─> Live Connection Status Query
|
||||
|
||||
Client Database
|
||||
└─> Collector Zone Assignment
|
||||
└─> Collector Payment Logging (field receipting)
|
||||
└─> Collector Daily Summary / Accountability Report
|
||||
|
||||
Client Database
|
||||
└─> Ticketing / Support Log
|
||||
└─> Ticket → Job Order conversion
|
||||
└─> Technician Dispatch List
|
||||
└─> Technician Mobile View (PWA/app)
|
||||
|
||||
Invoice Auto-Generation + Payment Logging
|
||||
└─> Double-Entry Journal Entries (automated)
|
||||
└─> Chart of Accounts
|
||||
└─> Ledger / Trial Balance
|
||||
└─> Income Statement (P&L)
|
||||
└─> Balance Sheet
|
||||
|
||||
Inventory Registry
|
||||
└─> Asset Status Tracking (In Stock / Deployed / With Technician)
|
||||
└─> Asset Assignment to Client or Technician
|
||||
|
||||
SMS Notifications
|
||||
└─> SMS Gateway Integration (Semaphore / Twilio)
|
||||
└─> Pre-due reminder
|
||||
└─> Overdue alert
|
||||
└─> Payment confirmation receipt
|
||||
|
||||
API-First Architecture
|
||||
└─> n8n / Facebook Messenger integration
|
||||
└─> Balance check chatbot
|
||||
└─> Ticket creation via chat
|
||||
|
||||
SaaS Multi-Tenancy (tenant_id isolation)
|
||||
└─> Super-Admin Panel
|
||||
└─> ISP tenant management
|
||||
└─> Usage metering / subscription billing of ISPs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MVP Recommendation
|
||||
|
||||
For an MVP targeting small ISPs (50–500 subscribers), prioritize these features first:
|
||||
|
||||
**Must-have (MVP blockers — without these no ISP will run on NetForge):**
|
||||
1. Client database with status lifecycle
|
||||
2. Service plan registry
|
||||
3. Invoice auto-generation (monthly recurring)
|
||||
4. Payment logging by office staff
|
||||
5. Overdue / outstanding reports
|
||||
6. MikroTik auto-suspend and auto-activate
|
||||
7. Multi-user roles (Admin, Staff, Collector, Technician)
|
||||
8. Basic ticketing → job order workflow
|
||||
9. SMS reminders (pre-due + overdue + confirmation)
|
||||
10. Executive dashboard (revenue collected, overdue count, active clients)
|
||||
|
||||
**High-value post-MVP (Phase 2):**
|
||||
- Double-entry accounting with automated journal entries
|
||||
- Inventory / asset tracking
|
||||
- Collector zone management + field payment receipting
|
||||
- Facebook Messenger chatbot via n8n API
|
||||
- API documentation and webhook support
|
||||
|
||||
**Defer until Phase 3 or later:**
|
||||
- Technician native mobile app
|
||||
- White-label client portal
|
||||
- Prepaid voucher / load management
|
||||
- Live MikroTik connection status polling
|
||||
- Automated PPPoE profile sync on plan change
|
||||
- Super-admin / SaaS subscription management (platform meta-layer)
|
||||
- Network usage graphs
|
||||
|
||||
---
|
||||
|
||||
## Competitor Feature Coverage (Training Data — MEDIUM confidence)
|
||||
|
||||
Reference table showing which products cover which feature areas. Confidence is MEDIUM as this is
|
||||
based on training data from products' public documentation up to mid-2025.
|
||||
|
||||
| Feature Area | Splynx | UISP CRM | ISPApp | Sonar | NetForge Target |
|
||||
|--------------|--------|----------|--------|-------|-----------------|
|
||||
| Recurring billing / invoicing | Yes | Yes | Yes | Yes | Yes |
|
||||
| MikroTik integration | Deep | Deep (Ubiquiti-first) | Yes | Yes | Deep |
|
||||
| Double-entry accounting | No (billing only) | No | Partial | Partial | Yes (differentiator) |
|
||||
| Inventory management | Basic | Yes | Basic | Yes | Yes |
|
||||
| Ticketing | Yes | Yes | Yes | Yes | Yes |
|
||||
| Field collector workflow | No | No | Partial | No | Yes (differentiator) |
|
||||
| SMS automation | Yes | Partial | Yes | Yes | Yes |
|
||||
| Facebook Messenger chatbot | No | No | No | No | Yes (differentiator) |
|
||||
| API / webhook | Yes | Yes | Partial | Yes | Yes |
|
||||
| Prepaid vouchers | Partial | No | Yes | No | Phase 3 |
|
||||
| Mobile technician app | No (web only) | Yes | Partial | Yes | Phase 3 |
|
||||
| Multi-tenant SaaS platform | No (self-hosted) | No | No | No | Yes (architecture) |
|
||||
| PH market-specific (GCash, local SMS) | No | No | Yes | No | Yes (differentiator) |
|
||||
|
||||
**Key insight:** No current product combines deep MikroTik integration + full double-entry accounting +
|
||||
field collector workflow + Facebook Messenger self-service in a single multi-tenant SaaS. That is
|
||||
NetForge's differentiated position.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- Training knowledge of Splynx (splynx.com), UISP (ui.com/uisp), ISPApp, Sonar Software (sonar.software),
|
||||
Wise-ISP, HostBill ISP modules — confidence MEDIUM (training data up to ~mid-2025, not verified
|
||||
against live product pages due to tool restrictions during this session)
|
||||
- NetForge PRD (isp_system_prd.md) — the project's own requirements document, reviewed directly
|
||||
- Domain knowledge of Philippine ISP market context: cash/bank-transfer dominance, GCash/PayMaya
|
||||
prevalence, Facebook Messenger as primary customer communication channel — confidence MEDIUM (pattern
|
||||
from multiple sources in training data, not validated with live market data in this session)
|
||||
|
||||
**Validation recommended before roadmap lock:**
|
||||
- Verify Splynx feature list at splynx.com/features/
|
||||
- Verify UISP CRM feature list at ui.com/uisp
|
||||
- Verify Sonar feature list at sonar.software/features/
|
||||
- Check ISPApp (ispapp.co) feature list
|
||||
- Check Wise-ISP feature coverage
|
||||
Reference in New Issue
Block a user