PSA/ee/docs/plans/2026-03-16-service-period-first-billing-and-cadence-ownership/FEATURE_SUBSYSTEM_MAP.md

Feature-To-Subsystem Map

Purpose

Use this file to keep implementation progress traceable by subsystem instead of only by chronological feature order.

The feature list is intentionally long because the billing cutover spans runtime, persistence, read models, authoring, downstream consumers, rollout, and the later materialized-service-period ledger. This map is the index for that breadth.

Tracking Discipline

When completing work from features.json:

1. identify the primary subsystem from the map below
2. note any secondary subsystem surfaces touched by the same checkpoint
3. update SCRATCHPAD.md with the concrete files and behavior changes
4. keep commit messages scoped to the feature ID or the coherent subsystem slice being advanced

When adding new features:

1. place the new feature inside the correct subsystem band
2. update this map if the feature introduces a new subsystem or a new cross-cut seam
3. avoid creating feature IDs whose subsystem ownership is ambiguous from the artifact set

Subsystem Bands

Subsystem	Primary feature bands	What lives here
Architecture, inventory, and parity scaffolding	F001-F010, F111-F120, F147-F150	pass-0 inventory, parity harness, rollout staging, follow-on boundaries, operator/runbook artifacts
Shared recurring timing domain	F011-F020	canonical service-period types, invoice-window types, cadence owners, due-position and coverage helpers
Client-cadence generation and parity engine	F021-F040	anchored client periods, partial-period rules, first/final period semantics, zero-coverage behavior
Runtime recurring charge execution	F041-F070, F143-F146, F256-F266	fixed/product/license timing, bucket timing, canonical runtime guardrails, eventual persisted-service-period runtime consumption
Invoice generation, persistence, and recurring billing runs	F071-F080, F151-F190, F241-F242	due selection, preview/generate flows, duplicate prevention, billed-through, recurring execution identity, grouping rules, financial artifact semantics
Data model, repositories, APIs, and recurrence storage reconciliation	F081-F090, F201-F230, F243-F255	cadence-owner persistence, compatibility readers/writers, repository cleanup, authoring-path storage normalization, regeneration and override policy
Authoring UI and recurring configuration surfaces	F091-F097, F121-F124, F138-F145, F202-F210, F250-F258, F264-F266	contract-line configuration, wizards, templates, presets, dashboard copy, portal detail policy, future service-period inspection/editing surfaces
Reporting, portal readers, and accounting/export consumers	F098-F100, F125-F133, F191-F200, F222, F225-F227	invoice readers, portal billing views, report date-basis policy, export adapters, projection-mismatch diagnosis
Contract cadence and mixed-cadence behavior	F101-F110, F156-F160, F223	anniversary-based service periods, mixed-window grouping, contract-cadence due selection, contract-cadence scheduler cutover
Materialized service-period ledger	F231-F270	persisted service-period schema, lifecycle state, provenance, generation, regeneration, editing, invoice linkage, repair flows

Cross-Cut Seams To Recheck During Every Pass

• Runtime plus persistence: canonical recurring periods are only done when invoice detail writes and rereads stay coherent.
• Reader plus export surfaces: any header-versus-detail semantic change must be checked in dashboard, portal, and export consumers.
• Authoring plus storage: cadence-owner or timing defaults are only safe when wizard, template, preset, custom-line, repository, and API paths agree.
• Rollout plus cleanup: staged compatibility work must stay explicit until source and DB validation prove the legacy seam is actually dead.

Minimum Coverage Expectation

Before declaring the plan complete, the implemented feature set must still be traceable across all of these surfaces:

• runtime billing and timing domain
• invoice generation and persistence
• credits, prepayment, and negative-invoice flows
• repositories, APIs, and recurrence storage
• dashboard, wizard, template, and preset authoring
• client portal, reporting, and accounting exports
• rollout, cleanup, validation, and operator runbooks
• persisted service-period ledger design and lifecycle