NetForge/.planning/phases/02-subscriber-and-billing-core/02-CONTEXT.md

Phase 2: Subscriber and Billing Core - Context

Gathered: 2026-03-04 Status: Ready for planning

## Phase Boundary

Subscriber management (registration, plan assignment, status lifecycle), billing engine (prepaid/postpaid invoice generation), payment recording (cash/bank, partial, overpayment), and the double-entry accounting ledger (Chart of Accounts, JournalEntryService, manual entries). No collector workflows, no ticketing, no reports beyond outstanding balance — those are later phases.

## Implementation Decisions

Subscriber Lifecycle

• Statuses: Active, Suspended, Cancelled
• Suspension triggers: both automatic (configurable days overdue per tenant) AND manual (staff can suspend/unsuspend anytime)
• Auto-suspend threshold is a per-tenant setting (each ISP configures their own overdue days)
• Reactivation requires full payment of outstanding balance — no reactivation with unpaid debt
• Cancellation is reversible — cancelled subscribers can be reactivated with their full history intact (not a new record)

Billing Models

• Prepaid = pay before the service period starts; postpaid = use service, get billed after
• Invoice generation is anniversary-based (each subscriber billed on their signup date, not a fixed monthly date)
• Prepaid invoices generated X days before the billing date to give subscribers time to pay
• Plan changes take effect on the next billing cycle — no proration needed
• No load-based/usage-based billing — this is flat monthly plans only

Payment Recording

• Payment fields: Claude's discretion on the right set (amount, method, reference, date, invoice allocation are expected)
• Overpayment creates a credit balance that auto-applies to the next invoice
• Partial payments supported — applied to oldest unpaid invoice first (FIFO)
• Payment voids/reversals allowed for Admin and Office Staff — implemented as reversing journal entries (no deletion)
• Idempotency keys on payment creation to prevent double-recording

Chart of Accounts & Ledger

• Pre-configured ISP-specific Chart of Accounts auto-provisioned at tenant signup — not customizable in v1
• Journal entries visible to Admin only — staff sees only reports and summaries
• Manual journal entries (e.g., cash-on-hand to bank) use maker-checker workflow — one person creates, another approves
• Accounting periods enforced — Admin can close a month, no entries allowed in closed periods
• All journal entries are immutable — corrections via reversing entries only
• All balances derived from journal entry history — no mutable balance fields anywhere

Claude's Discretion

• Payment input fields (reasonable set expected)
• Pre-configured COA account list (standard ISP accounts: revenue, COGS, operating expenses, assets, liabilities, equity)
• Prepaid invoice lead time (how many days before billing date)
• Invoice numbering scheme
• Outstanding balance report layout and filters
• Service plan fields beyond name, speed, and monthly price

## Specific Ideas

• Small ISPs often have one person doing everything — the maker-checker workflow should be optional or have a "self-approve" override for single-person operations
• FIFO payment allocation is how most Philippine ISPs work — collectors in the field just collect whatever the subscriber can pay and it goes to the oldest bill
• Credit balance is important because some subscribers prepay multiple months when they have cash on hand

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 02-subscriber-and-billing-core Context gathered: 2026-03-04