esg/docs/ENVIRONMENT_CONFIGURATION.md

# Environment Configuration Guide

This guide explains all environment variables used in the ESG Inquiry Gateway system.

## Table of Contents
- [Application Settings](#application-settings)
- [Database Configuration](#database-configuration)
- [Authentication & Security](#authentication--security)
- [Provider Configuration](#provider-configuration)
- [Inquiry Routing](#inquiry-routing)
- [Provider Behavior Examples](#provider-behavior-examples)

## Application Settings

### Basic Configuration
```env
PORT=8085                    # HTTP server port
NODE_ENV=development         # Environment: development, production, test
```

### OpenTelemetry (Optional)
```env
OTEL_EXPORTER_OTLP_ENDPOINT=http://192.168.10.10:4318
OTEL_SERVICE_NAME=esg
OTEL_NODE_RESOURCE_DETECTORS=env,host,os
```

## Database Configuration

### MongoDB
```env
MONGODB_URI=mongodb://localhost:27017/inquiry-gateway
```

## Authentication & Security

### API Authentication
```env
API_KEY=your-secure-api-key-here              # API key for external clients
JWT_SECRET=change-me-use-long-random-string   # JWT signing secret
JWT_REFRESH_SECRET=change-me-refresh-secret   # JWT refresh token secret
JWT_ACCESS_EXPIRES_IN=15m                     # Access token lifetime
JWT_REFRESH_EXPIRES_IN=7d                     # Refresh token lifetime
JWT_ENABLED=true                              # Enable/disable JWT auth
BCRYPT_SALT_ROUNDS=12                         # Password hashing rounds
```

### Rate Limiting
```env
THROTTLE_TTL=60      # Time window in seconds
THROTTLE_LIMIT=100   # Max requests per window
```

## Provider Configuration

### Understanding Provider Architecture

The system has **two types of components**:

1. **Providers** (Inquiry Handlers): HAMTA, MOALLEM, TEJARATNOU
2. **Authentication Services**: AMITIS (used by HAMTA and MOALLEM)

### AMITIS Authentication Service

AMITIS is **not a provider** - it's an authentication service that provides tokens for HAMTA and MOALLEM.

```env
# AMITIS Configuration
AMITIS_BASE_URL=https://auth.services.centinsur.ir
AMITIS_LOGIN_PATH=/api/security/login
AMITIS_REFRESH_PATH=/api/security/RefreshToken
AMITIS_TOKEN_TIME_ZONE=Asia/Tehran
AMITIS_TIMEOUT=10000
AMITIS_ENABLED=true
```

**Token Management:**
- Tokens refresh every 20 minutes
- Tokens expire daily at 23:59:59 (Tehran time)
- Automatic refresh with fallback to re-login

### Provider Structure

Each provider has:
- **Global settings**: `ENABLED`, `TIMEOUT`, `MAX_RETRIES`
- **Per-inquiry settings**: `URL`, `USERNAME`, `PASSWORD`, `AUTH_METHOD`

#### Format: `PROVIDER_INQUIRY_FIELD`

Example:
```env
HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS
```

### Authentication Methods

Each inquiry can use different authentication:

- **`AMITIS`**: Token-based auth via AMITIS service
- **`SOAP`**: Direct SOAP authentication (credentials in XML)
- **`OAUTH2`**: OAuth2 flow (TejaratNou)
- **`NONE`**: No authentication required

### HAMTA Provider

```env
# Global Settings
HAMTA_ENABLED=true
HAMTA_TIMEOUT=10000
HAMTA_MAX_RETRIES=3

# Person Inquiry (SOAP auth)
HAMTA_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
HAMTA_PERSON_USERNAME=hamta.sabtahval
HAMTA_PERSON_PASSWORD=your-password
HAMTA_PERSON_AUTH_METHOD=SOAP

# Real Estate Inquiry (AMITIS auth)
HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth - no AMITIS)
HAMTA_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
HAMTA_SHAHKAR_USERNAME=Hamta.Shahkar
HAMTA_SHAHKAR_PASSWORD=Y^WzP!8R5Tz
HAMTA_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
HAMTA_SHEBA_URL=https://api.hamta.example.com/api/inquiry/sheba
HAMTA_SHEBA_USERNAME=Hamta.sayah
HAMTA_SHEBA_PASSWORD=J$z07$bg
HAMTA_SHEBA_AUTH_METHOD=AMITIS

# Postal Code Inquiry (AMITIS auth)
HAMTA_POSTAL_CODE_URL=https://api.hamta.example.com/api/inquiry/postalCode
HAMTA_POSTAL_CODE_USERNAME=
HAMTA_POSTAL_CODE_PASSWORD=
HAMTA_POSTAL_CODE_AUTH_METHOD=AMITIS

# Legal Person Inquiry (AMITIS auth)
HAMTA_LEGAL_PERSON_URL=https://api.hamta.example.com/api/inquiry/legalPerson
HAMTA_LEGAL_PERSON_USERNAME=SabtAsnadHamta
HAMTA_LEGAL_PERSON_PASSWORD=HSY1f6?e@kSJ
HAMTA_LEGAL_PERSON_AUTH_METHOD=AMITIS

```

### MOALLEM Provider

```env
# Global Settings
MOALLEM_ENABLED=true
MOALLEM_TIMEOUT=10000
MOALLEM_MAX_RETRIES=2

# Person Inquiry (SOAP auth)
MOALLEM_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_PERSON_USERNAME=mo9635
MOALLEM_PERSON_PASSWORD=ciiws@sabt92
MOALLEM_PERSON_AUTH_METHOD=SOAP

# Postal Code Inquiry (AMITIS auth)
MOALLEM_POSTAL_CODE_URL=https://postalcode.services.centinsur.ir/api/cisb
MOALLEM_POSTAL_CODE_USERNAME=moallem.post
MOALLEM_POSTAL_CODE_PASSWORD=tBUCLGfVJH
MOALLEM_POSTAL_CODE_AUTH_METHOD=AMITIS

# Real Estate Inquiry (AMITIS auth)
MOALLEM_REAL_ESTATE_URL=https://api.moallem.example.com/api/inquiry/realEstate
MOALLEM_REAL_ESTATE_USERNAME=AmlakEskanMoalem
MOALLEM_REAL_ESTATE_PASSWORD=AEM@123456
MOALLEM_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth)
MOALLEM_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
MOALLEM_SHAHKAR_USERNAME=ShkrMoalem1286
MOALLEM_SHAHKAR_PASSWORD=cuYYELt9
MOALLEM_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
MOALLEM_SHEBA_URL=https://sayah.services.centinsur.ir/api/Cisb/TatbighServiceAsync
MOALLEM_SHEBA_USERNAME=moallem.sayah
MOALLEM_SHEBA_PASSWORD=BUCLGfVJH7
MOALLEM_SHEBA_AUTH_METHOD=AMITIS

# Legal Person Inquiry (SOAP auth)
MOALLEM_LEGAL_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_LEGAL_PERSON_USERNAME=
MOALLEM_LEGAL_PERSON_PASSWORD=
MOALLEM_LEGAL_PERSON_AUTH_METHOD=SOAP
```

### PARSIAN Provider

```env
# Global Settings
PARSIAN_ENABLED=true
PARSIAN_TIMEOUT=10000
PARSIAN_MAX_RETRIES=2

# Person Inquiry (SOAP auth)
PARSIAN_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
PARSIAN_PERSON_USERNAME=pa6476
PARSIAN_PERSON_PASSWORD=your-password
PARSIAN_PERSON_AUTH_METHOD=SOAP

# Shahkar Inquiry (X-PACKAGE-API-KEY header)
PARSIAN_SHAHKAR_URL=https://apigateway.parsianinsurance.com/shahkarinqOut
PARSIAN_SHAHKAR_API_KEY=your-package-api-key
PARSIAN_SHAHKAR_AUTH_METHOD=NONE

# Sheba/Sayah Inquiry (AMITIS auth)
PARSIAN_SHEBA_URL=https://sayah.services.centinsur.ir/api/Cisb/TatbighServiceAsync
PARSIAN_SHEBA_USERNAME=parsian.sayah
PARSIAN_SHEBA_PASSWORD=your-password
PARSIAN_SHEBA_AUTH_METHOD=AMITIS

# Car policy inquiry by chassis (SOAP auth)
PARSIAN_POLICY_BY_CHASSIS_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_CHASSIS_USERNAME=pa6476
PARSIAN_POLICY_BY_CHASSIS_PASSWORD=your-password
PARSIAN_POLICY_BY_CHASSIS_AUTH_METHOD=SOAP

# Car policy inquiry by national plate (SOAP auth)
PARSIAN_POLICY_BY_PLATE_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_PLATE_USERNAME=pa6476
PARSIAN_POLICY_BY_PLATE_PASSWORD=your-password
PARSIAN_POLICY_BY_PLATE_AUTH_METHOD=SOAP

# Car policy inquiry by national code (SOAP auth)
PARSIAN_POLICY_BY_NATIONAL_CODE_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_NATIONAL_CODE_USERNAME=pa6476
PARSIAN_POLICY_BY_NATIONAL_CODE_PASSWORD=your-password
PARSIAN_POLICY_BY_NATIONAL_CODE_AUTH_METHOD=SOAP
```

### TEJARATNOU Provider

```env
# Global Settings
TEJARATNOU_ENABLED=true
TEJARATNOU_TIMEOUT=15000
TEJARATNOU_MAX_RETRIES=2

# OAuth2 Authentication
TEJARATNOU_AUTH_URL=https://accounts.tejaratnoins.ir
TEJARATNOU_CLIENT_ID=api-gateway
TEJARATNOU_CLIENT_SECRET=hkld@ork123T
TEJARATNOU_USERNAME=thirdparty-silcogroup
TEJARATNOU_PASSWORD=FDHG87sdf787l764iuo

# Person Inquiry
TEJARATNOU_PERSON_URL=https://gateway.tejaratnoins.ir/api/inquiry/person
TEJARATNOU_PERSON_AUTH_METHOD=OAUTH2
```

## Inquiry Routing

Routing determines which provider handles each inquiry type and whether to use fallbacks.

### Format
```env
{INQUIRY_TYPE}_DEFAULT_PROVIDER=PROVIDER_NAME
{INQUIRY_TYPE}_FALLBACK_ENABLED=true|false
{INQUIRY_TYPE}_FALLBACK_PROVIDERS=PROVIDER1,PROVIDER2
```

### Available Inquiry Types
- `PERSON` - Person/Civil registration inquiry
- `REAL_ESTATE` - Real estate/property inquiry
- `SHAHKAR` - Mobile number verification
- `POSTAL_CODE` - Postal code lookup
- `SHEBA` - Bank account verification
- `LEGAL_PERSON` - Legal entity inquiry
- `CAR_PLATE` - Vehicle plate inquiry

### Example Configurations

#### Person Inquiry (Single Provider)
```env
PERSON_DEFAULT_PROVIDER=PARSIAN
PERSON_FALLBACK_ENABLED=false
PERSON_FALLBACK_PROVIDERS=
```
**Behavior**: Only PARSIAN is used. If it fails, request fails.

#### Person Inquiry (With Fallback)
```env
PERSON_DEFAULT_PROVIDER=PARSIAN
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,TEJARATNOU
```
**Behavior**: 
1. Try PARSIAN first
2. If fails, try HAMTA
3. If fails, try TEJARATNOU
4. If all fail, return error

#### Real Estate Inquiry
```env
REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false
REAL_ESTATE_FALLBACK_PROVIDERS=
```

#### Shahkar Inquiry
```env
SHAHKAR_DEFAULT_PROVIDER=PARSIAN
SHAHKAR_FALLBACK_ENABLED=false
SHAHKAR_FALLBACK_PROVIDERS=
```

#### Sheba/Sayah Inquiry
```env
SHEBA_DEFAULT_PROVIDER=PARSIAN
SHEBA_FALLBACK_ENABLED=false
SHEBA_FALLBACK_PROVIDERS=
```

## Provider Behavior Examples

### Scenario 1: All Providers Enabled

```env
HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false
```

**Result**: Only TEJARATNOU is used for person inquiries, even though others are enabled.

### Scenario 2: Default Provider Disabled

```env
HAMTA_ENABLED=false
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=TEJARATNOU,MOALLEM
```

**Result**: 
- HAMTA is skipped (disabled)
- TEJARATNOU is tried first (first enabled fallback)
- MOALLEM is tried if TEJARATNOU fails

### Scenario 3: No Providers Available

```env
HAMTA_ENABLED=false
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

PERSON_DEFAULT_PROVIDER=TEJARATNOU
```

**Result**: API returns error:
```json
{
  "success": false,
  "provider": "GATEWAY",
  "message": "No enabled providers configured for PERSON",
  "error": {
    "code": "NO_PROVIDERS",
    "message": "No enabled providers configured for PERSON"
  }
}
```

### Scenario 4: All Providers Fail

```env
HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM
```

**Result**: If all three providers fail, API returns:
```json
{
  "success": false,
  "provider": "GATEWAY",
  "message": "TEJARATNOU failed: timeout; HAMTA failed: auth error; MOALLEM failed: network error",
  "error": {
    "code": "ALL_PROVIDERS_FAILED",
    "message": "Combined error messages from all providers"
  }
}
```

## Production Recommendations

### High Availability Setup
```env
# Enable all providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

# Use fallbacks for critical inquiries
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=true
REAL_ESTATE_FALLBACK_PROVIDERS=MOALLEM
```

### Performance-Optimized Setup
```env
# Enable only primary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=true

# No fallbacks for faster response
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false
```

### Cost-Optimized Setup
```env
# Enable only necessary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

# Single provider per inquiry type
PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false
```

## Security Best Practices

1. **Never commit `.env` to git** - Use `.env.example` as template
2. **Rotate credentials regularly** - Update passwords every 90 days
3. **Use strong secrets** - Generate random strings for JWT secrets
4. **Limit API key distribution** - One key per client application
5. **Enable rate limiting** - Protect against abuse
6. **Monitor failed authentications** - Alert on repeated failures
7. **Use HTTPS in production** - Never send credentials over HTTP

## Troubleshooting

### Provider Not Working

1. Check if provider is enabled: `{PROVIDER}_ENABLED=true`
2. Verify credentials are correct
3. Check if inquiry type is configured for that provider
4. Verify network connectivity to provider URL
5. Check logs for authentication errors

### No Providers Available Error

1. Verify at least one provider is enabled
2. Check `{INQUIRY}_DEFAULT_PROVIDER` is set correctly
3. Ensure the default provider supports the inquiry type
4. Verify provider credentials are configured

### Authentication Failures

1. Check AMITIS service is enabled and reachable
2. Verify credentials in `{PROVIDER}_{INQUIRY}_USERNAME/PASSWORD`
3. Check if tokens are expiring (should auto-refresh)
4. Verify system time is correct (affects token expiration)

### Performance Issues

1. Reduce `MAX_RETRIES` for faster failures
2. Decrease `TIMEOUT` values
3. Disable fallbacks if not needed
4. Enable only required providers
5. Check network latency to provider services

## Migration from Old Format

### Old Format (Deprecated)
```env
AMITIS_HAMTA_PERSON_USERNAME=pa6476
AMITIS_HAMTA_PERSON_PASSWORD=ciiws@sabt92
```

### New Format (Current)
```env
PARSIAN_PERSON_USERNAME=pa6476
PARSIAN_PERSON_PASSWORD=your-password
PARSIAN_PERSON_AUTH_METHOD=SOAP
```

**Key Changes:**
- Removed `AMITIS_` prefix from provider credentials
- Added `AUTH_METHOD` to specify authentication type
- Added per-inquiry `URL` configuration
- AMITIS is now a separate authentication service, not a provider