NetForge/.planning/ROADMAP.md

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.

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

• 01-01-PLAN.md — Docker environment, PostgreSQL with RLS, Redis, project scaffolding (Next.js 15 + TypeScript + Prisma)
• 01-02-PLAN.md — Auth module: NextAuth credentials login, JWT with tenant_id + roles, session persistence, logout
• 01-03-PLAN.md — Tenant provisioning: signup flow, Prisma tenant middleware, PostgreSQL RLS policies, isolation tests
• 01-04-PLAN.md — RBAC with CASL: permission matrix for all five roles, API-layer enforcement, unauthorized access tests
• 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	0/5	Planned	-
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	-