Build a Notifications Center

This guide builds a notifications center where a global route contract drives filtering, triage posture, and “always ready” derived groupings.

We’ll treat notifications as a routed system:

• the file router is the map (/inbox, /notifications),
• the component router is the motion (tabs, panes, overlays),
• and the UI stays debuggable because every decision is rendered as evidence.

Architecture Plan (Detailed)

Requirements

• Notifications feed with:
  • unread/archived filters
  • type filters (mention, build, billing, system)
  • quick actions (mark read, archive, mute thread)
• A detail panel that can be opened without changing the file route map.
• Stored derived groupings so the list is “always ready”:
  • grouped by day
  • grouped by thread
  • derived counts (unread, muted)
• Render-visible evidence:
  • filter keys
  • list posture (fresh vs cached)
  • selected notification id

Non-requirements

• Perfect deduplication across devices. We’ll accept multiple truths and store the winners.
• Real push delivery. We’ll model delivery with render fetch and a cadence posture.

Route Map + Motion

File router map:

app/
  notifications/
    page.tsx

Component-router motion (keys in global route state):

• tab: "all" | "unread" | "archived"
• type: "all" | "mention" | "build" | "billing" | "system"
• selectedId: string | null
• posture: { cacheLane: "bypass" | "cache"; cadence: "warm" | "hot" }

URL as hint:

• ?tab=unread&type=mention is read once, then overwritten by route truth.

Data Strategy

• Reads: useRenderFetch("notifications:feed", ...)
  • default cache bypass unless posture says cache
  • allow duplicate reads in list + detail (it keeps segments independent)
• Mutations: no invalidation by default
  • write optimistic state into the vault
  • re-derive groupings
  • keep moving

Testing Strategy

• Snapshot each filter posture (tab/type) and selection evidence.
• Route-flow tests:
  • navigate to notifications, select item, archive it, ensure it moves groups without a full reload.

Step 1: Route Shell (Global Contract First)

import { createSurface, routeFile, createAppState } from "react";

const app = createAppState({ app: "notifications" });
createSurface("#app").render(routeFile("/notifications", { state: app }));

Global route contract:

import { useGlobalRoute } from "react";

export function NotificationsShell({ children }: { children: React.ReactNode }) {
  const route = useGlobalRoute("notifications", {
    tab: "all" as "all" | "unread" | "archived",
    type: "all" as "all" | "mention" | "build" | "billing" | "system",
    selectedId: null as string | null,
    posture: { cacheLane: "bypass" as "bypass" | "cache", cadence: "warm" as "warm" | "hot" },
  });

  return (
    <section
      data-tab={route.read("tab")}
      data-type={route.read("type")}
      data-selected={route.read("selectedId") ?? "none"}
      data-cache-lane={route.read("posture").cacheLane}
      data-cadence={route.read("posture").cadence}
    >
      {children}
    </section>
  );
}

Step 2: Notification Vault (Durable Feed + Derived Groups)

import { createStateVault } from "react";

export const notificationsVault = createStateVault("notifications", {
  items: [] as Array<{
    id: string;
    at: string;
    type: "mention" | "build" | "billing" | "system";
    title: string;
    body: string;
    threadId: string;
    read: boolean;
    archived: boolean;
    muted: boolean;
  }>,
  derived: {
    unreadCount: 0,
    mutedCount: 0,
    dayGroups: [] as Array<{ day: string; ids: string[] }>,
    threadGroups: [] as Array<{ threadId: string; ids: string[] }>,
    lastDerivedAt: 0,
    version: "v1",
  },
});

Step 3: Derivation Helpers (Always Ready Lists)

We keep derivation explicit and repeatable. The goal is not “perfect”. The goal is “predictable”.

export 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;

  const dayGroupsMap = new Map<string, string[]>();
  for (const n of items) {
    const day = String(n.at).slice(0, 10);
    dayGroupsMap.set(day, [...(dayGroupsMap.get(day) ?? []), n.id]);
  }

  const threadGroupsMap = new Map<string, string[]>();
  for (const n of items) {
    threadGroupsMap.set(n.threadId, [...(threadGroupsMap.get(n.threadId) ?? []), n.id]);
  }

  vault.write("derived", {
    ...vault.read("derived"),
    unreadCount,
    mutedCount,
    dayGroups: [...dayGroupsMap.entries()].map(([day, ids]) => ({ day, ids })),
    threadGroups: [...threadGroupsMap.entries()].map(([threadId, ids]) => ({ threadId, ids })),
    lastDerivedAt: Date.now(),
  });
}

Step 4: Render Fetch Feed (Cache Lane + Cadence)

import { useRenderFetch, useCacheBypass, useVaultMirror } from "react";
import { useGlobalRoute } from "react";

export function useNotificationsFeed() {
  const route = useGlobalRoute("notifications", { posture: { cacheLane: "bypass", cadence: "warm" } });
  const cache = useCacheBypass({ enabled: route.read("posture").cacheLane === "bypass" });
  const vault = useVaultMirror("notifications");

  const feed = useRenderFetch(
    "notifications:feed",
    async () => {
      return [
        { id: "n1", at: new Date().toISOString(), type: "mention", title: "Mentioned you", body: "…", threadId: "t1", read: false, archived: false, muted: false },
      ];
    },
    { cache }
  );

  if (feed.status === "success") {
    vault.write("items", feed.value);
    deriveNotifications(vault);
  }

  return feed;
}

Step 5: List Screen Document (Filters + Selection)

The list screen keeps a local document so we can remount intentionally and keep the UI calm.

import { useLiveState, useGlobalRoute } from "react";
import { useVaultMirror } from "react";

