# Brewing a Reliable Coffee Subscription Platform

BeanRoute started with a simple promise: deliver freshly roasted coffee before customers run out. Behind that promise is a scheduling system that combines subscriber preferences, roaster capacity, shipping estimates, and payment status to determine when each order should enter fulfillment.

## Modeling Subscriptions as Schedules

We store subscription preferences separately from generated orders. Each subscription records cadence, grind type, quantity, and the customer’s next target delivery date. A daily scheduler works backward from that date using the destination’s shipping estimate and the roaster’s two-day preparation window. This approach preserves an audit trail and lets customers change future deliveries without rewriting existing orders.

## Making Jobs Safe to Retry

The scheduler runs through a durable queue because payment providers, carrier APIs, and inventory services occasionally time out. Every job includes an idempotency key derived from the subscription and delivery date. Workers use that key when creating orders and charging cards, so retrying a partially completed job cannot produce duplicate shipments or charges.

```yaml
scheduler:
  batch_size: 250
  retry_limit: 5
  lock_timeout: 90s
  horizon_days: 14
```

## Handling Inventory Without Overselling

Coffee inventory changes quickly after weekly roasting runs, so we reserve beans when an order is generated rather than when it ships. Reservations expire if payment fails, while successful orders convert reservations into committed stock. When a preferred roast is unavailable, the system selects only substitutions the subscriber has explicitly allowed; otherwise, it delays the order and alerts the operations team.

## Observability That Matches the Business

Infrastructure metrics alone do not reveal whether customers will receive coffee on time. Our dashboards track subscriptions awaiting scheduling, payment recovery rates, reservation failures, and projected late deliveries by roaster. Each order also carries a correlation ID across the scheduler, payment service, and fulfillment integration, making production incidents traceable without manually joining logs.

## Lessons From Production

The most valuable design choice was treating delivery dates as customer-facing commitments rather than simple timestamps. Time zones, holidays, carrier cutoffs, and paused subscriptions all complicate scheduling, but keeping those rules centralized makes the system easier to test. As BeanRoute adds roasters and regions, this model scales by introducing new calendars and capacity constraints instead of rebuilding the subscription workflow.