S
Sheba ISP ERPDOCS
Architecture Decisions (ADRs)

ADR-007: Immutable Financial Ledger as Single Source of Truth

Architectural elimination of mutable balance columns in favor of append-only ledger entries.

ADR-007: Immutable Financial Ledger as Single Source of Truth

  • Status: ACCEPTED
  • Deciders: Lead Architect
  • Date: September 2026

Context

Legacy ISP billing software commonly relies on a single Customer.balance column updated in-place. Under high concurrency (e.g. simultaneous auto-recharge, staff payment entry, and invoice generation), lost updates and un-audited discrepancies frequently occur.

Decision

Introduce apps.finance with an append-only LedgerEntry journal:

  • Records are immutable once written; deletion or update via API is blocked.
  • Balances are mathematical projections of ledger entries.
  • Adjustments, waivers, and refunds require explicit signed Adjustment entries.
  • Financial transactions enforce Idempotency-Key headers.

Consequences

  • Positive: 100% auditable financial history; complete immunity to race conditions and lost transaction history.
  • Negative: Requires calculating balances via aggregations (optimized by storing balance_after snapshots per entry).

ADR-006: MikroTik RouterOS v7 Abstraction Layer

Encapsulating hardware communication behind a unified service adapter pattern.

ADR-008: Asynchronous Webhook & State Machine Processing

Architectural separation of HTTP webhook reception from subscriber matching and ledger mutations.

On this page

ADR-007: Immutable Financial Ledger as Single Source of TruthContextDecisionConsequences