[Guide] Build a Customer Support Inbox - implementation notes

Route groups finally made sense to me after this guide.

Filters are shared truth across panels; selection is global motion; drafts are local truth.

We modeled it almost exactly like the guide (group filters + global selection).

The key was rendering group filter evidence in the shell so you could tell what the queue was actually showing.

Counterpoint: group state can become another global store if you're not careful.

If every feature adds a group key, you end up with a giant shared filter object nobody owns.

Triage scores were worth it because they prevented the queue from feeling random.

Even if the score isn't perfect, consistency is a UX feature.

A small snippet for group state + evidence that matched the guide's posture:

tsx
export function SupportShell({ children }: { children: React.ReactNode }) {
  const route = useGlobalRoute('support', { selectedId: null, panel: 'split', density: 'comfortable' });
  const group = useGroupState('support', { status: 'open', assigned: 'any', channel: 'any', q: '', sort: 'triage' });
  return (
    <section
      data-status={group.read('status')}
      data-assigned={group.read('assigned')}
      data-channel={group.read('channel')}
      data-selected={String(route.read('selectedId'))}
    >
      {children}
    </section>
  );
}

Compose overlay dead ends were solved by self-correcting navigation in render.

If compose is open and there's no selected thread, close compose and bounce to the queue. It's strict but avoids broken screens.

We stored previewLinesById and it made list rendering cheap and consistent.

If each row computes a preview from the last message, you get drift when data updates mid-scroll.

A misunderstanding I had: I thought route groups were just fancy context.

But the key difference is that group truth is treated as a routing contract, not just a convenience.

We found it helpful to store derived groupedByStatus so queue sections were stable and predictable.

Otherwise a thread can "jump" between groups during a refresh and it looks like a bug.

Derivation maintenance was solved by centralizing: whenever queue data changes, run deriveQueue() once and write all derived keys.

We stopped doing per-row derivations in render and the UI got calmer.

One place route groups helped: shared filters between queue and thread made back/forward behavior sane.

You don't get the situation where the queue is filtered but the thread view isn't aware of it.

Counterpoint: storing triage scores can hide when the underlying data changed.

We had to also store a triageDerivedAt timestamp so people didn't assume the score was live.

Evidence wise we rendered data-panel, data-density, plus the group filter keys.

Support screenshots became actionable because they included the posture implicitly.

We also used route group middleware to stamp filters into a request context for logging.

It made server logs line up with what the UI was showing.

The guide's posture that duplicate fetching is acceptable is important here.

Inbox UIs feel broken when the queue is fresh but the thread is stale (or vice versa). Let panels choose freshness.

We used sort=triage|newest as a group key and it was great.

The queue can switch ordering without rewriting routes, and it still stays shareable because the group contract is stable.

Docs tie-in: this guide is basically "routing contracts" applied to support tooling.

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

We added a derived staleSelectionReason string when the shell clears a selection.

It helped explain why a thread "closed" (e.g. filter changed, thread no longer visible).

The best part about group contracts is that they prevent the shell from becoming a prop API.

You can share state across panels without turning every component into an argument list.

We stored a derived "queue health" number (missing previews, missing triage, empty threads).

It caught a bunch of drift bugs early because it was an always-visible red flag in debug mode.

If you're adopting this pattern, start by defining the group contract keys clearly.

Once the shared filter story is stable, the rest of the architecture falls into place.

This is the first guide where the routing model genuinely explains the UX, not just the file structure.