Architecture

Runtime shape

The React developer console uses Better Auth sessions and organization permissions. Customer systems use environment-scoped API keys against the Hono /v1 API. Both surfaces call the same service and repository policy; browser sessions are never accepted as public machine authentication.

PostgreSQL owns normalized resources, encrypted raw payloads, durable operations, outbox records, idempotency, provider budgets, webhook delivery, usage, contracts, and audit history. Xero remains the source of truth for accounting records.

Provider boundary

packages/accounting defines the provider-neutral interface and contains the Xero adapter. Provider SDK objects do not cross that package boundary. Public Zod contracts live in packages/contracts and are shared by the server and console.

Read and write flow

Cached list reads query PostgreSQL. Live point reads acquire the per-connection provider budget, refresh OAuth tokens when necessary, call Xero, normalize the response, and update the cache. Writes validate a normalized contract, map it to Xero, enforce idempotency and commercial access, call the provider under its budget, cache the normalized result, and record immutable usage.

Durable work

Creating an automation commits the operation and outbox in one transaction. A dispatcher publishes an authenticated Cloud Task, and the private worker claims the operation with FOR UPDATE SKIP LOCKED. Leases allow recovery after worker termination. Retries preserve input and error history; terminal exhaustion is visible as dead_letter.

Commercial model

Commercial terms are source-owned records, not checkout-provider subscriptions. Operators create effective-dated contracts and generate monthly usage statements. This supports negotiated B2B terms, manual invoicing, and a controlled migration off an incumbent platform without coupling product access to a generic billing module.