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

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

### Subscriber Management

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

### Billing

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

### Collector Management

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

### Ticketing & Job Orders

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

### Technician Management

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

### Inventory & Asset Management

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

### Expense Tracking

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

### Accounting

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

- [x] **INFRA-01**: Docker-based local development environment (database, services)
- [x] **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 |
|-------------|-------|--------|
| TENANT-01 | Phase 1 | Complete |
| TENANT-02 | Phase 1 | Complete |
| TENANT-03 | Phase 1 | Complete |
| AUTH-01 | Phase 1 | Complete |
| AUTH-02 | Phase 1 | Complete |
| AUTH-03 | Phase 1 | Complete |
| AUTH-04 | Phase 1 | Complete |
| INFRA-01 | Phase 1 | Complete |
| INFRA-02 | Phase 1 | Complete |
| SUB-01 | Phase 2 | Complete |
| SUB-02 | Phase 2 | Complete |
| SUB-03 | Phase 2 | Complete |
| SUB-04 | Phase 2 | Complete |
| SUB-05 | Phase 2 | Complete |
| BILL-01 | Phase 2 | Complete |
| BILL-02 | Phase 2 | Complete |
| BILL-03 | Phase 2 | Complete |
| BILL-04 | Phase 2 | Complete |
| BILL-05 | Phase 2 | Complete |
| BILL-06 | Phase 2 | Complete |
| ACCT-01 | Phase 2 | Complete |
| ACCT-02 | Phase 2 | Complete |
| ACCT-03 | Phase 2 | Complete |
| ACCT-07 | Phase 2 | Complete |
| ACCT-09 | Phase 2 | Complete |
| COLL-01 | Phase 3 | Complete |
| COLL-02 | Phase 3 | Complete |
| COLL-03 | Phase 3 | Complete |
| COLL-04 | Phase 3 | Complete |
| COLL-05 | Phase 3 | Complete |
| COLL-06 | Phase 3 | Complete |
| TICK-01 | Phase 3 | Complete |
| TICK-02 | Phase 3 | Complete |
| TICK-03 | Phase 3 | Complete |
| TICK-04 | Phase 3 | Complete |
| TICK-05 | Phase 3 | Complete |
| TECH-01 | Phase 3 | Complete |
| TECH-02 | Phase 3 | Complete |
| TECH-03 | Phase 3 | Complete |
| TECH-04 | Phase 3 | Complete |
| INV-01 | Phase 4 | Complete |
| INV-02 | Phase 4 | Complete |
| INV-03 | Phase 4 | Complete |
| INV-04 | Phase 4 | Complete |
| INV-05 | Phase 4 | Complete |
| INV-06 | Phase 4 | Complete |
| EXP-01 | Phase 4 | Complete |
| EXP-02 | Phase 4 | Complete |
| EXP-03 | Phase 4 | Complete |
| EXP-04 | Phase 4 | Complete |
| EXP-05 | Phase 4 | Complete |
| ACCT-04 | Phase 4 | Complete |
| ACCT-05 | Phase 4 | Complete |
| ACCT-06 | Phase 4 | Complete |
| ACCT-08 | Phase 4 | Complete |
| DASH-01 | Phase 5 | Pending |
| DASH-02 | Phase 5 | Pending |
| DASH-03 | Phase 5 | Pending |
| DASH-04 | Phase 5 | Pending |
| PORT-01 | Phase 5 | Pending |
| PORT-02 | Phase 5 | Pending |
| PORT-03 | Phase 5 | Pending |
| PORT-04 | Phase 5 | Pending |
| PORT-05 | Phase 5 | Pending |
| INFRA-03 | Phase 5 | Pending |
| INFRA-04 | Phase 5 | Pending |

**Coverage:**
- v1 requirements: 66 total (note: original count of 53 excluded PORT, DASH, and INFRA categories which are v1 scope)
- Mapped to phases: 66
- Unmapped: 0 ✓

**Coverage note on PORT-05:** PORT-05 (online payment gateway integration) is listed in v1 requirements but is noted as out of scope in PROJECT.md ("Automated billing integration with payment gateways — v1 tracks payments, gateway integration later"). It is included in Phase 5 as a UI scaffold only — the interface is built but the actual payment gateway connection is deferred to v2.

---
*Requirements defined: 2026-03-04*
*Last updated: 2026-03-04 after roadmap creation — traceability populated*