Architecture: CRM — Usage Wallet and Rebilling

[curtisdelicata]

Implementation epic

Deliver the Usage Wallet and Rebilling capability in the CRM application repository as an independently owned, testable module. The domain specification remains authoritative for business behavior; API, Filament 5, and Livewire 4 are one-to-one presentation packages and must not move business rules into presentation code.

Source specifications

• Domain / feature: https://github.com/liberusoftware/documentation/blob/main/features/crm/usage-wallet-and-rebilling.md
• API: https://github.com/liberusoftware/documentation/blob/main/api/crm/usage-wallet-and-rebilling.md
• Filament 5: https://github.com/liberusoftware/documentation/blob/main/filament/crm/usage-wallet-and-rebilling.md
• Livewire 4: https://github.com/liberusoftware/documentation/blob/main/livewire/crm/usage-wallet-and-rebilling.md
• Shared architecture: https://github.com/liberusoftware/documentation/blob/main/MODULES.md, https://github.com/liberusoftware/documentation/blob/main/API.md, https://github.com/liberusoftware/documentation/blob/main/FILAMENT.md, https://github.com/liberusoftware/documentation/blob/main/LIVEWIRE.md, https://github.com/liberusoftware/documentation/blob/main/TESTING.md, https://github.com/liberusoftware/documentation/blob/main/DOCUMENTATION.md

Specification details

Domain

CRM: Usage Wallet and Rebilling

Canonical independent module specification

Domain module: crm-usage-wallet-and-rebilling
Application: CRM
Capability group: Partner and agency modules
Source scope: CRM.md
Architecture: MODULES.md · TESTING.md · API.md · FILAMENT.md · LIVEWIRE.md

1. Purpose

The Usage Wallet and Rebilling module owns Provider usage imports, wallets/credits, threshold reloads, cost/markup rules, client charges, exceptions, reconciliation, and Billing/Accounting handoff. It is the authoritative boundary for this capability and must remain independently installable, testable, versioned, enabled, and reusable across compatible Liberu applications.

2. Full feature scope

• Provider usage imports: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Wallets/credits: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Threshold reloads: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Cost/markup rules: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Client charges: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Exceptions: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Reconciliation: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.
• Billing/Accounting handoff: implement the complete lifecycle, validation, permissions, failure handling, audit evidence, and operator/user feedback required by this capability.

3. Ownership and boundaries

• Own the capability's domain rules, policies, actions, queries, events, persistence, migrations, configuration, audit semantics, and failure recovery.
• Expose stable contracts, immutable DTOs/read models, commands, queries, and past-tense domain events where other modules have a legitimate integration need.
• Consume identity, organizations/teams, authorization, settings, files, notifications, queues, localization, currency, and observability from the shared foundation rather than duplicating them.
• Never depend on an application's App\ classes, another module's private tables/models, a provider SDK in provider-neutral code, or an optional presentation framework.
• Keep Filament, Livewire, and HTTP API logic in matching one-to-one presentation packages when those surfaces are required.

4. Implementation strategy

Domain model

• Define aggregates, entities, value objects, enums, invariants, lifecycle states, and transition rules using the terminology in this specification.
• Make invalid states unrepresentable where practical and enforce remaining invariants at every mutation boundary.
• Use opaque stable identifiers and explicit actor, tenant, locale, timezone, and currency context where relevant.

Application layer

API contract

CRM: Usage Wallet and Rebilling API

Canonical one-to-one API module specification

API package: module-crm-usage-wallet-and-rebilling-api
Matching domain module: crm-usage-wallet-and-rebilling
Application: CRM
Source feature: Usage Wallet and Rebilling
Architecture: API.md · MODULES.md · TESTING.md

1. Purpose and ownership

This optional API presentation package exposes approved HTTP operations for the Usage Wallet and Rebilling domain module. It presents exactly one independent module, delegates all authoritative behavior to that module's public actions/queries/policies, and contains no other module's API logic.

The domain capability includes:

• Provider usage imports
• wallets/credits
• threshold reloads
• cost/markup rules
• client charges
• exceptions
• reconciliation
• Billing/Accounting handoff

Installation does not expose every capability automatically. The host application selects this package, API version, audiences, route groups, and operations in its API manifest.

2. Contract design

• Publish an OpenAPI 3.1 fragment with stable operation IDs, schemas, examples, scopes, errors, pagination, rate limits, idempotency, and deprecation metadata.

Filament surface

CRM: Usage Wallet and Rebilling Filament

Canonical one-to-one Filament 5 implementation

