Cursor rule

1---
2description: Express API conventions (Math Tutoring App)
3globs: api/**/*.js
4alwaysApply: false
5---
6 
7# API Patterns — `api/`
8 
9Stack: **Express** (CommonJS **`.js`**), **Vercel AI SDK** (`ai`, `@ai-sdk/openai`), deployed as **Vercel** serverless. **No database in this API** — persistence is **Firebase** from the **webapp** only.
10 
11## Folder layout (actual)
12 
13```
14api/
15  server.js          ← Express app, CORS, JSON, mounts routes, error handler
16  index.js             ← Vercel entry; re-exports app
17  routes/
18    chat.js            ← POST /chat, SSE streaming, tool schemas (Zod)
19  services/
20    promptService.js   ← System prompt / message building
21    contextManager.js  ← Conversation context helpers (if used)
22  src/lib/
23    logger.js            ← Pino singleton; pino-http attaches `req.log` per request (see server.js)
24  src/config/          ← Centralized env (Phase 4 — read REFACTOR_RUNBOOK.md)
25```
26 
27There is **no** `middleware/` or `prisma/` here. Do not add Prisma or hand-written SQL migrations to this project.
28 
29## Responsibilities
30 
31- **`routes/`** — Thin HTTP: validate inputs, call `services/`, set status codes, stream SSE. Avoid huge inline prompt strings; keep them in `services/promptService.js` (or dedicated modules under `services/`).
32- **`services/`** — Business-ish logic: prompt construction, helpers. No Firebase Admin for Firestore user data (removed by design); optional context utilities only.
33- **`server.js`** — App wiring only; avoid new domain logic here.
34 
35## LLM & streaming
36 
37- Use the **Vercel AI SDK** patterns already in `routes/chat.js` (`streamText`, tools, Zod `inputSchema`).
38- **OpenAI API key** must stay **server-side** only (`OPENAI_API_KEY`).
39 
40## Environment variables
41 
42- **Do not** scatter new `process.env` reads — the refactor runbook centralizes config under **`api/src/config/`** (Phase 4). Until then, follow existing patterns and Oxlint overrides documented in the runbook.
43 
44## Logging
45 
46- Import **`api/src/lib/logger.js`** for startup and process-level logs; in routes use **`req.log`** from **pino-http** (registered first in `server.js`).
47- Never use `console.*` in application code.
48 
49## Errors
50 
51- Prefer consistent JSON error shapes for new routes; match existing `{ error, message }` style in this codebase unless a refactor standardizes on another shape.
52 
53## SSE
54 
55- Chat streaming uses `text/event-stream` and `data: …` lines as already implemented; preserve headers (`Content-Type`, `Cache-Control`, `Connection`) when touching streaming code.
56