BFF API Layer (Frontend Standard)

This document defines the standard BFF approach for Next.js frontends.

Standard route layout (required)

• BFF routes live under /app/api/v1/*.
• They proxy to the backend’s /api/v1/* endpoints.

Railway internal/private backend URL (required)

• Backend base URL must be server-only (example name: BACKEND_BASE_URL).
• The browser must never see or call the backend base URL.
• The browser calls same-origin BFF endpoints only.

Responsibilities of a Route Handler (required)

For unsafe methods (POST/PUT/PATCH/DELETE), the BFF must:

• validate CSRF (token + origin/referer)
• read backend JWTs from HttpOnly cookies server-side
• attach Authorization: Bearer <access_jwt> to backend requests
• map backend errors to safe response shapes

For all requests, the BFF should:

• preserve/forward X-Request-Id when present
• avoid logging secrets/PII

Error mapping

Do not pass raw backend error bodies straight to the browser. Normalize errors into a safe, consistent envelope (project-specific details belong in the project repo; standards require a consistent shape).

Build-time caveat (required)

Avoid making backend calls from build-time code paths that execute during next build (SSG/generation). Internal/private hostnames may not be reachable during build.