Search documentation

Find a vivid-layer page or product.

Chat Minimap

A compact conversation navigator that previews turns, tracks reading position, and jumps between message anchors.

pnpm dlx shadcn@latest add @vivid-layer/chat-minimap

Review the incident handoff and tell me what to read first.

Start with the summary and the impact section. The regression affected the upload queue, but the recovery path completed for every queued job.

What was the customer impact?

Impact was limited to delayed processing.

No records were dropped, and the reconciliation worker confirmed each retry batch. Support saw confusion from two customers, but there were no checkout or billing errors.

What actions are open?

Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.

The alert should fire on sustained queue growth, not a single short spike.

Give me the follow-up checklist.

After that, compare the queue recovery graph with the deploy timeline so the handoff shows exactly when processing returned to baseline. That makes it easier for support and engineering to answer the same customer questions without re-reading the whole incident thread.

I would also add a short owner note beside each follow-up item. The checklist is small, but ownership keeps the retry-window decision, alert tuning, and support macro from drifting into separate follow-up conversations.

Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.

The alert should fire on sustained queue growth, not a single short spike.

When did processing return to normal?

The queue began draining at 14:22 UTC and returned to baseline at 14:47 UTC.

The deploy completed earlier, but the recovery graph is the better marker because it shows when customer-visible delays actually ended.

Who owns the remaining follow-ups?

Mina owns the queue-depth alert, Rafael owns the retry-window decision, and Support Operations owns the customer macro.

Each item should stay in the same incident project until it has an owner, due date, and verification note.

What should support tell customers?

Tell customers that uploads were delayed but not lost. Every queued job completed after retries, and no checkout or billing data was affected.

If a customer still sees a pending upload, ask for the job ID so engineering can compare it with the reconciliation log.

What caused the queue to back up?

A worker concurrency change increased the number of uploads entering the retry path at the same time. The queue accepted the work, but processors could not drain it at the expected rate.

The issue was amplified by a retry window that stayed open longer than intended.

How did we first detect the regression?

The first reliable signal was a rise in queue age, followed by two support reports about uploads remaining in a processing state. Error rate stayed low, so the normal failure alert did not fire.

Queue age should become a primary incident signal for this workflow.

Why did the existing alert arrive late?

The alert watched failed jobs rather than delayed jobs. Retries kept completing successfully, which hid the growing wait time until the queue crossed its broad capacity threshold.

A latency-based alert would have detected the incident earlier.

Were all regions affected equally?

The largest delay appeared in the primary region because it handled most upload traffic. Secondary regions saw shorter queues and recovered before the primary region returned to baseline.

No regional failover was required.

How large did the backlog become?

The queue peaked at 18,420 pending jobs, compared with a normal peak below 2,000. Median processing delay reached eleven minutes and the longest delay reached twenty-seven minutes.

The backlog began shrinking immediately after concurrency was reduced.

Did retries make the incident worse?

Retries protected the jobs from being dropped, but the extended retry window increased pressure on the workers. The system repeatedly reconsidered work that would have completed after capacity recovered.

The follow-up is to cap retry concurrency without weakening delivery guarantees.

How did we verify data integrity?

Engineering compared accepted upload IDs with completed job IDs and then checked the reconciliation ledger for gaps. Every accepted record had a matching completion or retry event.

A second pass after recovery confirmed zero missing or duplicated records.

Why did we not roll back immediately?

The deployment also contained a schema change that made an immediate rollback riskier than reducing worker concurrency. The mitigation could be applied independently and showed a measurable queue improvement within minutes.

Rollback remained available if the queue stopped draining.

Which mitigation had the biggest effect?

Reducing worker concurrency stabilized database pressure and allowed successful jobs to finish without competing with aggressive retries. Shortening the retry window then accelerated the remaining recovery.

Together, those changes returned throughput above incoming traffic volume.

What changed in the recovery deploy?

The recovery deploy restored the previous concurrency limit and added a guard that pauses retry expansion when queue age rises. It also emitted queue-age metrics at one-minute intervals.

No customer-facing API or payload changed.

How was the recovery deploy validated?

The team replayed a production-shaped upload batch in staging, then deployed to five percent of workers. Queue age, completion rate, retry volume, and database saturation stayed within the expected range.

The rollout expanded only after two clean observation windows.

What risk remains after the fix?

A sudden traffic spike can still create a short queue because worker capacity is intentionally capped. The difference is that retry pressure can no longer grow without bound.

The remaining risk is delay, not loss, and it is now visible through queue-age monitoring.

What should we monitor for the next day?

Watch queue age, pending job count, retry concurrency, completion throughput, and database saturation. Compare each metric with the same traffic window from the previous week.

Escalate if queue age exceeds five minutes for more than ten consecutive minutes.

Which alert thresholds should we use?

Create a warning when queue age exceeds three minutes for five minutes, and a critical alert at five minutes for ten minutes. Add a separate warning when retry concurrency remains above eighty percent of its cap.

