Feature 1: The Sentiment Badge

The sentiment badge looks like the easiest feature: one word per review. The hard decisions are about volume. The Kestrel X2 has 214 reviews, shown 20 per page, and each page view could trigger up to 20 model calls. Get the volume design wrong and the smallest feature becomes the most expensive one.

This lesson builds the badge end to end: the route, the hook and the component. It ends with the question every senior engineer should ask about a feature like this: should it run in the browser's request path at all?

One call per page, not one per review

The badge prompt from section 2 is about 300 tokens of rules and examples. A review is about 150 tokens. Compare two designs for one page of 20 reviews:

Batching cuts input tokens by 63 percent and requests by a factor of 20. It is also kinder to rate limits: 20 parallel calls from every page view hit a provider's requests-per-minute limit quickly.

Batching has costs too. If the batched reply is invalid, you lose all 20 labels instead of one. And the slowest item in the batch sets the time for all of them. For short labels those costs are small, so ShopLens batches. For long outputs per item, smaller batches of 5 are a reasonable middle ground.

The route

1// server/routes/sentiment.ts2import type { Request, Response } from "express";3import { SentimentReply, SentimentRequest } from "../../shared/schemas";4import { completeJson } from "../completeJson";5import { getReviewsByIds } from "../data";6import { SENTIMENT_SYSTEM, sentimentUserPrompt } from "../prompts";78export async function sentimentRoute(req: Request, res: Response): Promise<void> {9  const input = SentimentRequest.safeParse(req.body);10  if (!input.success) {11    res.status(400).json({ error: "Invalid request" });12    return;13  }14  const reviews = await getReviewsByIds(input.data.productId, input.data.reviewIds);15  if (reviews.length === 0) {16    res.json({ items: [] });17    return;18  }1920  const reply = await completeJson(21    { tier: "fast", system: SENTIMENT_SYSTEM, user: sentimentUserPrompt(reviews),22      maxTokens: 600, signal: AbortSignal.timeout(10_000) },23    SentimentReply,24  );25  if (!reply) {26    res.status(502).json({ error: "Sentiment unavailable" });27    return;28  }2930  // Keep one label per review that was actually asked about.31  const asked = new Set(reviews.map((r) => r.id));32  const items: SentimentReply["items"] = [];33  for (const item of reply.items) {34    if (asked.has(item.id)) {35      items.push(item);36      asked.delete(item.id);37    }38  }39  res.json({ items });40}

Read it from top to bottom. The request is validated before anything else, so a list of 500 ids is rejected with a 400. The reviews come from the database, filtered by product, so a caller cannot ask about another product's reviews through this product's page. The model call has a 10-second timeout from AbortSignal.timeout, because a badge that arrives after 10 seconds is worthless. Finally, the loop keeps only labels for ids that were requested, and only the first label for each. The schema cannot do that check, because it does not know which ids were asked for.

The hook

1// src/hooks/useSentiment.ts2import { useEffect, useState } from "react";3import { postJson } from "../api/client";4import { SentimentReply, type SentimentLabel } from "../../shared/schemas";56export function useSentiment(productId: string, reviewIds: string[]) {7  const [labels, setLabels] = useState<Record<string, SentimentLabel>>({});8  const key = reviewIds.join(","); // stable dependency: the array is new on every render910  useEffect(() => {11    const ids = key ? key.split(",") : [];12    if (ids.length === 0) return;13    const controller = new AbortController();1415    postJson("/api/sentiment", { productId, reviewIds: ids }, SentimentReply, controller.signal)16      .then((reply) => {17        setLabels((prev) => {18          const next = { ...prev };19          for (const item of reply.items) next[item.id] = item.label;20          return next;21        });22      })23      .catch((err: unknown) => {24        if (!controller.signal.aborted) console.warn("sentiment unavailable", err);25      });2627    return () => controller.abort(); // page changed or component unmounted28  }, [productId, key]);2930  return labels;31}

The key string is the most important line. reviewIds is a new array on every render, so using it as an effect dependency would fire a new request on every render, which is the cost bug from section 1. A joined string only changes when the ids change. The cleanup aborts the request when the shopper moves to the next page, so a slow reply for page 1 cannot arrive after page 2 is showing. Failures are logged and otherwise ignored: the badge is decoration, and a missing badge is a fine outcome.

The badge

1// src/components/SentimentBadge.tsx2import type { SentimentLabel } from "../../shared/schemas";34const TEXT: Record<SentimentLabel, string> = {5  positive: "Positive",6  mixed: "Mixed",7  negative: "Negative",8};910export function SentimentBadge({ label }: { label: SentimentLabel | undefined }) {11  if (!label) return <span className="badge badge--empty" aria-hidden="true" />;12  return (13    <span className={`badge badge--${label}`}>14      <span className="visually-hidden">Review sentiment: </span>15      {TEXT[label]}16    </span>17  );18}

In ReviewList, the page calls const labels = useSentiment(productId, page.map((r) => r.id)) and renders <SentimentBadge label={labels[r.id]} /> in each card. Two details make it robust. The empty badge has the same width as a real one, so when labels arrive 1.5 seconds later nothing shifts, and your layout-shift score stays clean. And TEXT is a Record keyed by the label type, so if someone adds a fourth label to the Zod enum, TypeScript refuses to compile until the badge knows how to show it.

Or compute it once, at write time

Here is the honest question. A review's text never changes after it is posted, so its sentiment never changes either. Why classify it on every page view?

Put numbers on it. With 50,000 product page views a day and one badge call per view, the cost is 50,000 × $0.004 = $200 a day. If instead a background job labels each new review once when it is posted, and the store receives 1,000 reviews a day, the cost is 1,000 × $0.0002 = $0.20 a day, and the badge appears instantly with the page.

So in production, ShopLens stores the label in a database column and the page reads it with the reviews. The route you just built stays useful for reviews that have not been labelled yet, and the same pattern of batch, validate, and ignore failures applies to any feature that depends on something the user just did, which cannot be computed in advance. The rule to remember: if the input is fixed, compute the output once.