Typographe

Queues are often designed from the worker outward: max concurrency, retry count, dead-letter policy, and throughput. Those details matter, but they are not enough. A queue is also a promise to users that work has not disappeared.

When that promise becomes unclear, people open support tickets, refresh dashboards, and rerun actions that were already in flight.

## Name the user-visible state

Every background workflow should have a small state model that product, support, and engineering can share. Received, processing, waiting on provider, retrying, failed, complete. The exact words matter less than the fact that everyone uses the same ones.

If a job can sit in a queue for ten minutes, the product should have language for that delay.

> Checklist: Every queue should have an owner, expected delay range, retry policy, and user-visible failure state.

## Treat retries as product behavior

Retries are not invisible. They can send duplicate emails, charge payment methods twice, or make an integration look unreliable. Make retries idempotent, cap them intentionally, and expose enough detail that operators know whether the system is healing or stuck.

The right retry policy depends on the user promise, not only the exception type.

## Design the failure shelf

Dead-letter queues are shelves for decisions. Who checks them? How often? What can be replayed safely? Which failures need a customer-visible status? Without answers, the shelf becomes a basement.

Good queue design gives humans a way to understand delayed work before they need to debug it.

Preview environments are easy to sell: every pull request gets a URL, reviewers see the real thing, and fewer bugs hide between staging and production. The trouble starts when every preview becomes a full copy of production.

The trick is deciding which parts deserve isolation and which parts only need believable behavior.

## Isolate writes, share reads

Most preview work needs safe writes, not an entire private universe. Give each branch its own write namespace for drafts, uploads, sessions, and mutations. Let read-heavy reference data come from a shared snapshot.

This keeps previews fast while avoiding the classic problem where one reviewer accidentally edits data another reviewer is using.

## Expire aggressively

Every preview should have an owner, a creation time, and a removal policy. Tie cleanup to pull request state and add a maximum age. If a preview matters after the branch is closed, promote the artifact or snapshot intentionally.

Cloud bills grow in the quiet corners. Expiration is a product feature for the engineering team.

## Make expensive services fake by default

Email, payments, search indexing, ML inference, and video processing should default to local doubles or sandbox providers. The preview should reveal integration shape, not spend real money proving a button can be clicked.

Document the few cases where a real service is required, and make that opt-in visible in the pull request.

## Show cost next to status

Build status says whether a preview exists. Cost status says whether it is behaving. A simple daily estimate beside each active environment changes behavior faster than a monthly surprise report.

The goal is not to make previews cheap at all costs. It is to spend money on feedback, not forgotten infrastructure.

Teams often talk about integration tests as if there are only two choices: mock everything or recreate production. There is a third path. Test the smallest real contract that has caused bugs before.

Small integration tests are not comprehensive. That is why they work.

## Pick the boundary that breaks

Start with contracts between your application and the things that change independently: database migrations, payment webhooks, search indexing, auth callbacks, generated SDKs, and queue payloads.

The question is not "can we test the whole workflow?" The question is "which boundary do we keep misunderstanding?"

ts
test("webhook payload matches the queue contract", async () => {
  const payload = await fixture("payment-succeeded.json");
  expect(toQueueMessage(payload)).toMatchObject({
    type: "payment.succeeded",
    accountId: expect.any(String),
  });
});

## Keep setup boring

Use fixtures that explain the contract, not fixtures that clone production. Avoid time-dependent data unless time is the contract. Keep external services in sandbox mode or local containers with a narrow scope.

If the setup takes longer to read than the assertion, the test is doing too much.

## Run them where they matter

Small integration tests should run in pull requests when they protect shared contracts. Slower contract suites can run before release. The important part is making failures actionable: tell engineers which boundary changed and why it matters.

A good integration test is a useful conversation with the system.

API versioning fails when it surprises people. A perfectly designed URL scheme cannot save a platform that changes behavior without warning, deprecates too aggressively, or leaves old versions alive with no support story.

The goal is not to avoid breaking changes forever. It is to make change survivable.

## Context

Public API consumers need predictable change windows, stable contracts, and clear migration paths. The existing informal approach works while consumers are close to the team, but becomes brittle as integrations grow.

## Decision

Use additive changes by default, reserve breaking changes for explicit version boundaries, and publish deprecation signals in documentation, response headers, and account communication.

## Alternatives

- Keep a single evergreen API and avoid explicit versions. - Version every endpoint independently. - Use date-based global versions for all behavior.

## Consequences

Consumers get a clearer contract, but the platform team must maintain version usage metrics and migration examples.

## Define what versioning protects

Does a version protect response shape, validation rules, authentication behavior, pagination, error codes, or all of the above? Write it down. Consumers need to know whether a field can appear, disappear, or change meaning.

Ambiguity turns every deploy into a compatibility risk.

## Make deprecation observable

Deprecation notices should show up in docs, dashboards, headers, and account communication. If a customer only learns about a breaking change when their integration fails, the process did not work.

Track usage by version and endpoint. That data tells you who needs help and whether a migration is realistic.

## Prefer additive change

Add fields, add endpoints, and add opt-in behavior before replacing existing contracts. When removal is necessary, provide migration examples that match real client code.

Developers forgive change more easily when the path forward is concrete.

Design tokens often begin as a tidy promise: put color, spacing, radius, and type values in one place. Then the product grows, teams add exceptions, and the token file becomes a museum of unresolved decisions.

The problem is rarely tokens themselves. It is naming values before naming intent.

## Separate primitives from roles

Primitive tokens store raw values: color scales, spacing steps, font sizes. Role tokens explain how the product uses them: surface, border, text-muted, action-primary, danger-background.

Components should mostly consume role tokens. That gives the system room to change a palette without rewriting every component.

## Keep aliases boring

Aliases should make usage clearer, not more mysterious. A name like interactive-critical-hover may be precise, but it can also become a place where no one wants to make a decision. Use enough structure to prevent chaos, then stop.

If a token name needs a long explanation in every pull request, the system is asking too much of its users.

## Retire tokens deliberately

Unused tokens are not harmless. They create false options and make new contributors wonder which value is preferred. Add deprecation notes, keep a removal window, and track token usage in components and docs.

A mature token system is not the one with the most names. It is the one where teams can make consistent decisions quickly.

Cloud cost reviews often arrive as bad news. Someone exports a dashboard, circles a spike, and asks engineers to spend less. That format creates defensiveness because it treats cost as a finance problem with engineering blame attached.

Better reviews connect spend to architecture choices.

## Start with unit economics

Look at cost per customer, request, build, workspace, document, or inference. Absolute spend matters, but unit cost shows whether the system is becoming more efficient as it grows.

A rising bill with falling unit cost may be healthy. A flat bill with rising unit cost may hide a scaling problem.

## Review the top movers

Do not review every line item. Pick the services that changed most since the last review and ask what product or system behavior moved them. New workload? Forgotten preview environments? Larger artifacts? More retries?

The meeting should produce engineering hypotheses, not vague anxiety.

## Make savings an architecture backlog

Cost work competes with product work, so size it like product work. Some savings are one-line config changes. Others require caching, lifecycle policies, query changes, or product constraints.

Engineers attend cost reviews when the conversation helps them make better systems, not when it asks them to feel bad about graphs.