These thresholds favor sustained degradation over brief traffic spikes.

What belongs on the incident dashboard?

Place queue age, queue depth, incoming jobs, completed jobs, retries, and worker concurrency on the first row. Add database saturation and regional breakdowns below them.

Annotate deploys and mitigation changes so metric movement can be tied to specific actions.

Which logs should we preserve?

Preserve worker scaling decisions, retry-window changes, queue snapshots, reconciliation output, and deploy annotations for the full incident window. Include fifteen minutes before the first signal and thirty minutes after recovery.

That range is sufficient for the postmortem without retaining unrelated customer content.

Which customers experienced the longest delays?

Customers submitting large multi-file batches during the peak window experienced the longest waits. Single-file uploads generally completed during the first retry cycle.

Account tier did not affect processing order or recovery time.

Did the incident breach an SLA?

The public availability SLA was not breached because uploads remained accepted and eventually completed. Two internal processing-time objectives were missed during the peak window.

The postmortem should report both misses even though they do not trigger service credits.

When should we send the customer update?

Send the resolved update after the reconciliation report and one full monitoring window are complete. The message should include the impact window, confirmation that uploads were not lost, and the current system status.

Avoid publishing internal implementation details that do not help customers recover.

What should trigger another escalation?

Escalate if queue age rises for three consecutive intervals, completed throughput falls below incoming volume, or reconciliation reports any unmatched upload ID. A second customer report after recovery should also reopen the incident.

Each trigger has a named owner in the monitoring handoff.

Are any external services part of the follow-up?

No external provider caused the incident, but the storage latency panel should remain in the dashboard as a comparison signal. The database team will review connection saturation during retry bursts.

All required fixes remain within systems owned by the upload platform team.

What are the follow-up deadlines?

The queue-age alert and dashboard update are due tomorrow. Retry concurrency controls are due before the next scheduled deploy, and the full load test is due by the end of the week.

The postmortem draft should be ready within three business days.

What should the postmortem focus on?

Focus on why successful retries masked customer-visible latency, why queue age was not a primary alert, and how the concurrency change passed pre-deploy checks. Separate detection, mitigation, and prevention actions.

The review should improve system controls rather than assign individual blame.

Summarize the final operational state.

The upload queue is at baseline, all accepted jobs have completed, and reconciliation shows no data loss or duplication. Worker concurrency and retry limits are stable under current traffic.

Monitoring remains elevated until the next deploy and all follow-up work is tracked in the incident project.

What should I verify before closing the incident?

Confirm that queue depth remains at baseline, the retry window has been disabled after the deploy, and the reconciliation report still shows zero dropped records.

Then link the alert, owner notes, and support macro from the incident summary so the final handoff has one source of truth.

Customize

Magnification
3.0
Lens range
3
Item size
12
Gap
0
Pill width
2
Transition duration
200

Chat Minimap gives long AI conversations the navigation layer chat apps usually lack: a compact rail that previews each turn, magnifies under the pointer, tracks your reading position, and jumps to any message on click. It is a React component built with shadcn/ui and Tailwind CSS, wired to scroll anchors through the companion Message Scroller.

API reference

PropTypeDefaultDescription
itemsreadonly ChatMinimapItem[]Supplies the marker entries in conversation order.
side"left" | "right""left"Places the minimap beside the conversation and flips the hover previews. Inherited from ChatMinimapContainer when unset.
magnificationnumber3Sets the maximum marker magnification as a multiple of itemSize.
lensRangenumber3Sets how many neighboring markers the wave affects.
itemSizenumber12Sets the base marker length and interactive row height in pixels.
gapnumber0Sets the space between marker rows in pixels.
pillWidthnumber2Sets the marker thickness in pixels.
transitionDurationnumber200Sets the marker transition duration in milliseconds.
easingReact.CSSProperties["transitionTimingFunction"]"ease-out"Sets the CSS transition timing function.

Each ChatMinimapItem contains id, title, and description. ChatMinimap also accepts native nav props.

Layout

Wrap ChatMinimap and Message Scroller in ChatMinimapContainer to place the minimap. The container accepts side ("left" | "right", default "left") plus native div props, and provides side to the minimap inside it. The minimap floats over the transcript edge in a rail the content padding reserves, so the viewport scrollbar keeps its usual place at the right edge — with the minimap on the right, the order is messages, minimap, scrollbar.

Behavior

  • Each marker previews a turn title and description in an official Hover Card.
  • Hovering or focusing a marker expands nearby bars into a wave.
  • The active marker follows currentAnchorId from Message Scroller.
  • Marker jumps use smooth scrolling by default and switch to "instant" when the system requests reduced motion.
  • Chat Minimap does not own messages, layout, AI state, or scrolling behavior.

Credits

Chat Minimap integrates with shadcn's official Message Scroller API. Its marker magnification is adapted from Mantine Lens Select, licensed under MIT.