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.

- [x] **Phase 1: Foundation** - Multi-tenant isolation, auth, Docker dev environment, and testing infrastructure
- [x] **Phase 2: Subscriber and Billing Core** - Subscriber management, billing engine, payment recording, and the double-entry accounting ledger
- [x] **Phase 3: Operational Modules** - Collector workflow, ticketing system, job orders, and technician management
- [x] **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 (gap closure in progress)

## 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**: 5 plans

Plans:
- [x] 02-01-PLAN.md — Chart of Accounts: ISP COA auto-provisioned at tenant signup, accounting period management (ACCT-01, ACCT-09)
- [x] 02-02-PLAN.md — Journal Entry Service: sole ledger gateway, debit=credit enforcement, immutable entries, reversing entries, maker-checker (ACCT-02, ACCT-03, ACCT-07)
- [x] 02-03-PLAN.md — Subscriber management: registration, plan assignment, status lifecycle, search and filtering (SUB-01, SUB-02, SUB-03, SUB-04)
- [x] 02-04-PLAN.md — Billing engine: prepaid/postpaid invoice generation, anniversary billing, overdue detection, journal entry per invoice (BILL-01, BILL-02)
- [x] 02-05-PLAN.md — Payment tracker: FIFO allocation, partial/full/overpayment, void with reversing entries, outstanding report, payment history (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**: 5 plans

Plans:
- [x] 03-01-PLAN.md — Zone management: zone CRUD, subscriber-to-zone assignment, collector-to-zone assignment, collector-scoped subscriber queries (COLL-03, AUTH-03)
- [x] 03-02-PLAN.md — Collector field collection and remittance: FIFO payment via Cash in Transit, two-party remittance verification with JE, daily collection summary report (COLL-01, COLL-02, COLL-04, COLL-05, COLL-06)
- [x] 03-03-PLAN.md — Ticketing system: ticket CRUD with lifecycle (OPEN/ASSIGNED/RESOLVED/CLOSED), admin-configurable categories with ISP defaults, priority levels (TICK-01, TICK-05)
- [x] 03-04-PLAN.md — Job order workflow: ticket-to-job conversion (1:many), technician assignment, status lifecycle, auto-resolve ticket when all jobs complete (TICK-02, TICK-03, TICK-04)
- [x] 03-05-PLAN.md — Technician management: profiles with skills/zone, hybrid compensation model (per-job + salary), CompensationService, period summary report (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**: 5 plans

Plans:
- [x] 04-01-PLAN.md — Inventory event-ledger: hardware item registration, immutable stock movements, derived stock levels, JE posting for receiving (INV-01, INV-02, INV-03)
- [x] 04-02-PLAN.md — Asset management: subscriber/technician asset assignment, return with condition, admin-only disposal with write-off JE, location history (INV-04, INV-05, INV-06)
- [x] 04-03-PLAN.md — Expense tracking: expense recording with category/vendor, expense category seeding, vendor CRUD, expense-to-JE posting (EXP-01, EXP-02, EXP-03, EXP-05)
- [x] 04-04-PLAN.md — Expense reports and audit trail: reports by category/vendor/period, JE audit trail with creator and source reference (EXP-04, ACCT-08)
- [x] 04-05-PLAN.md — Financial report engine: Trial Balance, Income Statement, Balance Sheet from JE history, account drill-down (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**: 7 plans

Plans:
- [x] 05-01-PLAN.md — Dashboard service: revenue metrics, overdue counts, subscriber status breakdown, cash flow summary, collector summary (DASH-01, DASH-02, DASH-03, DASH-04)
- [x] 05-02-PLAN.md — Portal auth and account view: subscriber login via account number, bill/balance view, payment history, plan details (PORT-01, PORT-02, PORT-04)
- [x] 05-03-PLAN.md — Portal tickets and payment scaffold: ticket submission with conversation threads, online payment "coming soon" page (PORT-03, PORT-05)
- [x] 05-04-PLAN.md — Integration tests: API RBAC enforcement for all 5 roles, unauthorized access assertions, two-tenant isolation tests (INFRA-03)
- [x] 05-05-PLAN.md — End-to-end tests: billing workflow, collection/remittance workflow, ticket-to-job-order workflow (INFRA-04)
- [ ] 05-06-PLAN.md — Gap closure: fix tenant scoping for 6 missing models, add Collection/Remittance CASL subjects (P0 security + tech debt)
- [ ] 05-07-PLAN.md — Gap closure: inventory/expense and portal ticket E2E tests, Phase 2 verification correction (tech debt)

---

## 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 | 5/5 | Complete | 2026-03-04 |
| 3. Operational Modules | 5/5 | Complete | 2026-03-05 |
| 4. Inventory, Expenses, and Financial Reports | 5/5 | Complete | 2026-03-06 |
| 5. Visibility and Client Portal | 5/7 | Gap Closure | 2026-03-05 |