Walk me through code I just inherited.
The onboarding read you don't have a colleague to give you. Structure, purpose, gotchas, and the specific parts to be careful about.
You just opened a file you didn't write. Maybe it's a legacy service you're now on-call for. Maybe it's an OSS library you need to modify. Either way, you have 30 minutes before you need to be productive in it. This prompt gets you oriented fast.
THE PROMPT
Walk me through the following code as if you were a colleague onboarding me. I'll paste it below. Structure your explanation as: **Purpose (one paragraph)** — what this code exists to do, in one paragraph that a non-author could grasp. Don't restate the function names. **Architecture (bullets)** — 3-5 bullets on how the code is organized. What are the key abstractions? What flows through what? **The parts I should read first** — bulleted list of 3-5 lines or blocks, in order of importance for understanding. Reference file line ranges if the paste has them. **Gotchas** — where are the bodies buried? Non-obvious behaviors, historical choices, coupling to other systems, silent failures. Be specific. **What would I break if I changed X** — a rough map of blast radius. Which changes are safe, which are load-bearing. If the code has clear technical debt, name it once at the bottom in a "Debt worth noting" section — but don't lecture, just note. Code: [PASTE CODE]
**Purpose**
This module owns the order lifecycle: it takes a cart, validates it, holds inventory, creates a Stripe payment intent, and marks the order as paid or failed. The three exported functions correspond to the three stages a customer might get stuck at.
**Architecture**
- Three stateless functions (`validateCart`, `createPaymentIntent`, `markPaid`) that each read from and write to Postgres via the shared `pg` connection.
- No queue — everything is synchronous within a request. Retries happen at the HTTP layer.
- Stripe idempotency keys are derived from `order.id + attempt` — critical, easy to break.
**The parts I should read first**
- `validateCart` (lines 20–65) — this is where 80% of edge cases live.
- The `markPaid` transaction (lines 140–180) — the only place two tables are updated atomically. Everything else is single-table.
- The webhook signature verification (lines 220–240) — non-obvious and security-critical.
**Gotchas**
- `processOrder` at the bottom is a wrapper the older API routes still call. It's deprecated in favor of the three-function API but hasn't been removed.
- Cart validation silently drops items whose `quantity` is 0 without logging. Look at line 47.
- Stripe timeouts are handled by returning success — that's a legacy behavior tied to how our old webhook cadence worked, and it will bite you if you assume "no error" means "payment cleared".
**What would I break if I changed X**
- Changing the shape of `Order` — high blast radius, ~14 callers.
- Changing what `markPaid` writes — low blast radius, only `processOrder` calls it externally.
- Renaming any of the three exports — anything importing this module will break; ~30 files.
**Debt worth noting**
The deprecated `processOrder` wrapper should be removed once the last three legacy callers are migrated.