============
Web Frontend
============

Repository: ``bridges-frontend-source-code/oim-frontend-staging``

The beneficiary-facing web application is a **Next.js** (App Router) project
written in TypeScript and React, styled with Tailwind CSS and the shadcn/ui
component system (Radix primitives).

Technology
==========

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Concern
     - Implementation
   * - Framework
     - Next.js (App Router) + React
   * - Language
     - TypeScript
   * - Styling
     - Tailwind CSS, ``tailwindcss-animate``, ``class-variance-authority``
   * - UI components
     - Radix UI primitives / shadcn/ui, ``lucide-react`` icons
   * - State / data
     - ``zustand`` (stores), ``@tanstack/react-query`` (server state)
   * - Forms / validation
     - ``react-hook-form`` + ``zod``
   * - HTTP
     - ``axios``
   * - i18n
     - ``next-intl``
   * - Charts
     - ``recharts``

Source Structure
================

.. code-block:: text

   src/
     app/                 # App Router routes
       auth/              # sign-in, login, forgot/reset password, verify email
       home/              # authenticated landing
       forms/             # profile and intake forms
       recommendations/   # results, saved, profile, limited views
     components/
       ui/                # shadcn/ui primitives
       auth/  home/  layout/  oim/  providers/
     providers/auth/      # authentication context provider
     stores/              # zustand stores
     services/            # API client services
     hooks/  lib/  i18n/  types/

Key Routes
==========

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Route group
     - Purpose
   * - ``/auth/*``
     - Registration, login, email verification, and password reset flows
   * - ``/home``
     - Authenticated home / dashboard
   * - ``/forms``
     - Beneficiary profile and intake forms
   * - ``/recommendations``
     - Recommendation results, with ``/saved``, ``/profile``, and ``/limited``
       sub-views

Backend Integration
===================

The frontend communicates with the backend API through the service layer in
``src/services`` using ``axios``. Server state is cached with React Query, while
authentication and UI state are held in ``zustand`` stores and the auth
provider. The recommendation views call the engine's recommendation endpoints
(see :doc:`../api-reference`) and render the ranked results with their relevance
scores and explanations.