NetForge/.planning/STATE.md

Project State

Project Reference

See: .planning/PROJECT.md (updated 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. Current focus: All 5 phases complete. Milestone v1.0 ready for audit.

Current Position

Phase: 5 of 5 (Visibility and Client Portal) Plan: 5 of 5 in phase 5 (28/28 total complete) Status: All phases complete. All plans done: 05-01, 05-02, 05-03, 05-04, 05-05. Last activity: 2026-03-05 — Phase 5 verified (76 tests, dashboard, portal, RBAC, E2E)

Progress: [████████████████████████████] 100% (28/28 plans across all phases)

Performance Metrics

Velocity:

• Total plans completed: 28
• Average duration: ~9 min
• Total execution time: ~200 min

By Phase:

Phase	Plans	Total	Avg/Plan
01-foundation	5/5 complete	41 min	8.2 min
02-subscriber-and-billing-core	5/5 complete	57 min	11.4 min
03-operational-modules	5/5 complete	~65 min	~13 min
04-inventory-expenses-reports	5/5 complete	71 min	14.2 min
05-visibility-and-client-portal	5/5 complete	~21 min	~4.2 min

Updated after each plan completion

Accumulated Context

Decisions

Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work:

• [Roadmap]: Accounting COA and JournalEntryService built in Phase 2 before first invoice — cannot be retrofitted
• [Roadmap]: Inventory modeled as event-ledger (immutable movements) from Phase 4 — mutable quantity columns explicitly rejected
• [Roadmap]: Collector balances derived from transaction log, never stored as mutable fields
• [Roadmap]: PORT-05 (online payment) scaffolded in Phase 5 but payment gateway integration deferred to v2 per project out-of-scope decision
• [05-01]: Dashboard revenue metrics use Payment.createdAt (not paymentDate) for today/month filtering
• [05-01]: Cash flow uses same approach as FinancialReportService — POSTED JE lines on revenue (4xxx) and expense (5xxx) accounts with normal balance logic
• [05-01]: getDashboardSummary runs all 5 metric methods in parallel via Promise.all
• [05-02]: Dual NextAuth credentials providers (staff id=credentials, portal id=portal-credentials) on same instance — additive, no change to staff auth
• [05-02]: Subscriber.passwordHash is nullable — only subscribers with a set password can log in to portal
• [05-02]: subscriberId persisted in JWT token and session — distinguishes portal users from staff users without DB lookup
• [05-02]: withPortalAuth HOF validates subscriberId in session; 401 if no session, 403 if not portal user
• [05-03]: ensurePortalUser creates shadow User with CLIENT role and portal-{accountNumber}@portal.local email — bridges Subscriber auth to User FK on Ticket.createdById
• [05-03]: Portal tickets use source=SUBSCRIBER (not PORTAL) — TicketSource enum has STAFF/SUBSCRIBER only
• [05-03]: TicketComment is append-only (no updatedAt, no edits/deletes) — conversation integrity preserved
• [05-03]: Closed tickets reject new comments — enforced at service layer in addTicketComment
• [05-03]: Payment scaffold computes outstanding balance in JS from SENT/PARTIAL/OVERDUE invoices — same derived-aggregation pattern
• [05-04]: RBAC tests use definePermissionsFor directly + withPermission/withPortalAuth HOF mocking — 43 tests covering all 5 roles
• [05-04]: Two-tenant isolation verified with real DB records — cross-tenant queries return null/empty
• [05-05]: E2E tests exercise services directly (not HTTP) — 16 tests across 3 critical workflows
• [05-05]: Trial balance verified balanced (debits === credits > 0) after each workflow

Pending Todos

None.

Blockers/Concerns

• [Phase 1 research flag]: MikroTik RouterOS Node.js client library maintenance status is LOW confidence — verify node-routeros vs mikronode before implementing router integration (MikroTik integration is v2, but adapter interface should be planned)
• [Phase 3 research flag]: Semaphore SMS API pricing/stability for 2026 is MEDIUM confidence — verify before any SMS work (SMS is v2, but abstraction layer design is relevant)

Session Continuity

Last session: 2026-03-05T10:00:00Z Stopped at: All 5 phases complete. Phase 5 verified — 5/5 must-haves passed. Milestone v1.0 ready for audit. Resume file: None