Inquiry Gateway

Production-grade NestJS + MongoDB unified inquiry gateway for external service providers.

📚 Documentation

• Environment Configuration Guide - Complete guide for configuring providers, authentication, and inquiry routing
• API Documentation - Full API reference with examples, Swagger definitions, and best practices

Architecture

Client → POST /inquiries/person (unified)
       → InquiryController
       → InquiryService
       → ProviderOrchestratorService (strategy + fallback)
       → ProviderFactory → Hamta | Moallem | TejaratNou
       → LegacyApiProvider (shared base for identical APIs)
       → BaseProvider (retry, timeout, logging, error normalization)
       → MongoDB inquiry_logs

Provider vs Authentication Service

The system distinguishes between:

• Inquiry Providers (HAMTA, MOALLEM, TEJARATNOU): Handle actual inquiry requests
• Authentication Services (AMITIS): Provide authentication tokens for providers

Each inquiry type can be configured with its own credentials and authentication method. See Environment Configuration Guide for details.

Design patterns

Pattern	Usage
Strategy	ProviderOrchestratorService selects and executes providers
Factory	ProviderFactory registers and resolves provider instances
Template method	BaseProvider defines execution pipeline; subclasses implement callProvider
Shared adapter	LegacyApiProvider for Hamta/Moallem identical APIs

Project structure

src/
├── main.ts
├── app.module.ts
├── common/          # DTOs, filters, interceptors, helpers, enums
├── config/          # @nestjs/config + inquiry routing
├── auth/            # JWT, RBAC, inquiry access guards
├── users/           # Unified users (ADMIN / USER / SUPER_ADMIN)
├── audit/           # Security audit logs
├── rate-limit/      # Global + per-user throttling
├── logging/         # MongoDB inquiry audit logs
├── providers/       # BaseProvider, LegacyApiProvider, factory, orchestrator
└── inquiry/         # Unified controllers & services

Quick start

cp .env.example .env
# Edit .env with your provider credentials (see Environment Configuration Guide)
npm install
npm run cli:create-super-admin   # interactive — creates SUPER_ADMIN
npm run start:dev

• API: http://localhost:8085
• Swagger: http://localhost:8085/api/docs

Authentication & users

Role	Capabilities
SUPER_ADMIN	Full access; create any user including other super admins
ADMIN	Manage users; all inquiry types
USER	Inquiry access per allowedInquiries

Auth endpoints: POST /auth/login, POST /auth/refresh, POST /auth/logout, GET /auth/profile

User management: POST/GET/PATCH /users, block/unblock, reset password (ADMIN+ only)

# Login
curl -X POST http://localhost:8085/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# Person inquiry (JWT)
curl -X POST http://localhost:8085/inquiries/person \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"nationalCode":"0012345678","birthDate":"1370-05-15"}'

Response envelope (BaseInquiryResponseDto):

{
  "success": true,
  "provider": "HAMTA",
  "trackingCode": "INQ-20250525-A1B2C3D4",
  "message": "Person inquiry completed successfully",
  "data": { "nationalCode": "0012345678", "birthDate": "1370-05-15", "fullName": "..." },
  "duration": 342
}

Provider configuration

Per-inquiry configuration via environment variables:

# Default provider and fallback chain
PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_PROVIDERS=MOALLEM

# Per-inquiry credentials and authentication
HAMTA_PERSON_URL=https://api.example.com/person
HAMTA_PERSON_USERNAME=user123
HAMTA_PERSON_PASSWORD=pass123
HAMTA_PERSON_AUTH_METHOD=AMITIS

# AMITIS authentication service
AMITIS_LOGIN_URL=https://auth.services.centinsur.ir/api/security/login
AMITIS_REFRESH_URL=https://auth.services.centinsur.ir/api/security/RefreshToken

See Environment Configuration Guide for complete configuration options.

Supported inquiry types

Inquiry Type	Providers	Description
PERSON_INQUIRY	HAMTA, MOALLEM	Person information by national code and birth date
REAL_ESTATE_INQUIRY	HAMTA	Real estate ownership information
POSTAL_CODE_INQUIRY	HAMTA, MOALLEM	Address validation by postal code
SHAHKAR_INQUIRY	HAMTA, MOALLEM	Mobile number verification
CIVIL_REGISTRATION_INQUIRY	MOALLEM	Civil registration data
SHEBA_INQUIRY	MOALLEM	Bank account (SHEBA) validation
SAYAH_INQUIRY	TEJARATNOU	Sayah system inquiry

See API Documentation for detailed request/response formats.

Authentication methods

Method	Description	Use Case
AMITIS	Token-based auth via AMITIS service	Most CentInsur APIs
SOAP	Direct SOAP authentication	Legacy XML-based services
OAUTH2	OAuth 2.0 flow	Modern REST APIs
NONE	No authentication required	Public APIs

Token management

• Token refresh: Every 20 minutes automatically
• Token expiration: Daily at 23:59:59 Tehran time
• Retry logic: Automatic retry on HTTP 5xx errors and network failures
• Error handling: Graceful fallback to alternative providers

Adding a new provider

1. Add ProviderName enum value in src/common/enums/provider-name.enum.ts
2. Add provider configuration in src/config/configuration.ts
3. Implement provider (extend BaseProvider or LegacyApiProvider)
4. Register in src/providers/factory/provider.factory.ts
5. Update inquiry routing env vars — no new HTTP routes required

Adding a new inquiry type

1. Add InquiryType enum in src/common/enums/inquiry-type.enum.ts
2. Create request/response DTOs with class-validator in src/inquiry/dto/
3. Add POST /inquiries/<type> in InquiryController
4. Implement service method using ProviderOrchestratorService
5. Configure routing and credentials in .env

Security

• JWT: access + refresh tokens (JWT_SECRET, JWT_REFRESH_SECRET)
• RBAC: @Roles() + RolesGuard
• Inquiry access: allowedInquiries + InquiryAccessGuard (e.g. PERSON_INQUIRY)
• Rate limiting: global throttler + per-user requestLimitPerMinute / requestLimitPerDay
• Audit: audit_logs for login, user lifecycle events
• Request logging: All inquiries logged to MongoDB with masked sensitive data

Error handling

The system provides comprehensive error handling:

• Network errors: Automatic retry with exponential backoff
• HTTP 5xx errors: Automatic retry (configurable attempts)
• Provider failures: Automatic fallback to alternative providers
• Validation errors: Detailed error messages with field-level validation
• Authentication errors: Automatic token refresh and retry

Monitoring & observability

• OpenTelemetry: Distributed tracing support
• Inquiry logs: MongoDB collection with full request/response audit trail
• Audit logs: Security events and user actions
• Performance metrics: Request duration, provider response times
• Error tracking: Normalized error codes and messages

Development

# Development mode with hot reload
npm run start:dev

# Build for production
npm run build

# Run tests
npm run test

# Run tests with coverage
npm run test:cov

# Lint code
npm run lint

# Format code
npm run format

Environment variables

Key environment variables (see .env.example for complete list):

# Application
NODE_ENV=development
PORT=8085
API_PREFIX=api

# Database
MONGODB_URI=mongodb://localhost:27017/inquiry-gateway

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=your-refresh-secret
JWT_REFRESH_EXPIRES_IN=7d

# Rate limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100

# Provider configuration (see Environment Configuration Guide)

License

MIT