Skip to content

Use cases

Different codebases. Different questions. One clearer picture.

Four situations where the context around the code matters more than the code in any single file.

Onboarding

Joining an unfamiliar project

You've joined the storefront team. Before your first ticket you want to understand authentication, API structure and data flow.

First week goalKnow where auth, the API layer and the data model live.

What you see
A natural-language question, a contextual answer, the files it relies on and a suggested path to read next.
Outcome
A structured starting point for onboarding: where auth, the API layer and the data model live, and how they connect.
Open this scenario in the demo

Question

Where is authentication handled?

Answer

Authentication lives in lib/auth/session.ts. getSession reads the session cookie and verifies it; requireUser wraps it and throws a 401 response. Only the cart and checkout handlers call requireUser, so product pages are public.

Referenced files

  • lib/auth/session.ts:6–10Cookie read + token verification
  • lib/auth/session.ts:12–18Guard used by private handlers
  • app/api/cart/route.ts:6Cart is authenticated
  • app/api/checkout/route.ts:6Checkout is authenticated
  • lib/auth/session.ts:2Inference: Token verification lives in ./tokens, which this sample does not include

Suggested exploration path

  1. session.ts
  2. cart/route.ts
  3. checkout/route.ts

Debugging

Investigating a bug

Checkout started failing after a change to cart logic. You have the symptom, not the cause.

Reported symptomPOST /api/checkout returns 500 for signed-in users with a discount. Users without a discount can check out.

What you see
The reported symptom, the request handler, the functions it calls, a potential failure point and the evidence for it.
Outcome
A hypothesis to verify, with the lines that support it. Not a confirmed root cause.
Open this scenario in the demo

Question

Why might POST /api/checkout return 500 after the cart change?

Hypothesis

A likely candidate: calculateTotals now multiplies by (1 − discountRate) without rounding, so subtotalCents can be fractional. createCheckout passes that value straight to payments.createIntent, and the checkout handler has no error handling, so a rejected amount would surface as a 500. This is a hypothesis, not a confirmed root cause.

Referenced files

  • server/cart.ts:36No Math.round after applying the discount
  • server/checkout.ts:13–14Amount forwarded as-is
  • app/api/checkout/route.ts:5–9Errors are not caught or mapped
  • CONTRIBUTING.md:9Integer-cents convention
  • tests/cart.test.ts:4–16No test covers a non-zero discount
  • server/checkout.ts:3Inference: That the payment provider rejects fractional amounts is not visible here. Confirm in logs.

Suggested exploration path

  1. checkout/route.ts
  2. checkout.ts
  3. cart.ts

Change review

Understanding the impact of a change

A pull request changes apiFetch so failed responses resolve to null instead of throwing.

Change under reviewapiFetch in lib/api/client.ts no longer throws on non-2xx responses.

What you see
The changed function, the files that depend on it, related tests and the workflows that might be affected.
Outcome
A potential impact list to review against, scoped to the references RepoMind can see.
Open this scenario in the demo

Question

What could the apiFetch change affect?

Potential impact

Potential impact: callers that rely on ApiError stop seeing failures. getProduct would return null for any error, so a 500 could render as a 404 page. AddToCartButton's catch block would no longer run, so a failed add could look successful. The apiFetch error test is expected to fail. This list is based on direct references and may not be exhaustive.

Referenced files

  • lib/api/products.ts:9–13Depends on ApiError being thrown
  • app/products/[id]/page.tsx:11–13Treats null as not found
  • components/AddToCartButton.tsx:11–16Error state relies on a throw
  • tests/api-client.test.ts:12–15Will fail with the new behaviour
  • lib/api/client.ts:15–17Inference: Callers outside this sample (if any) are not covered

Suggested exploration path

  1. client.ts
  2. api/products.ts
  3. page.tsx
  4. AddToCartButton.tsx
  5. api-client.test.ts

Open source

Contributing to open source

You picked up an issue in storefront-app and want a focused, mergeable first pull request.

Issue #42Allow each product to set its own maximum quantity per order.

What you see
Where the relevant feature lives, the project's conventions, the nearest tests and the shape of a focused change.
Outcome
A smaller, better-aimed first pull request.
Open this scenario in the demo

Question

Where would I add a per-product quantity limit?

Answer

The limit is enforced in addItem in server/cart.ts, where 10 is currently hard-coded. A focused change would add a maxPerOrder column to products in db/schema.ts, read it in addItem, and keep the route handler unchanged.

Referenced files

  • server/cart.ts:8–10Current hard-coded rule
  • db/schema.ts:3–10products table definition
  • CONTRIBUTING.md:10Rules belong in server/

Suggested exploration path

  1. cart/route.ts
  2. cart.ts
  3. schema.ts

Try each scenario.

Each scenario has its own questions, file relationships and explanations in the sample repository.

Joining an unfamiliar project

You've joined the storefront team. Before your first ticket you want to understand authentication, API structure and data flow.

storefront-app / main

First week goalKnow where auth, the API layer and the data model live.

lib/auth/session.ts

import { cookies } from "next/headers";
import { verifySessionToken } from "./tokens";
 
export type SessionUser = { id: string; email: string; discountRate: number };
 
export async function getSession(): Promise<{ user: SessionUser } | null> {
  const token = (await cookies()).get("session")?.value;
  if (!token) return null;
  return verifySessionToken(token);
}
 
export async function requireUser(): Promise<SessionUser> {
  const session = await getSession();
  if (!session) {
    throw new Response("Unauthorized", { status: 401 });
  }
  return session.user;
}
Explanation

Where is authentication handled?

Authentication lives in lib/auth/session.ts. getSession reads the session cookie and verifies it; requireUser wraps it and throws a 401 response. Only the cart and checkout handlers call requireUser, so product pages are public.

  1. getSession reads the session cookie and verifies the token.
  2. requireUser throws Response(401) when no session exists.
  3. Calls requireUser() before touching the cart.
  4. Calls requireUser() before creating a payment intent.

Direct evidence

Inference

Follow up

Dependency graph: files in the current answer are lit

page.tsxProductDetails.tsxAddToCartButton.tsxapi/products.tsclient.tssession.ts[id]/route.tscart/route.tscheckout/route.tsserver/products.tscart.tscheckout.tsschema.tscart.test.tsapi-client.test.ts

Related files

Reads the session cookie. requireUser() guards private routes.

Used by

Start with a question. Find the context.

Explore the demoGet early access