Case study
Receipts Platform
Work on the system underneath a trust-first product: typed contracts, package boundaries, background jobs, and operational controls that make change possible.
Tension
The product problem beneath the work.
Receipts has several kinds of complexity at once: evidence collection, media processing, AI analysis, search indexing, ranking, public routes, admin workflows, and operator tooling. Without clear boundaries, that kind of product becomes hard to change exactly when it most needs to be inspectable.
Threads
Three platform contracts behind a product that can be operated.
Owned
What I was responsible for, and what it changed.
| Thread | Work | Signal |
|---|---|---|
| Platform boundaries | Shaped the monorepo around delivery, runtime, adapter, domain, and contract layers with boundary checks, package ownership, and typed API contracts. | Web, API, CLI, worker, and future mobile clients can share behaviour without importing the wrong runtime concerns. |
| Async work | Built job boundaries where the API validates and enqueues work, while workers claim Postgres queues for media processing, AI analysis, search indexing, and cleanup. | Heavy work can retry, back off, report status, and hand off follow-up indexing without blocking user-facing routes. |
| Operational control | Built ops surfaces and CLI commands for feature flags, DB targets, migrations, search smoke tests, endpoint audits, worker health, and observability. | Operational work becomes inspectable and reversible instead of hidden in deploy memory. |
Mechanism
The technical layers behind those responsibilities.
| Layer | Detail |
|---|---|
| Architecture | TanStack Start web, Hono API, CLI, worker, mobile smoke scaffold, and packages for contracts, domain, data, jobs, and observability. |
| Contracts | /v1 APIs use shared Zod contracts, stable response envelopes, a typed API client, and mobile smoke checks. |
| Media queue | The API validates signed uploads and enqueues processing; workers create derivatives, activate assets, and enqueue search refresh. |
| AI analysis | Image analysis runs as queued work with retry/backoff, trace context, and browser-safe status messages. |
| Search indexing | Provider search documents refresh through queue jobs and Postgres-backed projections. |
| Observability | Structured logs, Sentry capture, request correlation, DB audit events, and health/readiness/job/worker status endpoints. |
| Operator CLI | Commands for search smoke/explain, endpoint audit, feature flags, DB migration/seed/reset, and worker drains. |
Shape
How product work moves through the system.
- Domain and contract decisions define what product behaviour can mean.
- Web, API, CLI, and worker code consume shared contracts instead of leaking framework concerns.
- The API writes durable state and enqueues work that does not belong in the request cycle.
- Workers process, retry, update status, and enqueue follow-up indexing.
- Health, audit, CLI, and observability surfaces let the system be inspected and recovered.
Reflection
What the project clarified about platform work.
The platform is part of the product. A trust product cannot explain itself if its own internals are tangled, so the architecture has to make responsibility visible: where data enters, where work waits, where it retries, and where an operator can see what happened.