flowCreate.solutions

Architecture (Frontend Standard)

This document defines the standard architecture for Flow Create Solutions frontends built with Next.js App Router.

High-level topology (BFF)

Frontends follow a Backend-for-Frontend (BFF) model:

  • The browser talks to Next.js over same-origin requests.
  • Next.js Route Handlers proxy to backend services.
  • Backend internal/private service URLs (Railway) are server-only and must never be called from the browser.
sequenceDiagram
  participant Browser
  participant NextApp as NextApp_RouteHandlers
  participant Backend as BackendAPI

  Browser->>NextApp: GET /app_page
  NextApp-->>Browser: HTML (ServerComponents) + assets

  Browser->>NextApp: POST /api/v1/things (CSRF token + cookies)
  Note over NextApp: Validate CSRF + read HttpOnly cookies
  NextApp->>Backend: POST /api/v1/things (Authorization: Bearer <access_jwt>)
  Backend-->>NextApp: StandardResponse
  NextApp-->>Browser: StandardResponse (sanitized)

Server-first rendering model (App Router)

Default posture:

  • Server Components by default (no use client unless needed).
  • Use Client Components only for:
    • interactive UI (events, animations)
    • browser-only APIs (local storage for non-secret UI prefs, media, clipboard, etc.)
    • complex client-only state

Railway internal URL boundary (required)

The rule

  • Browser never calls Railway internal/private hostnames.
  • Only server runtime code (Route Handlers, Server Components at runtime) may call internal/private hostnames.
  • Avoid requiring internal network connectivity at build time (e.g., don’t depend on backend connectivity during next build for SSG).

Practical implication

All client-side requests must target BFF endpoints like:

  • /api/v1/...

And BFF endpoints call the backend using a server-only base URL:

  • BACKEND_BASE_URL (example name; project defines its own) — not NEXT_PUBLIC_*.

Standard request/response shaping

Server-side proxying responsibilities

Route Handlers must:

  • validate CSRF for unsafe methods
  • attach backend auth (Authorization: Bearer ...) server-side
  • map backend errors to safe, consistent shapes (no secret leakage)
  • forward correlation headers when present (at minimum preserve X-Request-Id if the backend uses it)

Where project-specific truth lives

These standards are generic. A project repo must document:

  • exact env var names/values for its backend base URL(s)
  • the Railway internal hostname(s) used in production
  • any build-time rendering configuration that affects data fetching