Explanation

An explanation page is a discussion. It is written for understanding rather than for use: it gives the reasoning behind a design, the alternatives that were weighed against it and the reason one of them was chosen. It argues, and it says what the choice costs.

An explanation page never states a bare contract. If you need the exact fields of a surface, Reference has them; an explanation tells you why they have that shape.

How this documentation is organised applies the same standard to the documentation itself.

Reading order

The pages build on each other in this order.

• Goals and design principles says what Tally is for and lists the eleven principles the pages below argue.
• Architecture and the provider pattern argues why the core is shared and every cloud contributes a thin adapter.
• Events as the source of truth argues why the append-only event history is authoritative and every other view is derived from it.
• Dual ingestion and reconciliation explains why events and a periodic sync are both needed, and names the two gaps the sync accepts.
• Metering separated from rating argues why usage is recorded in neutral units before any price is applied.
• Money and rounding argues why money is decimal end to end, rounded once per dimension and never summed across currencies.
• Billing period lifecycle and corrections explains why a finalized period is never edited and a late event becomes a credit note instead.
• Project registry, relations and exclusive attribution argues why projects are first-class entities linked by temporally valid relations, and why every project is billed in exactly one place.
• Commercial pricing on relations argues why discounts, surcharges and kickbacks are metadata on those relations rather than a pricing subsystem of their own.
• Worked examples walks the concept's worked examples and names the golden case each one seeded.
• OpenStack as the reference provider shows how the one provider that exists feeds the shared core, and why each of its four parts has the shape it has.
• The providers that do not exist yet keeps the unbuilt provider designs as the argument that the pattern generalises, and records that none of them is built.
• How the collector consumes a bus says why the OpenStack collector acknowledges a notification only after it is buffered, and what it drops instead.
• How reconciliation observes a cloud says what one OpenStack sync establishes, and which instant each correction ends up carrying.
• The OpenStack metrics pipeline argues why a sample reaches the store on either a push or a pull path, and why Tally ships no exporter of its own.
• The simulated OpenStack world describes the month the simulator renders and why the same seed renders it again byte for byte.
• Alerting design says why vmalert and Alertmanager are deployed the way they are, and why the repository names no receiver.
• Grafana and the read-only proxy argues why Grafana reaches the metrics store through a filtering proxy.
• Roadmap says what each phase covers and what is built.