Frontend Authentication Routes

Introduction

The Frontend Authentication Routes provide the user interface and client-side logic for managing user identity within the Product Compare application. These routes handle critical flows such as user registration, session establishment (login), password recovery, and email verification. The system is designed to migrate away from legacy REST endpoints toward a GraphQL-driven contract while maintaining the Phoenix backend as the primary cookie-backed session authority.

Sources: AGENTS.md:33-35, ARCHITECTURE.md:10-12

The authentication frontend is built using React and React Router, leveraging a shared UI shell to ensure consistency across different auth states. It communicates with the backend via a dedicated GraphQL endpoint (/api/graphql), where mutations are used to set or clear Phoenix session cookies.

Sources: AGENTS.md:33-35, assets/src/router.tsx:34-58

Architecture and Data Flow

GraphQL Auth Contract

The frontend auth implementation adheres to a specific "Auth Contract" where browser-facing flows must use GraphQL mutations. These mutations do not return bearer tokens; instead, they rely on the Phoenix backend to manage session state via HTTP-only cookies.

Sources: AGENTS.md:33-40

This diagram illustrates the flow where GraphQL mutations interact with the Phoenix session authority to manage browser cookies.
Sources: AGENTS.md:36-40, assets/src/relay/tests/fetch-graphql.test.ts:9-15

Shared UI Components

Authentication views are composed using a set of shared primitives defined in the form-shell.tsx module. This ensures that labels, inputs, and validation messages behave consistently.

Sources: assets/src/routes/auth/form-shell.tsx:90-192

Authentication Modules

Login and Registration

The LoginRoute and RegisterRoute handle the primary entry points for users. Both modules utilize local React state to manage submission status and error arrays returned from the GraphQL API.

• Logic: Upon a successful mutation (e.g., loginWithPassword or registerWithPassword), the application receives a viewer object and performs a client-side redirect to the root path (/).
• Error Handling: If the API returns validation errors (e.g., INVALID_CREDENTIALS), these are mapped to specific fields or displayed as global alerts within the AuthFormShell.

Sources: assets/src/routes/auth/login.tsx:16-36, assets/src/routes/auth/register.tsx:16-36

Password Recovery

The password recovery system is split into the ForgotPasswordRoute and ResetPasswordRoute. The reset flow is uniquely sensitive to URL parameters, as it requires a token query parameter to prove identity.

The ResetPasswordRoute includes internal version tracking (activeRequestVersion) to prevent race conditions where a late response from a stale token could overwrite the UI state after a user has updated their parameters.
Sources: assets/src/routes/auth/reset-password.tsx:21-65

API and Network Layer

The frontend uses a custom network fetcher, fetchGraphQL, to communicate with the backend.

Request Configuration

Outside of local development, the system requires VITE_API_BASE_URL to be configured. For browser-based requests, it explicitly includes credentials to allow the transport of Phoenix session cookies.

Sources: assets/src/relay/tests/fetch-graphql.test.ts:15-68

Summary

The Frontend Authentication Routes form a secure, unified entry system for the Product Compare platform. By centralizing UI logic in the AuthFormShell and enforcing a GraphQL-only auth contract, the system ensures that session management remains the responsibility of the Phoenix backend while providing a highly responsive, React-driven user experience. The use of Relay-style global IDs and preloaded queries is the planned next step for these routes to further integrate with the project's data architecture.

Sources: ARCHITECTURE.md:14-25, AGENTS.md:42-45