Propose Event Sourcing for Billing: Code Review Practice

This is ADR 21, proposing that billing move to event sourcing so every invoice has a complete history. Disputes currently take support hours of digging through logs. I'd like comments here before we take it to the architecture review on the 20th.

Adocs/adr/0021-event-sourcing-for-billing.md1 of 2

Files Changed

docs/adr/

docs/adr/0021-event-sourcing-for-billing.md

Markdown · Click a line number to comment · Tap a line to comment

@@ -0,0 +1,27 @@

# 21. Event Sourcing for Billing

Status: Proposed

Deciders: Billing, Platform

## Context

Billing state lives in mutable rows across invoices, payments, and adjustments. When a customer disputes a charge, support can't tell how an invoice reached its current state, and finance rebuilds the history by hand from application logs. Last quarter that took about 140 support hours.

## Decision

We will move billing to event sourcing. Every change becomes an immutable event in a billing_events table, and the current state of each invoice is a projection built from its events. The existing invoices, payments, and adjustments tables become read-only projections.

Events are stored as JSON with a type field.

Projections are rebuilt from the start of the log on every deploy, so a fix to projection code applies to all history.

Customer name, email, and billing address are copied into each event, so a projection never needs to call another service.

## Consequences

- Every invoice has a full history, which answers disputes directly.

- Auditing is simpler, since events are never changed or deleted.

- The team will need to learn event sourcing. We will run a training session in January.

## Rollout

All billing writes move to the event store in one release, behind the billing-v2 flag.

Propose Event Sourcing for Billing

docs/adr/0021-event-sourcing-for-billing.md

docs/adr/README.md