[Guide] Build a Notifications Center (Global Route Contract) - implementation notes

Keeping tab/type/selectedId in route state was the right call for us.

It made back/forward feel like a real feature instead of an accident.

We derived groups in a single helper and treated it as mandatory after any mutation:

ts
function deriveNotifications(vault: any) {
  const items = vault.read('items');
  const unreadCount = items.filter((n: any) => !n.read && !n.archived).length;
  const mutedCount = items.filter((n: any) => n.muted).length;
  vault.write('derived', { ...vault.read('derived'), unreadCount, mutedCount, lastDerivedAt: Date.now() });
}

If derivation isn't centralized, the list and header drift immediately.

Counterpoint: global route contracts can become huge if you add keys for every micro-feature.

We kept the contract minimal (tab/type/selectedId/posture) and left everything else in the vault/documents.

We used a simple rule for duplicate reads: list read wins for list-derived evidence, detail read wins for detail content.

But we always store a source string as evidence when we apply one over the other.

The cache lane posture was the most useful debugging knob.

If someone reports stale notifications, you can see data-cache-lane and tell if it's expected or a bug.

We rendered data-tab, data-type, and data-selected in the shell and it made screenshots actionable.

Without it, half the bug reports were missing the context that actually mattered.

Mark read + archive mutations were easiest when they were intent objects and the last intent was stored.

If you don't store intent, you can't explain why an item moved groups.

A misunderstanding I had: I thought "no invalidation" would make the list stale.

In practice, optimistic writes + re-derive makes the UI feel immediate, and duplicate reads converge later.

Counterpoint: optimistic writes can create weird flicker when a server read reorders items.

We stabilized by storing derived groups and only allowing reordering at group boundaries.

Docs tie-in: global route contract + derived state is basically the routing/state docs combined.

Related: Routing and Navigation and State Management (Best Practices).

We added a derived dayGroups version string and bumped it when derivation logic changed.

Otherwise deployments caused weird group mismatches until everything re-derived.

We kept selection in route state, but also stored a selectedSnapshot derived string in the vault.

It made it easy to show a placeholder detail view while the detail read loaded.

We treated cadence posture as a product decision: warm for default, hot only when user is actively reading unread.

It reduced churn while still feeling responsive.

One thing I liked is that the guide treats notifications like "content" plus "motion".

Once motion is explicit (route keys), the rest of the UI becomes much more predictable.

We had a bug where muted count drifted when archiving.

Centralizing derivation fixed it; we stopped doing any count logic inside components.

If you're doing thread grouping, treat threadId as an identity boundary and store it as evidence in the detail panel.

It prevents confusion when two notifications look similar but belong to different threads.

We also made a debug-only "group trace" that shows why an item is in a group.

It saved us during triage because you can see the rule, not just the result.

Counterpoint: storing too many derived structures can make migrations painful.

We kept derived groups, counts, and a small snapshot string; everything else stayed live.

The guide's "URL as hint" approach prevented the query-string-from-hell problem for us.

We read tab/type once and then route truth owns the rest.

We wrote route-flow tests that assert evidence keys instead of timing.

If the route contract says data-tab=unread, tests can be stable even when data freshness is hot.

The "always ready" derived grouping strategy is the only one I've seen that keeps notification UIs from feeling random.

Even if the grouping isn't perfect, being consistent matters more.

If you're implementing this, start with evidence keys first. It forces you to define the contract before you chase UX polish.