NetForge/.planning/REQUIREMENTS.md

# Requirements: NetForge

**Defined:** 2026-03-04
**Core Value:** ISP owners can see exactly where their money is — who owes what, what's been collected, what's been spent, and what the business actually looks like financially — in real time.

## v1 Requirements

### Multi-Tenancy & Auth

- [ ] **TENANT-01**: Each ISP tenant has fully isolated data via PostgreSQL Row-Level Security
- [ ] **TENANT-02**: New ISP can sign up and onboard with their own tenant space
- [ ] **TENANT-03**: Platform super-admin can manage all ISP tenants (create, suspend, view usage)
- [ ] **AUTH-01**: User can log in with email and password
- [ ] **AUTH-02**: Role-based access control for 5 roles: Admin, Office Staff, Collector, Technician, Client
- [ ] **AUTH-03**: Each role has scoped permissions (e.g., Collector sees only their assigned clients)
- [ ] **AUTH-04**: User session persists across browser refresh

### Subscriber Management

- [ ] **SUB-01**: Staff can register new subscriber with name, address, contact info, and assigned plan
- [ ] **SUB-02**: Staff can create and manage service plans (name, speed, monthly price, billing type)
- [ ] **SUB-03**: Subscriber has a status lifecycle: Active → Suspended → Cancelled
- [ ] **SUB-04**: Staff can view and search all subscribers with filtering by status, plan, zone
- [ ] **SUB-05**: Each subscriber has a payment history ledger showing all transactions

### Billing

- [ ] **BILL-01**: System auto-generates monthly invoices for all active subscribers based on their plan
- [ ] **BILL-02**: Billing supports both prepaid (pay before service) and postpaid (pay after service period)
- [ ] **BILL-03**: Office staff can record cash or bank payment against a subscriber's invoice
- [ ] **BILL-04**: System tracks outstanding balances per subscriber in real time
- [ ] **BILL-05**: Staff can generate overdue/outstanding reports filtered by date, status, amount
- [ ] **BILL-06**: Partial payments are supported and tracked against invoices

### Collector Management

- [ ] **COLL-01**: Collectors can record field cash collections against subscriber invoices
- [ ] **COLL-02**: System tracks total collected vs total remitted per collector (derived from transactions)
- [ ] **COLL-03**: Collectors are assigned to zones/territories with specific subscriber lists
- [ ] **COLL-04**: System generates daily collection summary report per collector
- [ ] **COLL-05**: Collectors can remit collected cash to management with a recorded transfer entry
- [ ] **COLL-06**: All collector remittances create corresponding journal entries in accounting

### Ticketing & Job Orders

- [ ] **TICK-01**: Staff can create a support ticket from a client call/text (issue description, priority, category)
- [ ] **TICK-02**: Staff can convert a ticket into a job order assigned to a technician
- [ ] **TICK-03**: Technicians can view their assigned job orders and update status (pending → in progress → completed)
- [ ] **TICK-04**: Job completion is tracked with outcome notes, date, and time
- [ ] **TICK-05**: Clients can submit tickets through the client portal

### Technician Management

- [ ] **TECH-01**: Admin can create technician profiles with contact info, skills, and assigned zone
- [ ] **TECH-02**: Admin can set fixed compensation rates per job type (e.g., installation = ₱500, repair = ₱300)
- [ ] **TECH-03**: System supports both per-job-order compensation and monthly salary models
- [ ] **TECH-04**: System generates compensation summary per technician per period (total jobs, total earned)

### Inventory & Asset Management

