# Environment Setup

## 1. Clone and Initial Setup

```bash
# Clone the repository
git clone <repository-url>
cd beneficiary-pwa-ui

# Install dependencies
yarn install

# Set up Git hooks (Husky)
yarn prepare
git config core.hooksPath .husky/_
chmod +x .husky/pre-commit
chmod +x .husky/commit-msg
```

## 2. Environment Variables Configuration

Create a `.env` file in the root directory with the following variables:

```bash
# =============================================================================
# UBI Beneficiary PWA UI - Environment Variables Configuration
# =============================================================================
# This file contains all the environment variables required for the application.
# Copy this file to .env and update the values according to your environment.
# 
# IMPORTANT: Never commit the actual .env file to version control!
# =============================================================================

# =============================================================================
# API CONFIGURATION
# =============================================================================
# Base URL for the UBI backend API service
# This is the main API endpoint that handles all backend operations
# including user management, benefit processing, and application handling
VITE_API_BASE_URL=https://your-api-domain.com/api

# Business Application Provider (BAP) identifier for ONDC protocol
# Used in ONDC-compliant benefit discovery and application processes
# This identifies your application in the ONDC network
VITE_API_BASE_ID=your-bap-id

# Business Application Provider (BAP) service URL
# The URL where your BAP service is hosted for ONDC protocol communication
# Used for benefit search, selection, and application initiation
VITE_BAP_URL=https://your-bap-domain.com

# Business Process Provider (BPP) identifier for ONDC protocol
# Identifies the service provider in the ONDC network
# Used when communicating with benefit providers
VITE_BPP_ID=your-bpp-id

# Business Process Provider (BPP) service URL
# The URL where the BPP service is hosted
# Used for benefit provider communication in ONDC protocol
VITE_BPP_URL=https://your-bpp-domain.com

# =============================================================================
# KEYCLOAK AUTHENTICATION CONFIGURATION
# =============================================================================
# Keycloak server base URL for authentication and authorization
# This is the URL where your Keycloak server is hosted
# Used for user authentication, role management, and token validation
VITE_KEYCLOAK_URL=https://your-keycloak-domain.com

# Keycloak realm name for the application
# A realm is a space where you manage objects, including users, credentials, roles, and groups
# Each realm is isolated from other realms and can manage its own set of users
VITE_KEYCLOAK_REALM=your-realm-name

# Keycloak client ID for the beneficiary application
# This identifies your application to the Keycloak server
# Must match the client configuration in your Keycloak realm
VITE_KEYCLOAK_CLIENT_ID=beneficiary-app

# =============================================================================
# DHIWAY SERVICES CONFIGURATION
# =============================================================================
# Dhiway API base URL for document verification services
# Used for DigiLocker integration, Aadhaar verification, and document processing
# This service handles secure document verification and data extraction
VITE_DHIWAY_API_URL=https://your-dhiway-api.com

# API token for authenticating with Dhiway services
# Required for making authenticated requests to Dhiway APIs
# This token should be obtained from your Dhiway service provider
VITE_DHIWAY_TOKEN=your-dhiway-api-token

# Redirect URL for DigiLocker authentication flow
# This URL is used as the callback after DigiLocker authentication
# Must be registered with DigiLocker and match your application's domain
VITE_DHIWAY_REDIRECT_URL=https://your-app-domain.com

# URL for document issuance and verification instance
# Used for document verification workflows and issuance processes
# This endpoint handles document validation and verification operations
VITE_DHIWAY_ISSUANCE_VERIFY_INSTANCE_URL=https://your-issuance-url.com

# =============================================================================
# E-WALLET INTEGRATION CONFIGURATION
# =============================================================================
# Origin URL for e-wallet service communication
# Used for cross-origin communication with embedded e-wallet iframe
# This ensures secure communication between the main app and e-wallet service
VITE_EWALLET_ORIGIN=https://your-ewallet-domain.com

# Iframe source URL for e-wallet integration
# The URL of the e-wallet service that will be embedded in an iframe
# Used for document wallet functionality and secure document storage
VITE_EWALLET_IFRAME_SRC=https://your-ewallet-iframe.com
```

## 3. External Services Setup

### For full functionality of the Beneficiary PWA UI, the following external services must be configured:

* Keycloak Server
  * Used for authentication and authorization.
  * Ensure your realm, client ID, and redirect URIs are configured.
  * [📄 Refer to Keycloak Setup Documentation](https://piramal-swasthya.gitbook.io/uba/toasters/beneficiary-toaster/backend-guide/keycloak-and-hasura-setup-guide#keycloak-setup)
* UBI Backend API
  * Provides beneficiary data management, benefit processing, and application handling.
  * Update VITE\_API\_BASE\_URL and related variables in .env.
  * [📄 Refer to UBI Backend Setup Documentation](https://piramal-swasthya.gitbook.io/uba/toasters/beneficiary-toaster/developer-guide/backend-guide)
* Dhiway Services
  * Required for Aadhaar verification, DigiLocker integration, and document issuance.
  * Configure VITE\_DHIWAY\_API\_URL, VITE\_DHIWAY\_TOKEN, and redirect URLs.

## 4. Notes

* All environment variables must be prefixed with VITE\_ to be accessible in the frontend.
* Never commit .env with real values to version control.
* For production deployment, ensure HTTPS URLs and secure API tokens.
* Verify all external services are accessible before running the UI.