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: Phase 5 in progress — Visibility and Client Portal.

Current Position

Phase: 5 of 5 (Visibility and Client Portal) Plan: 4 of 5 in phase 5 (27/28 total complete) Status: In progress. 05-01, 05-02, 05-03, and 05-05 complete. Last activity: 2026-03-05 — Completed 05-05-PLAN.md (E2E Workflow Tests — 16 tests proving billing, collection/remittance, and ticket/job-order workflows)

Progress: [███████████████████████████░] 96% (27/28 plans across all phases)

Performance Metrics

Velocity:

• Total plans completed: 19
• Average duration: 9.7 min
• Total execution time: 185 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	4/5 complete	15 min	3.75 min

Recent Trend:

• Last 10 plans: 04-01 (16 min), 04-03 (17 min), 04-05 (10 min), 04-02 (8 min), 04-04 (20 min), 05-01 (3 min), 05-02 (4 min), 05-03 (5 min), 05-05 (3 min)
• Trend: Phase 5 plans executing fast — service + API + tests pattern, minimal schema changes

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
• [01-01]: DATABASE_URL uses Docker service name db (for app container); DATABASE_URL_LOCAL uses localhost:5432 (for host Prisma CLI)
• [01-01]: tenantId is nullable on User — super-admins have no tenant scope, avoiding a separate SuperAdmin model
• [01-01]: Email uniqueness is @@unique([email, tenantId]) — same email can exist across different tenants (realistic for ISP domain)
• [01-01]: Grace period fields (suspendedAt, gracePeriodEndsAt) included on Tenant at schema creation — cannot be retrofit later
• [01-02]: NextAuth v4 chosen over v5/Auth.js beta — credentials provider stability priority
• [01-02]: JWT carries tenantId + roles directly — no DB lookup on each request, stateless multi-tenancy
• [01-02]: Super-admin authorize uses OR [isSuperAdmin, tenant.status=ACTIVE] — one Prisma query handles both user types
• [01-02]: Seed uses findFirst+create for super-admin (null tenantId) — PostgreSQL NULL != NULL in unique constraints, upsert would create duplicates
• [01-02]: SessionProvider wrapped at root layout via Providers component — enables useSession() in all client components
• [01-03]: withTenantContext() creates new $extends per call — correct pattern, $extends is lightweight and request-scoped context is right
• [01-03]: findUnique cross-tenant protection routes through findFirst internally — Prisma unique key cannot have tenantId injected without changing where shape
• [01-03]: RLS USING allows null app.current_tenant_id — super-admin mode (no tenant context) sees all rows
• [01-03]: Initial migration baselined with migrate resolve --applied (schema was created via db push in 01-01)
• [01-04]: createMongoAbility used throughout (not PureAbility) — string subjects require conditionsMatcher which createMongoAbility provides built-in
• [01-04]: cannot() rules excluded when merging multi-role abilities — additive union means more roles = more (never less) access
• [01-04]: Condition objects cast via any for string subjects — CASL infers MongoQuery for strings; tighten when Prisma models defined in Phase 2+
• [01-04]: Technician can("read", "Subscriber") coarse-grained — data layer enforces actual scope to assigned job contacts only
• [01-04]: withPermission() HOF wraps Next.js route handlers; authorize() as convenience alias
• [01-05]: withSuperAdmin() implemented as standalone HOF (not via CASL) — super-admin access is binary, not permission-based
• [01-05]: Next.js 15 route params wrapped in Promise

  — HOF awaits params before passing to handler

