From app launch to translated line: request flow in plain language

Understanding the flow helps you debug odd 401s, 429s, and missing history. The client never talks to OpenRouter directly; the backend is the trust boundary for both POST /api/translate (text) and POST /api/translate/image (camera or file upload).

Session bootstrap

On launch, the app validates a stored token against /api/auth/me. If that fails, it creates a guest via POST /api/auth/guest, optionally reusing a stable device key from secure storage.

Translate request

TranslationService posts JSON with text plus structured source and target language metadata. The server validates with Zod, verifies the JWT, opens a transaction, checks monthly usage, calls OpenRouter with a JSON-shaped prompt, inserts the row, commits, and returns translated text (and detected source when using auto-detect).

Errors you should expect

• 401 — Missing or invalid bearer token.
• 429 — Quota exceeded; guests often receive signInToContinue: true.
• 502 — Upstream model failure (text or image); retry with shorter input or a smaller image when possible.