Filament package: module-crm-usage-wallet-and-rebilling-filament
Matching domain module: crm-usage-wallet-and-rebilling
Application: CRM
Source feature: Usage Wallet and Rebilling
Architecture: FILAMENT.md · MODULES.md · TESTING.md

1. Purpose and ownership

This optional Filament 5 presentation package presents exactly one independent domain module. It contributes reusable resources, pages, widgets, schemas, tables, infolists, and actions to application-owned panels while delegating authorization, validation, tenancy, persistence, and business rules to the crm-usage-wallet-and-rebilling public boundary. It must not contain another module's UI or depend on application App\ classes.

2. Module-specific surfaces

• Provider usage imports: resource/table/form/action or page behavior for this module's authorized workflow.
• Wallets/credits: resource/table/form/action or page behavior for this module's authorized workflow.
• Threshold reloads: resource/table/form/action or page behavior for this module's authorized workflow.
• Cost/markup rules: resource/table/form/action or page behavior for this module's authorized workflow.
• Client charges: resource/table/form/action or page behavior for this module's authorized workflow.
• Exceptions: resource/table/form/action or page behavior for this module's authorized workflow.
• Reconciliation: resource/table/form/action or page behavior for this module's authorized workflow.
• Billing/Accounting handoff: resource/table/form/action or page behavior for this module's authorized workflow.

3. Filament 5 implementation

• Register a stable module-crm-usage-wallet-and-rebilling-filament plugin and discover only classes in this package's namespace; applications attach it explicitly to each eligible panel.
• Keep resources under src/Resources, resource pages and relation managers beneath their resource, and shared module-local widgets/pages under src/Widgets and src/Pages.
• Use Filament 5 schemas, tables, infolists, actions, notifications, authorization hooks, and panel configuration as adapters over domain queries/actions; never duplicate domain invariants in form validation.

Livewire surface

CRM: Usage Wallet and Rebilling Livewire

Canonical one-to-one Livewire 4 implementation

Livewire package: module-crm-usage-wallet-and-rebilling-livewire
Matching domain module: crm-usage-wallet-and-rebilling
Application: CRM
Source feature: Usage Wallet and Rebilling
Architecture: LIVEWIRE.md · MODULES.md · TESTING.md

1. Purpose and ownership

This optional Livewire 4 presentation package provides interactive server-driven components for exactly one independent domain module. Components coordinate public queries/actions and presentation state; they do not own persistence, authorization decisions, tenancy, business rules, or theme identity. The package has no dependency on application App\ classes or another module's internals.

2. Module-specific interactions

• Provider usage imports: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Wallets/credits: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Threshold reloads: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Cost/markup rules: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Client charges: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Exceptions: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Reconciliation: interactive component state, validation feedback, loading, and failure recovery for this domain capability.
• Billing/Accounting handoff: interactive component state, validation feedback, loading, and failure recovery for this domain capability.

3. Livewire 4 implementation

• Register a stable module-crm-usage-wallet-and-rebilling-livewire component namespace and service provider; use explicit aliases such as <livewire:module-crm-usage-wallet-and-rebilling::component-name /> according to LIVEWIRE.md.
• Keep reusable components under src/Components, full-page components under src/Pages, and package views under resources/views.
• Treat public properties, URL state, events, uploads, and action parameters as untrusted input; validate and authorize at the Livewire boundary, then invoke the authoritative domain action/query.

Acceptance criteria

• Domain ownership, boundaries, data lifecycle, permissions, tenancy, events, failure recovery, telemetry, and migrations match the domain specification.
• API routes/operations/events, versioning, authentication, authorization scopes, validation, idempotency, errors, pagination, rate limits, and observability match the API specification.
• Filament package identity, panel/resource/page/widget inventory, authorization, tenancy, navigation, theme integration, accessibility, and cache/discovery behavior match the Filament specification.
• Livewire package identity, aliases, component inventory, state/actions/events, loading/failure states, authorization, tenancy, accessibility, and lifecycle behavior match the Livewire specification.
• Unit, feature, contract, architecture, security, compatibility, migration/upgrade, and presentation tests cover allowed, denied, invalid, duplicate, concurrent, wrong-tenant, partial-failure, and recovery paths as applicable.
• README, changelog, runbook, API/presentation documentation, release notes, and adoption/upgrade guidance are complete.

Explicit exclusions

Do not implement unrelated independent modules, application App namespace coupling inside reusable packages, private cross-module table/model access, provider SDK leakage into provider-neutral code, or business authorization solely in UI/API presentation layers.