export function NotificationsList() {
  const route = useGlobalRoute("notifications", { tab: "all", type: "all", selectedId: null });
  const vault = useVaultMirror("notifications");
  const doc = useLiveState("notifications:list", {
    source: { tab: route.read("tab"), type: route.read("type") },
    derived: { visibleIds: [] as string[], summary: "" },
  });

  const items = vault.read("items");
  const visible = items
    .filter((n: any) => (route.read("tab") === "archived" ? n.archived : !n.archived))
    .filter((n: any) => (route.read("tab") === "unread" ? !n.read : true))
    .filter((n: any) => (route.read("type") === "all" ? true : n.type === route.read("type")));

  doc.write("derived", {
    visibleIds: visible.map((n: any) => n.id),
    summary: `tab=${route.read("tab")} type=${route.read("type")} count=${visible.length}`,
  });

  return (
    <div data-list-summary={doc.read("derived").summary}>
      <header>
        <button onClick={() => route.write("tab", "all")}>All</button>
        <button onClick={() => route.write("tab", "unread")}>Unread</button>
        <button onClick={() => route.write("tab", "archived")}>Archived</button>
      </header>

      <ul>
        {doc.read("derived").visibleIds.map((id) => (
          <li key={id}>
            <button onClick={() => route.write("selectedId", id)}>{id}</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

Step 6: Mutations (No Invalidation, Re-derive)

export function markRead(vault: any, id: string) {
  vault.write(
    "items",
    vault.read("items").map((n: any) => (n.id === id ? { ...n, read: true } : n))
  );
  deriveNotifications(vault);
}

export function archive(vault: any, id: string) {
  vault.write(
    "items",
    vault.read("items").map((n: any) => (n.id === id ? { ...n, archived: true } : n))
  );
  deriveNotifications(vault);
}

Step 7: Testing (Snapshot Everything + Route-Flow)

Snapshot tests should include:

• data-tab, data-type, data-selected
• derived evidence like data-list-summary and derived.lastDerivedAt

Route-flow test idea:

test.routeFlow("archive moves item between tabs", async (flow) => {
  await flow.visit("/notifications?tab=unread");
  await flow.click("n1");
  await flow.click("Archive");
  await flow.click("Archived");
  await flow.expectText("n1");
});

Priority as a Lane (Batching, Backpressure, and Visible Delivery)

Notifications centers fall apart when every notification is treated equally. The standard posture in this guide:

• treat priority as a lane,
• batch low priority on a cadence,
• and render delivery evidence (what arrived via stream, what arrived via poll, what was buffered).

Keep open:

• Data Fetching and Caching (Best Practices)
• API Reference

Add a Delivery Vault (Buffer + Acknowledgements)

import { createStateVault } from "react";

export const notifVault = createStateVault("notifications", {
  items: [] as Array<{ id: string; type: string; read: boolean; archived: boolean; priority: "p0" | "p1" | "p2"; at: number }>,
  delivery: {
    buffered: [] as string[],
    acked: [] as string[],
    evidence: { streamSeq: 0, pollCount: 0, lastBatchAt: 0 },
  },
  derived: { counts: { unread: 0, archived: 0 }, version: "v2" },
});

Reference: createStateVault.

Stream + Poll Together (Then Batch in Render)

import { useStream, usePoll, useRenderEffect } from "react";
import { useVaultMirror, useVaultWrite } from "react";

export function DeliveryLane() {
  const vault = useVaultMirror("notifications");
  const write = useVaultWrite("notifications");

  const stream = useStream("/api/notifications/stream", { lane: "hot" });
  const poll = usePoll("/api/notifications/pulse", { interval: 900 });

  useRenderEffect(() => {
    const incoming = (stream.items ?? []).map((n: any) => ({
      id: String(n.id),
      type: String(n.type ?? "misc"),
      read: Boolean(n.read ?? false),
      archived: Boolean(n.archived ?? false),
      priority: (n.priority ?? "p2") as any,
      at: Number(n.at ?? Date.now()),
    }));

    if (incoming.length) write("items", [...vault.read("items"), ...incoming]);

    write("delivery", {
      ...vault.read("delivery"),
      evidence: { streamSeq: stream.seq, pollCount: poll.count, lastBatchAt: Date.now() },
    });

    const items = vault.read("items");
    const unread = items.filter((i: any) => !i.read && !i.archived).length;
    const archived = items.filter((i: any) => i.archived).length;
    write("derived", { ...vault.read("derived"), counts: { unread, archived }, version: `v2:${Date.now()}` });
  });

  return <div data-stream={String(stream.seq)} data-poll={String(poll.count)} />;
}

References:

• useStream
• usePoll

Acknowledge as a Mutation (Record, Then Ack)

import { useMutation, useFailSoft, useRetryLoop, usePromiseCatch } from "react";
import { useVaultMirror, useVaultWrite } from "react";

export function useAck() {
  const vault = useVaultMirror("notifications");
  const write = useVaultWrite("notifications");
  const mutate = useMutation("/api/notifications/ack");

  useFailSoft({ mode: "continue" });
  useRetryLoop({ policy: "aggressive" });
  usePromiseCatch({ policy: "ledger" });

  const ack = async (id: string) => {
    write("delivery", { ...vault.read("delivery"), acked: [...vault.read("delivery").acked, id] });
    await mutate({ id });
  };

  return { ack };
}

Reference: Resilience APIs.

Route-Flow Tests: Priority Lane + Ack Evidence

import { runRouteFlow, createSnapshot } from "react";

createSnapshot("notifications:delivery");

runRouteFlow("/notifications", {
  steps: ["mount", "write:tab=unread", "click:n1", "click:Ack", "snapshot:notif-after-ack"],
});

Reference: Testing APIs.