- [ ] **INV-01**: Staff can register hardware items (routers, ONUs, cables, connectors, splitters) with type, model, serial number
- [ ] **INV-02**: All stock movements are recorded as immutable events (received, issued, returned, disposed)
- [ ] **INV-03**: System tracks current stock levels derived from movement history (not mutable quantity)
- [ ] **INV-04**: Assets can be assigned to a subscriber (deployed at client location)
- [ ] **INV-05**: Assets can be assigned to a technician (carried for field work)
- [ ] **INV-06**: Staff can view asset history (where it's been, who had it)

### Expense Tracking

- [ ] **EXP-01**: Staff can record expenses with amount, date, category, vendor, and description
- [ ] **EXP-02**: Admin can manage expense categories (bandwidth, rent, fuel, supplies, etc.)
- [ ] **EXP-03**: Staff can manage vendors (name, contact, services provided)
- [ ] **EXP-04**: System generates expense reports by category, vendor, and period
- [ ] **EXP-05**: All expenses create corresponding journal entries in accounting

### Accounting

- [ ] **ACCT-01**: System provides a standard Chart of Accounts pre-configured for ISP business
- [ ] **ACCT-02**: All money movements (payments, expenses, collector remittances) auto-generate double-entry journal entries
- [ ] **ACCT-03**: Staff can create manual journal entries for inter-account transfers (e.g., cash-on-hand → bank)
- [ ] **ACCT-04**: System generates Income Statement (Profit & Loss) for any date range
- [ ] **ACCT-05**: System generates Balance Sheet (assets, liabilities, equity) as of any date
- [ ] **ACCT-06**: System generates Trial Balance to verify books are balanced
- [ ] **ACCT-07**: All journal entries are immutable — corrections done via reversing entries only
- [ ] **ACCT-08**: Full audit trail on every accounting entry (who created, when, reference to source transaction)
- [ ] **ACCT-09**: All account balances are derived from journal entry history (never stored as mutable values)

### Client Portal

- [ ] **PORT-01**: Subscribers can log in and view their current bill and outstanding balance
- [ ] **PORT-02**: Subscribers can view their payment history
- [ ] **PORT-03**: Subscribers can submit support tickets through the portal
- [ ] **PORT-04**: Subscribers can view their current plan details and account status
- [ ] **PORT-05**: Subscribers can make online payments through the portal (payment gateway integration)

### Dashboard & Reports

- [ ] **DASH-01**: Dashboard shows revenue collected today and this month
- [ ] **DASH-02**: Dashboard shows overdue subscriber count and total outstanding amount
- [ ] **DASH-03**: Dashboard shows active vs suspended vs cancelled subscriber counts
- [ ] **DASH-04**: Dashboard shows cash flow summary (money in vs money out)

### Testing & Infrastructure

- [ ] **INFRA-01**: Docker-based local development environment (database, services)
- [ ] **INFRA-02**: Automated unit tests for core business logic (billing, accounting, inventory)
- [ ] **INFRA-03**: Integration tests for API endpoints
- [ ] **INFRA-04**: End-to-end tests for critical user workflows

## v2 Requirements

### Notifications

- **NOTF-01**: SMS pre-due payment reminders
- **NOTF-02**: SMS overdue payment alerts
- **NOTF-03**: SMS payment confirmation receipts
- **NOTF-04**: In-app notification system

### MikroTik Integration

- **MKTK-01**: Auto-suspend subscriber on MikroTik when overdue
- **MKTK-02**: Auto-activate subscriber on MikroTik when payment received
- **MKTK-03**: Live connection status query per subscriber
- **MKTK-04**: Automated PPPoE/hotspot profile sync on plan change
- **MKTK-05**: Multi-router/multi-zone router management

### Advanced Features

- **ADV-01**: Facebook Messenger chatbot self-service (balance check, ticket filing)
- **ADV-02**: Technician mobile dispatch app (PWA)
- **ADV-03**: White-label client portal per ISP tenant
- **ADV-04**: Prepaid voucher/data load management
- **ADV-05**: API documentation and webhook support
- **ADV-06**: Network topology/map view

## Out of Scope

| Feature | Reason |
|---------|--------|
| Full RADIUS server | Solved problem — integrate with FreeRADIUS or use MikroTik directly |
| Network monitoring / SNMP | NMS is its own product — point to UISP or LibreNMS |
| VoIP billing | Different niche with CDR complexity |
| Zero-touch provisioning | Enterprise-tier complexity, manual install sufficient for <2000 subs |
| Native mobile app | Web-first with responsive design; native app deferred to v2+ |
| Full ERP (HR, payroll, procurement) | Scope creep — stick to ISP-specific operations |
| Credit card processing | PH market is cash/GCash dominant; low ROI for v1 |
| CAPEX depreciation schedules | Let accountant handle externally |
| Email marketing / newsletters | Not ISP ops — use external tools |
| Bandwidth usage graphs per client | Requires RADIUS/router polling infrastructure; defer |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| (populated during roadmap creation) | | |

**Coverage:**
- v1 requirements: 53 total
- Mapped to phases: 0 (pending roadmap)
- Unmapped: 53 ⚠️

---
*Requirements defined: 2026-03-04*
*Last updated: 2026-03-04 after initial definition*