System Architecture Overview

The billing platform is a Rust workspace composed of 18 crates arranged in a layered dependency graph.

Crate Dependency Graph

                      ┌─────────────┐
                      │   common    │  Money, IDs, BillingError, types, tax trait
                      └──────┬──────┘
              ┌──────────────┼──────────────┬──────────────┐
              ▼              ▼              ▼              ▼
        ┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
        │metering │   │ pricing  │   │customers │   │  ledger  │
        └────┬────┘   └────┬─────┘   └──────────┘   └──────────┘
             │             │
             ▼             ▼
        ┌─────────┐   ┌──────────┐
        │ rating  │◄──│ pricing  │
        └────┬────┘   └──────────┘
             │
             ▼
       ┌──────────────┐
       │  invoicing   │  + ledger, wallet
       └──────┬───────┘
              │
    ┌─────────┼──────────┐
    ▼         ▼          ▼
┌────────┐ ┌────────┐ ┌──────────┐
│dunning │ │payments│ │contracts │
└────────┘ └────────┘ └──────────┘
              │
    ┌─────────┼──────────┐
    ▼         ▼          ▼
┌────────┐ ┌────────┐ ┌───────────────┐
│ audit  │ │ wallet │ │spend-alerts   │
└────────┘ └────────┘ └───────────────┘
              │
              ▼
     ┌───────────────────┐
     │    api-gateway    │  Axum HTTP server
     └───────────────────┘

Technology Stack

Deploy Architecture

Internet
   │
   ▼
Caddy (TLS termination, reverse proxy)
   │
   ├─► api.bill.sh → api-gateway (port 3000)
   ├─► docs.bill.sh → mdBook static site
   └─► ui.bill.sh → Askama/HTMX server-rendered UI

Infrastructure: Hetzner VPS (Ubuntu 24.04, Docker 29.x)

Key Design Principles

1. Correctness over performance: i128 pico-units eliminate money rounding bugs
2. Pure functions for business logic: rate_all(), prorate_days(), compute_true_up() have no I/O — deterministic and easily tested
3. Idempotency everywhere: All mutating operations safe to retry
4. In-memory for development: All repositories have InMemory* implementations — no database required for local dev or tests
5. Swap-in production backends: Implement Repository traits with CockroachDB/ClickHouse/TigerBeetle for production

Service Crates