140 lines
13 KiB
Markdown
140 lines
13 KiB
Markdown
# Roadmap: NetForge
|
|
|
|
## Overview
|
|
|
|
NetForge is built in five phases that follow strict dependency order: the accounting and tenant foundation must exist before any money can move; subscriber and billing core must exist before collectors can reconcile; operational modules (collector workflow, ticketing, inventory, expenses) complete the data that financial reports derive from; and visibility features (dashboard, client portal) are the read layer on top of everything. Every phase delivers a coherent, independently verifiable capability. No phase is optional — skipping any one creates a gap that the next phase cannot fill.
|
|
|
|
## Phases
|
|
|
|
**Phase Numbering:**
|
|
- Integer phases (1, 2, 3): Planned milestone work
|
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
|
|
|
Decimal phases appear between their surrounding integers in numeric order.
|
|
|
|
- [x] **Phase 1: Foundation** - Multi-tenant isolation, auth, Docker dev environment, and testing infrastructure
|
|
- [ ] **Phase 2: Subscriber and Billing Core** - Subscriber management, billing engine, payment recording, and the double-entry accounting ledger
|
|
- [ ] **Phase 3: Operational Modules** - Collector workflow, ticketing system, job orders, and technician management
|
|
- [ ] **Phase 4: Inventory, Expenses, and Financial Reports** - Inventory event-ledger, asset management, expense tracking, and accounting financial statements
|
|
- [ ] **Phase 5: Visibility and Client Portal** - Dashboard metrics, client self-service portal, integration tests, and end-to-end tests
|
|
|
|
## Phase Details
|
|
|
|
### Phase 1: Foundation
|
|
**Goal**: The development environment is containerized, tenant isolation is enforced at both application and database layers, all five roles can authenticate, and the test harness proves zero cross-tenant data leakage.
|
|
**Depends on**: Nothing (first phase)
|
|
**Requirements**: TENANT-01, TENANT-02, TENANT-03, AUTH-01, AUTH-02, AUTH-03, AUTH-04, INFRA-01, INFRA-02
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Running `docker compose up` starts the full local stack (PostgreSQL, Redis, Next.js app) with no manual setup steps
|
|
2. An admin can log in with email and password and stay logged in across browser refresh; logging out ends the session
|
|
3. A user with the Technician role cannot access billing or subscriber management routes — a 403 is returned at the API layer, not just hidden in the UI
|
|
4. A new ISP tenant can be created; a query issued by Tenant A returns zero rows from Tenant B's data — verified by automated test
|
|
5. Platform super-admin can log in on a separate auth context and view all tenants without being scoped to any single tenant
|
|
**Plans**: 5 plans
|
|
|
|
Plans:
|
|
- [x] 01-01-PLAN.md — Docker environment, PostgreSQL with RLS, Redis, project scaffolding (Next.js 15 + TypeScript + Prisma)
|
|
- [x] 01-02-PLAN.md — Auth module: NextAuth credentials login, JWT with tenant_id + roles, session persistence, logout
|
|
- [x] 01-03-PLAN.md — Tenant provisioning: signup flow, Prisma tenant middleware, PostgreSQL RLS policies, isolation tests
|
|
- [x] 01-04-PLAN.md — RBAC with CASL: permission matrix for all five roles, API-layer enforcement, unauthorized access tests
|
|
- [x] 01-05-PLAN.md — Super-admin panel: tenant management UI (list, suspend, activate), comprehensive test harness
|
|
|
|
---
|
|
|
|
### Phase 2: Subscriber and Billing Core
|
|
**Goal**: Staff can register subscribers, configure service plans, generate monthly invoices on schedule, record cash and bank payments against invoices, and every financial event posts a balanced double-entry journal entry to the ledger automatically.
|
|
**Depends on**: Phase 1
|
|
**Requirements**: SUB-01, SUB-02, SUB-03, SUB-04, SUB-05, BILL-01, BILL-02, BILL-03, BILL-04, BILL-05, BILL-06, ACCT-01, ACCT-02, ACCT-03, ACCT-07, ACCT-09
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Staff can register a new subscriber with name, address, contact info, and plan assignment, and the subscriber appears in filtered search results immediately
|
|
2. The system auto-generates invoices for all active subscribers on the billing cycle date — prepaid and postpaid subscribers receive invoices following their respective state machine logic
|
|
3. Office staff can record a full or partial cash or bank payment against an invoice; the invoice status updates to partial or paid in real time
|
|
4. Every payment and invoice generation event produces a balanced journal entry in the ledger (debits = credits) with no manual accounting step required
|
|
5. Staff can generate an overdue/outstanding report filtered by date range, status, and amount showing correct outstanding balances derived from the journal — no stored balance fields exist
|
|
**Plans**: TBD
|
|
|
|
Plans:
|
|
- [ ] 02-01: Chart of Accounts — pre-configured ISP COA auto-provisioned at tenant signup, ACCT-01 and ACCT-09 (balance derivation from ledger, no mutable balance fields)
|
|
- [ ] 02-02: Journal Entry Service — JournalEntryService as sole gateway to ledger, debit=credit enforcement, immutable entries, reversing entry pattern (ACCT-02, ACCT-03, ACCT-07)
|
|
- [ ] 02-03: Subscriber management — registration, plan assignment, status lifecycle (active/suspended/cancelled), subscriber search and filtering (SUB-01, SUB-02, SUB-03, SUB-04)
|
|
- [ ] 02-04: Billing engine — prepaid and postpaid as distinct state machines, monthly invoice auto-generation via BullMQ scheduled job, due date calculation, overdue detection (BILL-01, BILL-02)
|
|
- [ ] 02-05: Payment tracker — cash/bank payment recording, partial payment support, invoice status update, outstanding balance reports, idempotency keys on payment creation, subscriber payment history ledger (BILL-03, BILL-04, BILL-05, BILL-06, SUB-05)
|
|
|
|
---
|
|
|
|
### Phase 3: Operational Modules
|
|
**Goal**: Collectors can log field cash collections and remit to management with a verified audit trail; staff can create support tickets from client calls and convert them to job orders; technicians can update their own assigned work; and the system calculates technician compensation per job or monthly salary.
|
|
**Depends on**: Phase 2
|
|
**Requirements**: COLL-01, COLL-02, COLL-03, COLL-04, COLL-05, COLL-06, TICK-01, TICK-02, TICK-03, TICK-04, TICK-05, TECH-01, TECH-02, TECH-03, TECH-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. A collector can log a cash payment against a subscriber invoice in the field; the system tracks total collected vs total remitted per collector derived from the transaction log — no stored balance field
|
|
2. A collector can remit collected cash to management; an office staff member verifies the remittance; the verification creates the corresponding double-entry journal entry (cash in transit → office cash)
|
|
3. Staff can create a support ticket from a client call, convert it to a job order, assign it to a technician, and the technician can mark it complete with outcome notes — all status transitions are synchronized between ticket and job order
|
|
4. The system generates a daily collection summary report per collector showing payments collected, remitted, and any variance
|
|
5. Admin can configure per-job compensation rates by job type; the system generates a compensation summary per technician per period correctly for both per-job and monthly-salary models
|
|
**Plans**: TBD
|
|
|
|
Plans:
|
|
- [ ] 03-01: Collector zone management — zone/territory setup, subscriber-to-collector assignment, collector role scoping (COLL-03, AUTH-03)
|
|
- [ ] 03-02: Collector field collection and remittance — payment logging by collector, two-party remittance verification, journal entry on verified remittance, daily summary report (COLL-01, COLL-02, COLL-04, COLL-05, COLL-06)
|
|
- [ ] 03-03: Ticketing system — ticket creation from staff or client call, priority and category, ticket lifecycle (open → assigned → resolved → closed), client portal ticket submission (TICK-01, TICK-05)
|
|
- [ ] 03-04: Job order workflow — ticket-to-job-order conversion, technician assignment, status tracking (pending → in progress → completed), outcome notes, ticket status synchronization (TICK-02, TICK-03, TICK-04)
|
|
- [ ] 03-05: Technician management — profiles, compensation model configuration (per-job rates by type, monthly salary), CompensationService, period compensation summary (TECH-01, TECH-02, TECH-03, TECH-04)
|
|
|
|
---
|
|
|
|
### Phase 4: Inventory, Expenses, and Financial Reports
|
|
**Goal**: Staff can track all network hardware through its full lifecycle as an immutable movement ledger; expenses are recorded and post to the ledger automatically; and the accounting module can produce a verified Trial Balance, Income Statement, and Balance Sheet from journal entry history alone.
|
|
**Depends on**: Phase 3
|
|
**Requirements**: INV-01, INV-02, INV-03, INV-04, INV-05, INV-06, EXP-01, EXP-02, EXP-03, EXP-04, EXP-05, ACCT-04, ACCT-05, ACCT-06, ACCT-08
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Staff can register a hardware item and record its movement through warehouse, technician, and subscriber locations as immutable events; current stock levels are derived from the movement history — no mutable quantity column
|
|
2. An asset assigned to a subscriber shows the full location history (where it has been and who had it)
|
|
3. Staff can record an expense with amount, date, category, and vendor; the expense automatically creates a double-entry journal entry with a full audit trail showing who created it, when, and what source transaction it references
|
|
4. Admin can generate an Income Statement for any date range and a Balance Sheet as of any date, both derived entirely from journal entry lines
|
|
5. A Trial Balance can be generated and the totals of all debit balances equal all credit balances — the books are self-verifying
|
|
**Plans**: TBD
|
|
|
|
Plans:
|
|
- [ ] 04-01: Inventory event-ledger — hardware item registration, immutable stock movement records (received, issued, returned, disposed), derived stock level computation (INV-01, INV-02, INV-03)
|
|
- [ ] 04-02: Asset management — subscriber asset assignment, technician asset assignment, asset location history, lifecycle tracking (INV-04, INV-05, INV-06)
|
|
- [ ] 04-03: Expense tracking — expense recording with category and vendor, expense category management, vendor management, expense-to-journal-entry posting (EXP-01, EXP-02, EXP-03, EXP-05)
|
|
- [ ] 04-04: Expense reports and audit trail — expense reports by category, vendor, and period; full audit trail on all journal entries (who, when, source reference) (EXP-04, ACCT-08)
|
|
- [ ] 04-05: Financial report engine — Income Statement, Balance Sheet, Trial Balance derived from journal entry history; read-only report queries with proper date range filtering (ACCT-04, ACCT-05, ACCT-06)
|
|
|
|
---
|
|
|
|
### Phase 5: Visibility and Client Portal
|
|
**Goal**: The ISP owner can see the complete financial and operational picture on a single dashboard; subscribers can log in to view their bills, payment history, and plan details, and submit tickets; and the full system is covered by integration and end-to-end tests on critical workflows.
|
|
**Depends on**: Phase 4
|
|
**Requirements**: DASH-01, DASH-02, DASH-03, DASH-04, PORT-01, PORT-02, PORT-03, PORT-04, PORT-05, INFRA-03, INFRA-04
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Dashboard shows revenue collected today and this month, overdue subscriber count, total outstanding amount, subscriber status breakdown (active/suspended/cancelled), and a cash flow summary — all updating when underlying data changes
|
|
2. A subscriber can log in to the client portal and view their current bill, outstanding balance, payment history, and current plan details — scoped strictly to their own account at both the API and data layers
|
|
3. A subscriber can submit a support ticket through the client portal and see it reflected in staff's ticket queue
|
|
4. All API endpoints have integration tests that assert correct responses for authorized and unauthorized roles, verifying API-layer RBAC is not bypassed
|
|
5. Critical user workflows (subscriber registration → invoice generation → payment recording, collector collection → remittance verification, ticket creation → job order completion) pass end-to-end tests
|
|
**Plans**: TBD
|
|
|
|
Plans:
|
|
- [ ] 05-01: Dashboard service — revenue collected, overdue counts, subscriber status counts, cash flow summary; pre-aggregated metrics with indexed queries (DASH-01, DASH-02, DASH-03, DASH-04)
|
|
- [ ] 05-02: Client portal — subscriber login, bill and balance view, payment history, plan details and account status (PORT-01, PORT-02, PORT-04)
|
|
- [ ] 05-03: Client portal ticket submission and online payment scaffold — ticket submission from portal, PORT-05 online payment interface (payment gateway integration deferred to v2 per project scope; scaffold only) (PORT-03, PORT-05)
|
|
- [ ] 05-04: Integration tests — API endpoint tests for all roles, unauthorized access assertions, two-tenant cross-contamination tests (INFRA-03)
|
|
- [ ] 05-05: End-to-end tests — critical workflow automation: subscriber registration, billing cycle, payment recording, collector remittance, ticket-to-job-order resolution (INFRA-04)
|
|
|
|
---
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
|
|
|
|
| Phase | Plans Complete | Status | Completed |
|
|
|-------|----------------|--------|-----------|
|
|
| 1. Foundation | 5/5 | ✓ Complete | 2026-03-04 |
|
|
| 2. Subscriber and Billing Core | 0/5 | Not started | - |
|
|
| 3. Operational Modules | 0/5 | Not started | - |
|
|
| 4. Inventory, Expenses, and Financial Reports | 0/5 | Not started | - |
|
|
| 5. Visibility and Client Portal | 0/5 | Not started | - |
|