# Phase 2: Subscriber and Billing Core - Context

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

<domain>
## 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.

</domain>

<decisions>
## 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

</decisions>

<specifics>
## 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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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