ADR-0003: Next.js as BFF (Backend-For-Frontend)

Status

Accepted

Context

We need a frontend framework that handles SSR, auth sessions, and API proxying without creating a monolithic backend. The Go API handles business logic, but the frontend needs a trusted server-side layer for auth and data transformation.

Decision

Use Next.js 15 as a Backend-For-Frontend (BFF). Next.js handles:

• UI rendering (React Server Components)
• Auth sessions (Better Auth + Microsoft Entra SSO)
• Server Actions for mutations
• Proxying data to the Go API with auth headers

Next.js never communicates directly with PostgreSQL.

Consequences

Positive

• Clean separation: auth/UI in Next.js, business logic in Go
• Server Components reduce client bundle size
• Server Actions provide type-safe mutations
• BFF pattern allows data transformation before reaching the client

Negative

• Additional network hop (Client → Next.js → Go API)
• Need to keep Server Action types in sync with OpenAPI contract
• Two deployment targets (Vercel for Next.js, Fly.io for Go)