Designing for what's coming

Three choices that stay right whether or not more of the analytics surface ships — keep your own store authoritative, model on events rather than on a Cockpit screen, and declare an analytics.json now.

You cannot design against a roadmap you have not been given. You can design so that whatever ships is an addition rather than a rewrite. Three choices do most of that work.

1. Keep your own store authoritative

Whatever arrives later, the store you own stays the thing your product answers from.

That is not a hedge — it is the right architecture anyway. A number in your product's UI has to be available when the platform is slow, has to be reproducible when a customer disputes it, and has to survive you changing platforms. None of that is true of a figure you fetch from somebody else's reporting API at render time.

So: build the store, keep the raw records, reconcile against the API on a schedule. If a metrics API ships later, it becomes another input to that pipeline — or a way to cross-check it — not the pipeline itself.

What this rules out is the shortcut of designing your product around an API you expect to exist. A screen that only works once someone ships a metrics endpoint is a screen you cannot ship.

2. Model on events, not on a Cockpit screen

Model your data on the platform's contracts, not on its interfaces.

  • Event topics and payloads are contracts. They are named, documented per tenant, and they evolve additively — a topic's data only ever gains fields, and a breaking change ships as a new topic you opt into. See Event types.
  • API entity schemas are contracts, versioned under /v1. See Versioning & stability.
  • A Cockpit screen is not a contract. Analytics Studio is early and moving; its layout, its chart types and its navigation can change in a release.

Concretely, that means: derive your model from the entities and the event payloads, not from a chart somebody screenshotted. If a customer says "I want this Cockpit chart in my app", find out which entities and events it is made of, and build from those. The chart is a specification of the question, not of the data model.

And do not reproduce the studio UI in your own material — its demo fixtures carry a real customer name.

3. Declare an analytics.json now

Of everything in this section, analytics.json is the one part that is shipped, versioned and validated against a published schema. If you ship an App, declare it now:

  • It costs one file and no runtime code.
  • It gives the tenant's operators something today, without you building a reporting UI.
  • It is validated at deploy, so it fails loudly rather than silently.
  • Declaring roles now means your dataset is usable by whatever the studio grows into — a richer chart builder, a cohort feature that gets better, a metric surface that reads roles. The declaration is the durable part.

See Make your app's data analyzable, and get the roles right — that is the part a future surface will lean on hardest.

Two habits that make a later migration cheap

Store platform ids on everything. Every row in your store should carry the platform's id for the thing it describes, and the tenant it belongs to. Any future feed — a metrics API, an export, a warehouse target — joins on those. A store keyed on your own sequence numbers does not.

Keep the raw payloads. A modelling change becomes a re-transform instead of a re-backfill, and a new capability that exposes a field you previously ignored becomes a re-read of your own archive.

What not to do

  • Do not build a private dependency on an unpublished surface. If something is not in the public API Explorer, it is not something to ship against, whatever you can see in a console.
  • Do not promise a customer a capability from the missing list. Check the changelog before you commit to a date.
  • Do not treat the event delivery log as your archive. It has no retention promise. Yours does.

Where to go next

Was this page helpful?