• [01-05]: subscriberCount hardcoded to 0 in admin API — Subscriber model added in Phase 2; API shape is forward-compatible
• [01-05]: Dual guard strategy for /admin: middleware.ts (JWT edge), layout.tsx (server), API handlers (endpoint) — three defense-in-depth layers
• [02-01]: ISP COA has 28 accounts (5 category headers 1000/2000/3000/4000/5000 + 23 leaf accounts) — hierarchical for reporting
• [02-01]: Subscriber Credits (1150) is contra-asset with CREDIT normal balance — correctly reduces AR for overpayments
• [02-01]: seedChartOfAccounts receives Prisma tx client — works inside createTenant $transaction for atomic provisioning
• [02-01]: Accounting periods created on-demand via getOpenPeriod() — not pre-seeded on signup (no wasted periods for unused months)
• [02-01]: close route uses closure pattern over withPermission HOF — withPermission doesn't support dynamic params directly; POST fn closes over Next.js params
• [02-02]: JournalEntry self-referential reversal uses reversesEntryId @unique — one-to-one Prisma relation requires unique; semantically correct (one entry reverses at most one other)
• [02-02]: tenantId passed explicitly in $transaction callbacks — raw tx client lacks the withTenantContext() extension; must inject tenantId manually in create data
• [02-02]: startDate added to getAccountBalance — enables date-range balance queries; needed for period-scoped reporting and test isolation
• [02-02]: Integer cents for debit=credit validation — Math.round(n*100) avoids floating point drift on decimal amounts
• [02-02]: SYSTEM source auto-posts (POSTED status), MANUAL entries start DRAFT for maker-checker workflow
• [02-02]: Self-approval allowed — single-person ISP operations are common; blocking self-approval breaks common use case
• [02-02]: JournalEntryService is sole gateway — NO other code may write to JournalEntry/JournalEntryLine directly
• [02-03]: creditBalance on Subscriber is operational convenience (FIFO credit allocation for 02-05), NOT a ledger balance — always updated atomically with journal entries
• [02-03]: billingDay capped at 28 — subscribers signing up on days 29-31 get billingDay=28 to avoid month-length invoice generation issues
• [02-03]: CANCELLED -> ACTIVE transition is reversible by design — ISPs frequently reinstate cancelled accounts per CONTEXT.md
• [02-03]: as any cast in service create() calls — Prisma static type requires tenantId but withTenantContext() extension injects at runtime; cast is intentional
• [02-04]: Invoice.amountPaid is transactional convenience field, NOT standalone stored balance — always updated atomically with JEs (same pattern as creditBalance from 02-03)
• [02-04]: shouldBillToday PREPAID month-wrapping: actualLeadDay = lastDayOfCurrentMonth + (billingDay - leadDays) — uses current month's last day, not previous month's
• [02-04]: generateInvoiceForSubscriber returns null (not error) for duplicates — idempotent by design; generateMonthlyInvoices tracks in skipped array
• [02-04]: CreditService is standalone module — applyCredit() callable from BillingService (auto-apply) and PaymentService (02-05 overpayment)
• [02-04]: Dynamic route handlers pattern: export function GET/POST(req, { params }) wrapping withPermission()(handler)(req) — required for Next.js 15 Promise params in [id] routes
• [02-05]: PaymentAllocation as separate model — enables per-invoice allocation queries and void recalculation; each allocation row: paymentId + invoiceId + amount
• [02-05]: FIFO by dueDate ASC — oldest due date allocated first (matches standard ISP billing practice)
• [02-05]: Overpayment to subscriber.creditBalance atomically with JE — same pattern as invoice.amountPaid from 02-04
• [02-05]: Outstanding report computed in JS after fetching — Prisma doesn't support computed fields in WHERE/ORDER BY; acceptable for ISP scale
• [02-05]: Test invoiceCounter for periodStart uniqueness — monotonic counter generates unique periodStart per invoice, avoids @@unique([tenantId, subscriberId, periodStart]) in test helpers
• [03-01]: Collector security boundary enforced at service layer: getCollectorSubscribers THROWS (not empty return) when collector has no zone assignments — zero-access default
• [03-01]: ZoneAssignment upsert for idempotent collector assignment — duplicate assign calls don't throw errors
• [03-01]: Subscriber.zone String? replaced with Subscriber.zoneId FK — required for relational queries and JOIN-based ordering
• [03-01]: COLLECTOR gets can("read", "Zone") in CASL: coarse-grained gate, data layer enforces which specific zones
• [03-01]: Migration applied via Docker exec psql + prisma migrate resolve --applied (non-interactive CLI workaround)
• [03-03]: VALID_TICKET_TRANSITIONS guard map: OPEN->[ASSIGNED,CLOSED], ASSIGNED->[OPEN,RESOLVED], RESOLVED->[CLOSED,OPEN], CLOSED->[] (terminal)
• [03-03]: resolveTicket is idempotent — checks if already RESOLVED and returns silently, preventing race conditions from multiple job completions
• [03-03]: Ticket cleanup order in tests: tickets -> ticketCategories -> subscribers -> ... (categories seeded by createTenant must be deleted on teardown)
• [03-03]: transitionTicketStatus is the single gateway for status changes — updateTicket explicitly excludes status field
• [03-03]: 6 default ISP categories seeded in createTenant $transaction (No Connection, Slow Speed, Billing Inquiry, New Installation, Equipment Issue, Other)
• [03-02]: Collection JE uses 1030 Cash in Transit (not 1010) — cash is in collector's hands until remitted to office
• [03-02]: Remittance JE uses verifiedTotal on both DR 1010 and CR 1030 sides — variance is recorded on remittance record, not in ledger
• [03-02]: Variance is non-blocking — any discrepancy is an audit record; remittance proceeds to VERIFIED regardless
• [03-02]: Collection cleanup order: collectionAllocations → collections → invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → zoneAssignments → subscribers → zones → servicePlans → accountingPeriods → accounts → users → tenant
• [03-02]: ISP COA now has 29 accounts — added 1030 Cash in Transit between 1020 Cash in Bank and 1100 AR
• [03-04]: checkTicketAutoResolve counts non-cancelled jobs: if count > 0 AND all COMPLETED -> resolve; if count == 0 (all cancelled) -> skip (revertToOpen handles that path)
• [03-04]: checkTicketRevertToOpen only triggers on ASSIGNED tickets — RESOLVED/CLOSED tickets not reverted even if all jobs are cancelled
• [03-04]: COMPLETED requires outcomeNotes validated at service layer (not API) — enforces completeness regardless of caller
• [03-04]: TECHNICIAN self-service via getMyJobOrders delegates to listJobOrders with assignedToId filter; GET /api/job-orders checks !ADMIN && !OFFICE_STAFF for auto-filter to handle multi-role users
• [03-05]: User.technicianProfiles is one-to-many (not one-to-one) — Prisma requires @unique on FK for one-to-one; compound @@unique([tenantId,userId]) enforces one-per-tenant at DB; findFirst enforces at app layer
• [03-05]: Missing job type rate defaults to 0 bonus — rateMap.get(jobType) ?? Decimal(0); not an error per design spec
• [03-05]: SALARY model detail returns jobs with rate=0 — consistent API shape across all 3 models; all detail responses have a jobs array
• [03-05]: Compensation cleanup order in tests: jobOrders -> tickets -> ticketCategories -> jobTypeRates -> technicianProfiles -> zoneAssignments -> subscribers -> zones -> servicePlans -> users -> tenant
• [04-01]: Only RECEIVED movements auto-post JEs (DR 1200, CR 2010) — ISSUED/RETURNED/DISPOSED/TRANSFERRED do not create JEs
• [04-01]: CASL subject is "Inventory" (existing type in types.ts) — OFFICE_STAFF gets can("manage", "Inventory")
• [04-01]: Stock levels derived in JS from movement aggregation — acceptable for ISP scale (same pattern as collector balances, outstanding reports)
• [04-01]: Inventory cleanup order in tests: stockMovements -> inventoryItems -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> users -> tenant
• [04-03]: ExpensePaymentMethod determines CR account: CASH->1010, BANK_TRANSFER/CHECK->1020
• [04-03]: Default behavior is immediate post (no approval required); requireApproval flag enables DRAFT-only creation
• [04-03]: System expense categories (isSystemCategory=true) cannot be deleted; custom categories deletable if no expenses reference them
• [04-03]: Vendor added as CASL subject; OFFICE_STAFF gets manage Expense and manage Vendor
• [04-03]: ISP COA now has 31 accounts — added 5080 Fuel/Transportation, 5085 Rent Expense
• [04-03]: Expense cleanup order: expenses -> vendors -> expenseCategories (non-system) -> journalEntryLines -> null reversesEntryId -> journalEntries -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant
• [04-05]: FinancialReportService already existed — 04-05 created API routes and tests only
• [04-05]: All 3 financial reports derived entirely from POSTED JE lines — no stored balances
• [04-05]: Balance Sheet Net Income computed inline from revenue - expenses (beginning of time to asOfDate)
• [04-02]: AssetService delegates all movement recording to InventoryService.recordMovement — no direct StockMovement writes
• [04-02]: Disposal JE created separately before DISPOSED movement — InventoryService only auto-creates JEs for RECEIVED
• [04-02]: getCurrentLocation derives from latest movement's to-fields (null for DISPOSED)
• [04-02]: returnAsset always returns to main-warehouse — single warehouse model sufficient for ISP scale
• [04-02]: History name resolution uses batch queries then Map lookup — avoids N+1
• [04-02]: Asset cleanup order in tests: stockMovements -> inventoryItems -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> accountingPeriods -> accounts -> users -> tenant
• [04-04]: Expense aggregation done in JS after findMany -- same pattern as outstanding reports, collector balances (acceptable for ISP scale)
• [04-04]: AuditTrailService queries JEs by referenceType+referenceId -- works for all sources (Invoice, Payment, Expense, Collection, etc.)
• [04-04]: Expense report cleanup order: expenses -> vendors -> expenseCategories (custom) -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant
• [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-01]: Dashboard cleanup order: expenses -> vendors -> expenseCategories (custom) -> collectionAllocations -> collections -> remittances -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> zoneAssignments -> subscribers -> zones -> servicePlans -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant
• [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-02]: Portal cleanup order: payments -> paymentAllocations -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> tenantSettings -> accountingPeriods -> accounts -> users -> tenant
• [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-03]: Portal ticket cleanup order: ticketComments -> tickets -> ticketCategories -> subscribers -> servicePlans -> tenantSettings -> accountingPeriods -> accounts -> users -> tenant
• [05-05]: E2E tests use service functions directly (not HTTP) — tests integration layer, not transport
• [05-05]: Integration test directory: src/lib/tests/integration/ for cross-service tests
• [05-05]: Comprehensive cleanup order covers 25+ models in FK dependency order for full-system tests

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)
• [01-04 note]: CASL condition types for string subjects use any cast — upgrade to class-based subjects when Phase 2 Prisma models (Subscriber, Invoice, etc.) are defined
• [01-05 note]: /admin/tenants/[id] detail page is a stub link ("View") — detail view not implemented yet (out of Phase 1 scope)
• [02-02 note]: JournalEntry afterAll cleanup needs explicit order (lines → null reversesEntryId → entries → tenant) — document for any future test that involves journal entries
• [02-04 note]: Invoice cleanup order in tests: invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → subscribers → servicePlans → tenantSettings → accountingPeriods → accounts → users → tenant
• [02-05 note]: Payment cleanup order in tests: paymentAllocations → payments → invoiceLines → invoices → journalEntryLines → null reversesEntryId → journalEntries → subscribers → servicePlans → tenantSettings → accountingPeriods → accounts → users → tenant

Session Continuity

Last session: 2026-03-05T09:42:00Z Stopped at: Completed 05-05-PLAN.md (E2E Workflow Tests — 16 tests, 3 critical business workflows, INFRA-04 satisfied). Resume file: None