PRD · Design Doc · UI · ADR · Roadmap — 직접 써보세요

# PRD — Mini Chatbot

> **Sample PRD for the 10-week dev class.** Written in **English on purpose** — Claude Code
> (and every coding LLM) performs measurably better with English specs; Korean prompts
> degrade output quality. Write the *doc* in English even if you think in Korean.
>
> **Altitude rule (read this first):** a PRD says *what* and *why*. If a sentence names a
> function, a file, a framework, or a week of this class, it belongs in the Design Doc, the
> UI mockup, an ADR, or the roadmap — not here. This PRD should still make sense to someone
> who will never see the code. Notice how §6/§7 below hand off instead of specifying.
>
> **Format = synthesis of three sources:** big-tech PRD standard · ATI Labs house format
> (`passenger-flow-gen/docs/prd.md`) · the Meta-engineer PRD prompt (guardrail metrics,
> acceptance criteria, MoSCoW). The **W1 5-box PRD is the seed of §1–§5/§8 below**; the rest
> (§6 functional, §7 UX) grows over W2–W5.

**Status:** Draft · **Owner:** <you> · **Reviewers:** <mentor / senior> · **Last updated:** 2026-07-16

---

## 1. Summary
An assistant that answers a question in the place where the question came up, instead of
sending the person out to a search engine. MVP: one question in, one answer back.
(This is the class's reference app — grown week by week, W1 mockup → real model → deploy.)

## 2. Problem & Motivation
When a quick question comes up, people stop what they are doing, open a browser, search, skim
a page of blue links, and come back. The expensive part is not the seconds spent searching —
it is the broken context, and the fact that search returns **documents** when the person
wanted an **answer**. **Why now:** language models made a usable answer cheap. The missing
piece is no longer the answer; it is a thin, trustworthy surface to ask on.

## 3. Users & Use Cases
- **Primary user:** someone in the middle of a task with a one-off question, who will not
  invest a single minute in learning a tool.
- **Core use case:** ask in plain language → read the answer → get back to work.
- **Not our user (for now):** the researcher who needs sources, depth, and a trail (→ §5).

## 4. Goals & Success Metrics
- **G1 (the one MVP outcome) — a user gets a usable answer to a one-off question without
  leaving what they were doing.** One question, one answer, no detour.
- **Guardrail (counter-metric):** never worse than the search box we are replacing —
  (a) no dead end: every question gets *something* back, and (b) no confidently wrong answer
  that sends the user down the wrong path. In W1 the stubbed reply makes this trivially true;
  at W6, when a real model answers, this is the metric that bites.

## 5. Non-Goals (defer) ★ the most important section
Deciding what **not** to build is what makes the MVP shippable. Defer by **phase** — the class
week is just when we happen to get there.

| Deferred | Phase | Why not now |
|---|---|---|
| Accounts / login | Phase 2 (W2) | Nobody needs an identity to ask one question. |
| Remembering the conversation | Phase 2 (W2–4) | Single turn is enough to prove G1. |
| A real model behind the answer | Phase 3 (W6) | Today's answer is a stub — deliberately. |
| Voice, images, streaming, multi-turn memory | Later | Not on the path to G1. |
| Scale, caching, cost | Phase 3 (W3–5) | No users yet — optimizing now is guessing. |

## 6. Functional Requirements (MoSCoW)
- **Must:** the user can ask a question and see an answer appear, in the same place, without
  a reload. · **Should:** an empty question does nothing (no dead bubble). · **Could:** the
  wait *feels* like an answer being written. · **Won't (now):** everything in §5.
- **Acceptance criteria:** given an empty screen, when the user submits a question, an answer
  is visible in the same view within ~1 second, and the question is still visible next to it.

> *How* it renders (bubbles, alignment, auto-scroll, enter-to-send) is a screen decision →
> `UI-mini-chatbot.md`. *How* the answer is produced (one swappable seam) is an architecture
> decision → `design-doc-mini-chatbot.md` and `ADR-001-reply-seam.md`. Neither belongs here.

## 7. UX & Edge Cases (product-level only)
- **Happy path:** ask → answer, in place.
- **Empty state:** before the first question, the screen tells the user what it is for.
- **Empty / invalid input:** nothing happens; the user is never punished for a stray Enter.
- **Later (Phase 2+):** the answer fails to arrive; the question is too long; the user is
  not allowed to ask.

## 8. Success Criteria & Verification (the acceptance gate) ★ class pillar ③
**Observable, not asserted:** put the screen in front of **someone who is not you**, say
nothing, and watch them type a question and get an answer on the first try. That is "done"
for the MVP. (Not: "the send handler should work.") Everything in §4 G1 is visible in that
one moment — which is exactly why G1 was written as an outcome and not as a feature list.

## 9. Open Questions & Risks
- What backs the answer when the stub goes away — hosted model or our own? *(Decide at the
  Phase 3 boundary; it gets its own ADR — that is where a technology choice belongs.)*
- Does the guardrail (b) — "no confidently wrong answer" — need a human check, or can the
  product refuse to answer when unsure? **This is the real product risk.** Revisit before
  a real model ships.

# Design Doc (TRD) — Mini Chatbot

> **Sample Design Doc / RFC / TRD for the 10-week dev class.** Same document, different names
> across companies: **Design Doc** (Google), **RFC** (Request for Comments), **Design Proposal**
> (ATI Labs), **TRD** (Technical Requirements Document, Meta). It answers **"how"** (the PRD
> answers "what/why"); decisions extracted from it become **ADRs**.
>
> **Write in English** (better LLM output). **Format = synthesis:** big-tech Design Doc standard ·
> ATI Labs house format (`passenger-flow-gen/docs/facility-config-ui-design.md`) · the Meta-engineer
> TRD prompt (Mermaid architecture, NFR quality specs, deployment strategy).

**Status:** Draft · **Author (owner):** <you> · **Reviewers:** <senior/staff> ·
**Related:** `PRD-mini-chatbot.md` · `ADR-001-reply-seam.md` · **Last updated:** 2026-08-06

---

## 1. Context & Summary
Implements `PRD-mini-chatbot.md`. A single HTML page renders a chat log and a form; a **single
function `generateReply(message)`** produces the answer. Today it returns a stub string; the
whole point of isolating it is that later weeks swap the stub for a real LLM call **without
touching the UI**. Keep the core simple; absorb change behind one seam.

## 2. Goals & Non-Goals
- **Goals:** working single-turn UI; one clearly-named seam for the "answer"; zero build tooling (plain HTML/JS) at W1.
- **Non-Goals:** framework/bundler (W1), backend (until W2), streaming (later). See PRD §5.

## 3. Architecture
Client-only at W1; a backend seam appears at W2.

```mermaid
flowchart LR
  U[User] -->|type + send| F["Chat UI (index.html)"]
  F -->|message| G["generateReply(message) ← the seam"]
  G -->|W1: stub string| F
  G -.->|W6: HTTP| API["backend · POST /chat"]
  API -.-> LLM[("LLM serving · vLLM")]
```

- **`generateReply()` is the seam (W3 concept).** W6 changes only this function to call the
  backend; W5 adds a cache here; the UI never changes.
- **Components:** `index.html` (markup + styles + the log/form), one `<script>` (append bubbles,
  call the seam). No global state beyond the DOM at W1.

### 3.1 Production target (where this is headed) ★

Don't build this today — **build the 🟢 slice and leave the seam where production attaches.**
This picture is the *reason* W1 stays thin: every later concern lands at a **known joint**, so no
week forces a UI rewrite. The rollout in §9 walks this diagram left-to-right, one PR per week.

```mermaid
flowchart TB
  subgraph TODAY["🟢 W1 — what you actually build today"]
    direction LR
    UI["Chat UI (index.html)"] --> SEAM["generateReply(message)<br/>stub string · the seam"]
  end

  subgraph TARGET["Production target — same UI + same seam, internals grow W2 → W9"]
    direction TB
    LB["Load balancer"] --> APP
    subgraph APP["Stateless app · N replicas — W3 / W4"]
      AUTH["Auth guard — W2"] --> LIM["Rate limit — W2 / W9"] --> S2["generateReply()<br/>HTTP call — W6"]
    end
    S2 --> CACHE["Reply cache — W5"] --> LLM["LLM serving · vLLM — W6"]
    APP --> DB[("messages / users — W2 ~ W4")]
    APP --> OBS["Metrics · structured logs — W2 / W9"]
  end

  UI -. "same front-end, unchanged" .-> LB
```

- **The seam is the only joint that moves.** Today it returns a stub; W6 makes it an HTTP call;
  W5 slots a cache in front of it. The UI never changes — that is the whole payoff of ADR-001.
- **Every production concern has a home already:** auth + rate-limit wrap the request path (§5),
  the app is designed **stateless** so W3 can run N replicas behind the load balancer (§5 Scale),
  persistence and metrics attach at W2–W4/W9. You are pre-structuring, not pre-building.
- **What "production" adds beyond W1** = the boxes outside the 🟢 slice. Read §5 (NFRs) for *what*
  each is and §9 (rollout) for *when* it lands. If a box isn't needed for your scale yet, it stays
  on the diagram as a labeled target — **scale-correct now, tune later** (don't build it early).

## 4. Data & API Design
- **W1:** no data model; messages live in the DOM only.
- **W2+ (planned):** `POST /chat { message } → { reply }` (REST, JSON, status codes 200/400/401/429).
- **W2+ persistence:** `messages(id, user_id, role, text, created_at)` — added with auth, not before.

## 5. Non-Functional Requirements (the "quality" specs) — grown over the class
- **Security (W2):** auth guard on `/chat`; never ship an API key in client JS (see the disaster cases — Cara/Lovable). Secrets server-side only.
- **Rate limiting (W2/W9):** per-user key + limit so one caller can't drain the token budget.
- **Performance (W5):** target p95 reply latency; measure before optimizing.
- **Observability (W2/W9):** structured request logs; GPU/latency metrics once a model is live.
- **Scale (W3):** stateless request path so we can run N replicas behind a load balancer.

## 6. Alternatives Considered
- **Inline the answer logic in the submit handler** — rejected: no seam, so W6 would rewrite the UI.
- **Start with a framework (React) at W1** — rejected: build tooling overhead buys nothing for a one-page MVP; add when state/reuse justify it.
- **Multi-turn from day 1** — rejected: violates PRD Non-Goals; single-turn first.

## 7. Risks & Dependencies
- **Risk:** the stub hides real latency/error behavior → surfaces at W6. Mitigate by keeping the seam's signature `(message) → replyString` stable.
- **Dependency:** W6 needs a serving endpoint (hosted API or on-prem vLLM) — decided in a W6 ADR.

## 8. Verification

How someone else can tell this works — as checks they can run, not as a claim you make.
**An endpoint returning `200` is not the same as working**, and here the same trap wears a
different hat: *a stub that always answers instantly and never throws proves nothing about the
UI you will actually ship.* See 8.3.

### 8.1 What "working" means

| Situation | What the user should see | What must be verified |
|---|---|---|
| Types a message and sends | Their bubble appears, then the reply bubble; the input clears and refocuses | The seam is called exactly once with the typed text; the log order is send-then-reply |
| Sends empty or whitespace-only input | Nothing is sent, nothing appears, no error | The submit handler returns early — the seam is never called |
| The reply is slow (W6) | A pending indicator; the send button is disabled while in flight | No second request can be started; the pending state clears on both success **and** failure |
| The reply fails (W6) | An error bubble that says something went wrong; the earlier log is still there and the UI still usable | The failure is caught at the seam; the UI does not blank, freeze, or lose history |
| A reply contains markup | It renders **as text** — `<script>alert(1)</script>` shows those characters, no popup | Insertion is `textContent`, never `innerHTML` (this is the W2 XSS lesson, checked from W1) |

**"No reply yet" and "the reply failed" must not look the same.** If both render as an empty or
frozen bubble, every backend failure at W6 reads as slowness and you will debug the wrong thing.

### 8.2 Checks

Each is a click or a command with a visible pass/fail. *"The code looks right" is not a check.*

1. Type `hello` → Enter. Two bubbles appear, in order, and the input is empty and focused.
2. Press Enter on an empty box, then on spaces only → nothing happens, no console error.
3. Paste `<script>alert(1)</script>` as the message → it shows as those characters. **No alert box.**
4. Temporarily make the stub wait 3 s (8.3) → the send button is disabled for those 3 s, and
   hammering Enter produces exactly one reply.
5. Temporarily make the stub throw (8.3) → an error bubble appears, the earlier bubbles are still
   there, and you can send a normal message afterwards.
6. **The seam check (this is the one that matters).** Swap the stub for the real HTTP call, then
   `git diff --stat index.html` → **0 changed lines** if the markup and script are separate files,
   or a diff touching only `generateReply()` if they are not. A UI diff here means ADR-001 did not
   hold and W6 just cost you a rewrite.
7. From W2 on: open devtools → Sources and search the client bundle for the API key → **no hits**.

### 8.3 Stand-in — make the stub lie less

The stub *is* our stand-in for the LLM, and by default it is the dishonest kind: instant, always
successful, always well-formed. A UI verified only against that has **never seen latency, an error,
or a slow user double-clicking** — exactly the risk §7 says surfaces at W6.

So give the stub the three behaviours the real thing has, behind a flag you can flip by hand:

| Mode | Stub does | Catches |
|---|---|---|
| `normal` | returns the canned string | the happy path |
| `slow` | waits ~3 s first | missing pending state, double-send, disabled-button bugs |
| `fail` | throws | missing error handling, a UI that blanks or freezes on failure |

Keep the signature `(message) → replyString` (a Promise from W6 on) identical in all three — the
point is that the UI cannot tell which mode it is in. That is what makes it a stand-in rather than
a test double the real code path will never resemble.

### 8.4 Invariants

- The seam's signature stays `(message) → replyString`; the UI reads **only** its return value.
- The seam is called exactly once per send — never zero times, never twice.
- Bubbles never appear out of order, even if two sends overlap.
- No secret ever reaches client-side code (W2 on).
- Swapping what is *inside* the seam changes no UI code.

### 8.5 Bars

| Bar | Passing means |
|---|---|
| **W1 done** | Checks 1–3 pass, and 4–5 pass with the stub in `slow` and `fail` mode |
| **Seam held (W6)** | Check 6 shows no UI diff when the stub becomes a real HTTP call |
| **Secrets clean (W2)** | Check 7 finds nothing, on every build that ships |
| **Latency (W5)** | p95 measured under `slow`-mode-like conditions and **written down even if it misses target** — a number you only quote when it flatters you is not a bar |

## 9. Rollout / Phasing
W1 stub UI → W2 auth + backend seam → W3 stateless/scale → W5 perf/cache → **W6 real LLM** →
W10 deploy. Each week is one PR against a living version of this doc.
- **Go-live bar:** the §8.5 bar for that week passes. W6 does not start until check 6 is green on
  the stub swap — a rollout stage without its bar is a hope, not a rollout.

# UI — Mini Chatbot (text mockup)

> **Describe the screen to Claude Code — in words.** No design tool needed. This is the "UI mockup"
> you feed alongside the PRD + Design Doc. (Write in **English** for best results.)
>
> **Two different languages, on purpose.** The *doc* is English (better LLM output); the *UI copy
> your users read* stays in the product's own language. So the button below is **"보내기"** and the
> empty-state hint is Korean — quote those strings verbatim, don't translate them into the doc's
> language, or Claude Code will ship an English UI to Korean users.

## Screen: chat
One centered card (~520px wide, ~680px tall) on a light-gray page background.

- **Header** (top of card): app name **"Mini Chatbot"** in bold + one line of small gray subtext
  ("ask me anything").
- **Message log** (fills the middle, scrolls vertically):
  - **User messages** — right-aligned, purple bubble, white text, rounded (bottom-right corner squared).
  - **Bot messages** — left-aligned, light-gray bubble, dark text (bottom-left corner squared).
  - **Empty state** (before the first message): a small centered hint, "아무거나 물어보세요 👇".
- **Input bar** (fixed at the bottom): a text input that grows to fill + a **"보내기"** button (purple).

## Behavior
- Press Enter or click **보내기** → append the user's bubble, then after ~0.4s append the bot reply.
- **Empty input** → do nothing (no empty bubble).
- Auto-scroll to the newest message.

## Style
- System sans-serif. Accent **purple `#6C5CF0`**. Card: white, 16px radius, soft shadow.
- Minimal — one screen, no nav, no settings, no avatars.

## Prompt to give Claude Code
> "Build this as a **single self-contained `index.html`** (inline CSS + JS, no libraries). [paste the
> sections above]. The reply is produced by one function **`generateReply(message)`** — return a stub
> string for now (real LLM comes later). Match the style notes."

*(Tip: ask for 2–3 variations and pick the best. Or add "make it look like <a site you like>".)*

# ADR-001 — Reply generation: isolate behind one `generateReply()` seam

> **Sample ADR (Architecture Decision Record) for the 10-week dev class.** An ADR captures
> **one decision**: what was chosen, why, and what was rejected — short and **immutable**
> (a later change supersedes it with a new ADR; you don't edit history). **Write in English.**
> **Format = ATI Labs house ADR** (`onprem-llm-wiki/decisions/ADR-001-serving-engine.md`),
> which is the big-tech ADR standard (Nygard) plus a **Verdict** section for measured decisions.

- **Status:** accepted _(2026-07-16)_
- **Date:** 2026-07-16
- **Deciders:** <you> (owner)
- **Context source:** `PRD-mini-chatbot.md` · `design-doc-mini-chatbot.md` §3
- **Related:** a future **ADR-002** (W6) will decide *which* LLM backs the seam (hosted vs on-prem).

## Context
The mini chatbot must produce a reply for each message. At W1 there is no real model — the reply
is a stub. But we know a real LLM arrives at W6, caching at W5, and possibly a backend at W2.
Where the "make an answer" logic lives now determines how much we rewrite later. Two forces:
**(1) ship a visible MVP today** (a stub is fine), and **(2) don't repaint the UI every time the
answer source changes.** A beginner working with AI can build either shape; the decision is which
one to *ask the AI to build*.

## Decision
**All "produce an answer" logic lives in one function, `generateReply(message) → string`,** called
by the submit handler. W1 returns a stub. Later weeks change **only this function**: W6 makes it an
HTTP call to the backend; W5 adds a cache in front of it. The UI (append user bubble, append bot
bubble) never changes. This is the "seam" concept the class teaches at W3.

## Options considered
- **Seam function (chosen)** — one named function isolates the volatile part. _Cost:_ one tiny
  indirection now. _Benefit:_ W6 is a 5-line change, not a UI rewrite.
- **Inline in the submit handler** — rejected: fastest to type, but W6 forces editing the UI code
  and its tests; the volatile and stable parts get tangled.
- **Premature abstraction (provider interface, DI container)** — rejected: over-engineered for one
  call site (YAGNI). A single function is the right altitude; promote to an interface only if a
  second answer source actually appears.

## Consequences
- **Positive:** swapping stub → real LLM (W6) touches one function; UI, tests, and styling are
  untouched. Caching (W5) and backend routing (W2) also attach at the same seam.
- **Negative:** the stub hides real latency/error/streaming behavior, which only surfaces at W6.
  Mitigation: keep the seam's signature `(message) → replyString` stable, and add async handling
  when the real call lands (revisit in the W6 ADR).
- **Reversible:** the seam is a local refactor; if a different shape is needed later, supersede
  this ADR — no wide blast radius.

## Verdict
_(Fill after the W6 swap: did changing only `generateReply()` deliver a working real-LLM reply
without UI edits? PASS/FAIL + one line. This mirrors the house style — commit the rule up front,
record the measured outcome later, no post-hoc rationalization.)_

# Roadmap — Mini Chatbot (living doc)

> **What this file is.** Claude Code resets its memory every session. This `roadmap.md` is the
> **cross-session memory anchor** — paste it (or have it read) at the start of each session so the
> AI knows *where the project is* before you ask for anything. Keep it at your repo root and update
> it every session: what's done, what's next, one decision line. **Write in English.**
>
> Maintaining this file *is itself* the skill the class teaches: giving an LLM durable context.

## Status board (update every session)
- **Current week:** W1 · **Repo:** `mini-chatbot/`
- **Last done:** W1 stub UI renders; send → user bubble → stub bot reply (verified in browser).
- **Next step:** W2 — add a backend seam + auth guard on `/chat`.
- **Blockers:** none.

## 10-week plan (goal per week · status)
| Week | Goal | Status |
|---|---|---|
| **W1** | Whole loop + PRD; stub chat UI | ✅ done |
| W2 | Auth · secrets · logging (guard `/chat`) | ⬜ next |
| W3 | Scale · the seam · stateless request path | ⬜ |
| W4 | Architecture · data model (messages table) | ⬜ |
| W5 | Performance · measure p95 · cache at the seam | ⬜ |
| W6 | Real LLM behind `generateReply()` | ⬜ |
| W7 | Faster (streaming / batching) | ⬜ |
| W8 | Cheaper · bigger | ⬜ |
| W9 | Ops · rate limit · monitoring | ⬜ |
| W10 | Present · deploy · run | ⬜ |

## Documents (this project)
- PRD → `docs/prd.md` (what/why) · seeded from the W1 5-box.
- Design Doc → `docs/design-doc.md` (how) · living, grows each week.
- Decisions → `docs/decisions/ADR-001-reply-seam.md` (immutable).

## Decisions log (one line each → link the ADR)
- **ADR-001** (W1) — reply logic isolated behind `generateReply()` seam. → swap at W6.

## Open questions
- W6: which model backs the seam — hosted API vs on-prem? (decide with a W6 ADR)
- W2: history before or after auth?

## Session log (append, newest last)
- **2026-07-16** — W1: PRD written, stub UI built with Claude Code, verified reply renders.

# Design Doc (TRD) — Add Authentication & Security to <Your App>

> W2 filled example. **Copy this whole doc, fill the `<...>`, and paste it to Claude Code**
> (prompt at the bottom). It produces the "hardened app" you saw attacked in class —
> brute-force, SQL injection, IDOR, no-auth, flood, XSS and CSRF all bounce off.
> Write in English (better LLM output). Decisions here are recorded as ADRs.

**Status:** Draft → In Review → Approved → Implemented  ·  **Author (owner):** <you> ·
**Reviewers:** <mentor> · **Related:** <PRD link> · ADR-002 (auth approach) · **Last updated:** <YYYY-MM-DD>

---

## 1. Context & Summary
The app from W1 (`<e.g. a notes app / mini chatbot with saved history>`) currently has **no login
and no access control** — anyone can read anyone's data and the server trusts all input.
This doc adds **authentication (who are you) and authorization (are you allowed)** plus the baseline
hardening that stops the attacks that actually breach small apps.

**Threat model note (why "we're too small to be a target" is not true anymore):** most traffic that
finds a new public endpoint is automated. Scanners sweep continuously, and in 2026 a frontier AI model
autonomously escaped its own sandbox and breached a production service by chaining ordinary flaws —
**command injection into a proxy, an over-privileged process, and credentials left lying on a server**.
The defenses below are exactly the ones that would have stopped it. Design for a tireless attacker,
not an occasional one.

## 2. Goals & Non-Goals
- **Goals:** users log in; each user sees only their own data; passwords are stored safely;
  brute-force, injection, cross-site attacks and request floods are blocked; **a single compromise
  stays contained** (least privilege, credential hygiene, audit trail).
- **Non-Goals (defer):** social login / OAuth, MFA, SSO, a CDN/WAF edge layer (that's the *scale*
  week). Ship the app layer first.

## 3. Architecture (auth flow)
```mermaid
flowchart LR
  User --> Login[POST /login]
  Login -->|verify bcrypt hash| DB[(users)]
  Login -->|access token, short TTL| Mem[held in memory by the client]
  Login -->|refresh token, HttpOnly cookie| Cookie[(browser cookie)]
  Mem -->|Authorization: Bearer| API[protected endpoints]
  API -->|verify signature + exp| API
  API -->|owner_id == me ?| DB
  Cookie --> Refresh[POST /refresh -> rotate] --> Mem
```
- **Token-based auth (JWT).** The access token is **short-lived (~15 min)** and never written to
  `localStorage`; the **refresh token lives in an `HttpOnly` cookie** the browser's JavaScript cannot read.
- The **seam**: one `require_login()` / `current_user()` helper used by every protected endpoint —
  the only place auth is read, so the scheme can be swapped without touching the rest of the app.

## 4. Data & API
- **Data model — `users`:** `id`, `email` (unique), `password_hash` (bcrypt, never plaintext),
  `token_version` (bump to invalidate all of a user's tokens), `created_at`.
  Every user-owned row (notes, messages, …) has an `owner_id` → `users.id`.
- **Data model — `refresh_tokens`:** `jti` (unique id), `user_id`, `expires_at`, `revoked_at`.
  This is the small piece of server state that makes logout and revocation actually work.
- **API:**
  - `POST /login    { email, password } → 200 { access_token } + refresh cookie | 401`
  - `POST /refresh  (refresh cookie) → 200 { access_token } + NEW refresh cookie | 401`  (rotate on every use)
  - `POST /logout   → 200`  (revoke the refresh token; bump `token_version`)
  - `GET  /me/items → 200 [ my items ]`  (login required)
  - `GET  /items/{id} → 200 | 401 (no valid token) | 403 (not my item)`

## 5. Security Requirements  ★ (the core — implement all)
Organized by the **seven points a request passes through**: input → transport → inflow → identity →
authorization → storage → output. Each point gets its own "don't trust this".

### 5.1 Input — never let input become a command
- **Parameterized queries only.** Never build SQL by string concatenation/format; use bound
  parameters (`WHERE email = ?`). *(SQL injection.)*
- **Validate and normalize at the boundary** — types, lengths, formats, allow-lists.
- **Same rule for AI features.** If the app calls an LLM, user text is **data, not instructions**:
  keep system instructions separate, and never let model output trigger a privileged action without
  a server-side check. *(Prompt injection is the same root cause as SQL injection.)*

### 5.2 Transport — the road is not safe
- **HTTPS everywhere**, plus `Strict-Transport-Security`. No credentials over plain HTTP.

### 5.3 Inflow — don't accept unlimited requests
- **Login lockout** — after **5** failed logins for an account (or IP), lock for a cooldown → **429**.
- **Rate limiting** — per-IP sliding window on all endpoints; over the limit → **429**.

### 5.4 Identity — a token is a claim, not a fact
- **Sign with a strong secret/key**, pin the algorithm server-side, and **reject `alg: none`**.
- **Short expiry (~15 min)** on access tokens; verify `exp` on every request.
- **A JWT is signed, not encrypted** — anyone can read its contents. **Never put secrets,
  passwords, or personal data in the payload.**
- **Storage:** access token in memory; **refresh token in an `HttpOnly` + `Secure` + `SameSite`
  cookie**. Do **not** put tokens in `localStorage` — any XSS reads them instantly and the attacker
  can then use them from their own machine. *(See ADR-002.)*
- **Revocation:** rotate the refresh token on every use, store its `jti`, and reject reuse.
  Logout revokes the refresh token and bumps `token_version`.

### 5.5 Authorization — logging in is not permission
- For any resource with an owner, check `resource.owner_id == current_user.id` on **every request**
  → **403** otherwise. A hidden button in the frontend is **not** a control. *(IDOR / BOLA.)*
- **Role checks (RBAC)** for admin-only actions, and **least privilege everywhere**: the app's DB user,
  workers, and any background/agent process get only the permissions they actually need — **never root**.

### 5.6 Storage — assume it will be read some day
- **Passwords: bcrypt (or argon2) with a per-user salt.** Never plaintext, never plain SHA-256.
- **Secrets from the environment** — DB URL, signing key, API keys from env vars / a secrets manager.
  Never commit them; `.env` in `.gitignore`. **Rotate immediately if one is ever exposed.**

### 5.7 Output — be careful on the way out too
- **Escape on render.** User text goes into the page as **text, not markup** — use the framework's
  auto-escaping and never build HTML with raw `innerHTML`. *(XSS.)*
- **CSRF:** because the refresh cookie is sent automatically, set `SameSite=Lax|Strict` and require a
  CSRF token on cookie-authenticated state-changing routes. (Bearer-header routes are not CSRF-able.)
- **Don't leak in errors** — generic messages to the client, details to the log.

### 5.8 Containment — assume one thing will fail
- **Structured audit log:** `{time, user, action, result}`. **Never log passwords, tokens, or secrets.**
- **Watch outbound traffic**, not just inbound — stolen data has to leave somehow.
- **Use battle-tested libraries.** Do not hand-roll crypto, JWT verification, or auth.

## 6. Alternatives Considered
- **Session vs JWT vs OAuth** — chose JWT; see **ADR-002** for why and what was rejected.
- **Token storage: `localStorage` vs `HttpOnly` cookie vs memory + cookie** — chose memory + cookie
  (ADR-002). `localStorage` is the common tutorial default and the weakest against XSS.
- **SHA-256 vs bcrypt for passwords** — bcrypt (slow + salted); SHA-256 is too fast and unsalted.

## 7. Verification  ★ (how we prove it — run these after building)
1. Open the DB: the password column shows `$2b$...` (a bcrypt hash), **not** `1234`.
2. Log in as user A, request user B's item by id → **403**.
3. Call a protected endpoint with no token → **401**.
4. Send `' OR '1'='1` as the password → login **fails** (not bypassed).
5. Hit an endpoint 100× fast → starts returning **429**.
6. Post `<script>alert(1)</script>` as content → it shows up **as text**, no popup.
7. In devtools, `document.cookie` does **not** show the refresh token (it's `HttpOnly`),
   and no token is in `localStorage`.
8. Log out, then reuse the old refresh token → **401**, and it cannot be rotated back in.
9. `grep` the logs for a known password and for `Bearer` → **no hits**.
10. Enter the wrong password 5× for one account → the 6th attempt is **locked out (429)**,
    and even the *correct* password is refused until the cooldown ends.

Each check must be runnable by hand — a command or a click, with a visible pass/fail.
"The code looks right" is not a check.

## 8. Rollout / Phasing
- Ship §5.1–5.7 together (they're one layer); §5.8 lands with it — logging is not optional.
- **Go-live bar:** all ten checks in §7 pass. A check that "should pass" has not passed.
- Later (scale week): edge rate-limit / WAF / CDN in front of the app.

---

## Prompt to give Claude Code
> Read this design doc, then implement it on my app.
> [paste this whole document, with the `<...>` filled in]
> Use my stack's standard libraries for password hashing (bcrypt/argon2), JWT verification and the DB
> layer — do not hand-roll crypto. Parameterized queries everywhere. Access token in memory, refresh
> token in an HttpOnly + Secure + SameSite cookie, rotated on every use. If my app has no database
> yet, create one (SQLite is fine) as part of this. Then walk me through the ten checks in §7 one by
> one — for each, the exact thing I click or run, and what I should see on screen if it passed.

# ADR-002 — Authentication approach: JWT (short access token + rotating refresh cookie) + bcrypt + per-request authorization

> W2 filled example. One decision, short and **immutable** — if you change it later, write a *new*
> ADR that supersedes this one (don't edit history). Write in English.
> Copy this, adjust to your app, and keep it next to your design doc.

- **Status:** accepted _(YYYY-MM-DD)_
- **Date:** <YYYY-MM-DD>
- **Deciders:** <you> (+ mentor review)
- **Context source:** PRD <link> · Design Doc — Add Authentication & Security
- **Related:** ADR-001 (reply seam)

## Context
The app needs login and per-user data isolation, and `<a mobile client / a second service>` will call
the same API, so login state has to travel outside one browser session. We must pick **how login state
is carried**, **where the client keeps it**, and **how passwords are stored** — without over-building.

The forces: ship fast, but don't create the breaches we studied — plaintext passwords, "logged in =
can see everything", input executed as a command, and tokens that an attacker can lift and reuse.
Two facts from class shape this decision:

- **What decides XSS/CSRF exposure is not "session vs JWT" — it is *where the credential is stored*.**
  Anything JavaScript can read is gone the moment there is one XSS; anything the browser attaches
  automatically can be triggered by another site.
- **A token that cannot be revoked is a liability.** JWT's usual weakness is that it stays valid until
  it expires, so the design has to buy revocation back explicitly.

## Decision
- **Login state = JWT.** A **short-lived access token (~15 min)** sent as `Authorization: Bearer`,
  **held in memory** by the client — never in `localStorage`.
- **Refresh token in an `HttpOnly` + `Secure` + `SameSite` cookie**, **rotated on every use**, with its
  `jti` stored server-side so reuse is detected and logout actually revokes. `token_version` on the user
  row kills every outstanding token at once.
- **Passwords = bcrypt hash + per-user salt** (never plaintext, never plain SHA-256).
- **Authorization = checked on every request:** for any owned resource, `resource.owner_id ==
  current_user.id` or **403**. The frontend hiding a field is **not** a control.
- **Queries parameterized**; **secrets from env**; **login = 5-fail lockout + rate limit**;
  **least privilege** for every process (no root workers).

## Options considered
- **JWT, access in memory + refresh in HttpOnly cookie (chosen)** — works for browser *and* non-browser
  clients; nothing readable by JavaScript; rotation + `jti` restores the revocation that plain JWT lacks.
  Cost: more moving parts than a session, and we keep a small amount of server state after all.
- **JWT in `localStorage`** — rejected. It is the common tutorial default and the weakest option: one XSS
  reads the token in a single line, and the attacker then replays it **from their own machine, for as long
  as it is valid**. Convenience is not worth an exfiltratable credential.
- **Server-side session + opaque cookie** — rejected *for this app*, not on principle. It is genuinely
  simpler and revokes instantly, and it would be the right pick for a browser-only single-server app.
  We need a token our non-browser client can carry, and we don't want shared session storage when we
  add a second server.
- **OAuth / social login ("Log in with Google")** — deferred: extra setup and a third-party dependency
  the MVP doesn't need. Add later behind the same seam if users ask for it.

## Consequences
- **Positive:** one auth scheme for every client; no credential is reachable from JavaScript; automatic
  cookie attachment is contained by `SameSite` + CSRF token; the four classic breaches are closed by construction.
- **Negative / accepted:** an access token stays valid until it expires (≤15 min) even after logout —
  we accept that window and cut it with short TTL + refresh revocation. Rotation adds a table and a
  refresh endpoint to maintain. Signing-key leakage forges any user, so the key is env-only and rotatable.
- **Reversible?** Yes — auth is read only through `current_user()` / `require_login()`, so moving to
  sessions or OAuth touches one place, not the whole app.

## Verdict
_(Fill after you test.)_ PASS/FAIL — DB shows `$2b$…` (not plaintext) · other user's id → 403 ·
no token → 401 · `' OR '1'='1` login → fails · 100 fast requests → 429 ·
`<script>` renders as text · refresh token invisible to `document.cookie`, nothing in `localStorage` ·
reused refresh token after logout → 401 · 5 wrong passwords → locked out.