# Core Engine System - Implementation Guide

## Overview

This document provides instructions for running and using the Core Engine System, a scalable 3-layer architecture supporting multiple client platforms (NOW, Saathi).

## Architecture

See [ARCHITECTURE_DESIGN.md](./ARCHITECTURE_DESIGN.md) for detailed architecture documentation.

## Project Structure

```
pebble26/
├── core_engine/            # Core Engine System
│   ├── apim/              # APIM Layer (API Gateway)
│   │   ├── middleware/    # Auth, platform detection, tracing
│   │   ├── routes/        # Route handlers
│   │   └── validators/    # Request validators
│   ├── logic/             # Logic Layer (Orchestration)
│   │   ├── orchestrators/ # Business workflow orchestrators
│   │   ├── mappers/       # Platform-to-canonical mappers
│   │   └── clients/       # Service layer clients
│   ├── services/          # Service Layer (Backend Modules)
│   │   ├── loan/          # Loan service module
│   │   ├── score/         # Score service module
│   │   └── idempotency/   # Idempotency service
│   ├── domain/            # Shared Domain Models
│   │   ├── models/        # Canonical domain models
│   │   ├── exceptions.py  # Domain exceptions
│   │   └── constants.py  # Domain constants
│   ├── common/            # Common Utilities
│   │   ├── logger.py     # Structured logging
│   │   ├── errors.py     # Error handling
│   │   ├── config.py     # Configuration
│   │   ├── trace.py      # Trace ID management
│   │   └── retry.py      # Retry policies
│   └── tests/             # Tests
│       ├── unit/          # Unit tests
│       └── integration/   # Integration tests
├── auth/                   # Existing auth module
├── models/                 # Existing models
├── gateway/                # Existing gateway
└── app.py                  # Main application
```

## Prerequisites

1. **Python 3.8+**
2. **MongoDB** (running and accessible)
3. **Environment Variables** (see `.env` file)

## Environment Variables

Create a `.env` file in the project root:

```bash
# MongoDB
MONGODB_USER_LIVE=your_mongodb_user
MONGODB_PASSWORD_LIVE=your_mongodb_password
MONGODB_HOST_LIVE=your_mongodb_host
MONGODB_PORT_LIVE=27017
MONGODB_DB_LIVE=your_database_name

# JWT
JWT_SECRET_KEY=your_jwt_secret_key

# AWS (for SNS/OTP)
AWS_REGION=us-west-2
SNS_ACCESS_KEY=your_aws_access_key
SNS_SECRET_ACCESS_KEY=your_aws_secret_key

# External Services
# IMPORTANT: Set your actual core service URL here
CORE_SERVICE_URL=your_core_service_url_here
FPL_SERVICE_URL=https://fpl.nanope.ai

# Optional Configuration
MAX_RETRIES=3
RETRY_BACKOFF_BASE=1.0
SERVICE_TIMEOUT=30
CACHE_TTL=300
IDEMPOTENCY_TTL=86400
```

## Installation

1. **Clone the repository** (if not already done)

2. **Install dependencies**:
```bash
pip install -r requirements.txt
```

3. **Verify configuration**:
```bash
python -c "from common.config import Config; Config.validate()"
```

## Running the Application

### Development Mode

```bash
python app.py
```

The server will start on `http://localhost:5001`

### Production Mode

```bash
gunicorn -w 4 -b 0.0.0.0:5001 app:app
```

## API Endpoints

### Health Check

```bash
curl http://localhost:5001/health
```

### Loan Application (NOW Platform)

```bash
curl -X POST http://localhost:5001/api/v1/loan/apply \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "X-Platform: NOW" \
  -H "Idempotency-Key: req-12345" \
  -d '{
    "loan_amount": 5000,
    "purpose": "Business",
    "term_days": 30
  }'
```

**Response (NOW Format)**:
```json
{
  "success": true,
  "data": {
    "loan_id": "692e6db1cc7c914386725a39",
    "status": "APPROVED",
    "loan_amount": 5000,
    "approved_amount": 5000,
    "message": "Loan application approved",
    "n_score": 45.0
  },
  "trace_id": "abc-123-def-456"
}
```

### Loan Application (Saathi Platform)

```bash
curl -X POST http://localhost:5001/api/v1/loan/apply \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "X-Platform: Saathi" \
  -H "Idempotency-Key: req-12345" \
  -d '{
    "amount": 5000,
    "loan_purpose": "Business Expansion",
    "loan_term": 30
  }'
```

**Response (Saathi Format)**:
```json
{
  "success": true,
  "data": {
    "loan_id": "692e6db1cc7c914386725a39",
    "status": "APPROVED",
    "amount": 5000,
    "approved_amount": 5000,
    "message": "Loan application approved",
    "n_score": 45.0
  },
  "trace_id": "abc-123-def-456"
}
```

## Getting a JWT Token

To get a JWT token for testing, use the existing auth endpoints:

```bash
# Send OTP
curl -X POST http://localhost:5001/auth/v1/POSTloginsendotp \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919999999990",
    "country_code": "+91"
  }'

# Verify OTP and get token
curl -X POST http://localhost:5001/auth/v1/POSTloginverifyotp \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "uuid-from-previous-response",
    "otp": "123456"
  }'
```

The response will include a token that can be used in the `x-access-token` header.

## Request Flow Example

### 1. NOW Platform Request
```json
{
  "loan_amount": 5000,
  "purpose": "Business",
  "term_days": 30
}
```

### 2. APIM Layer Processing
- Validates request schema
- Authenticates JWT token
- Detects platform: "NOW"
- Generates trace_id
- Routes to Logic Layer

### 3. Logic Layer Processing
- Maps NOW request to canonical:
  ```json
  {
    "user_id": "123",
    "amount": 5000,
    "purpose": "Business",
    "platform": "NOW",
    "trace_id": "abc-123"
  }
  ```
- Orchestrates workflow:
  - Gets N-Score from Score Service
  - Validates eligibility
  - Calls Loan Service
- Maps canonical response to NOW format

### 4. Service Layer Processing
- Loan Service creates loan record in MongoDB
- Returns canonical response

### 5. Response to Client
- Logic Layer maps to NOW format
- APIM Layer adds trace_id header
- Returns formatted response

## Idempotency

The API supports idempotency keys to prevent duplicate processing:

1. **Send request with `Idempotency-Key` header**:
   ```bash
   -H "Idempotency-Key: unique-key-123"
   ```

2. **First request**: Processed normally, response cached

3. **Subsequent requests with same key**: Returns cached response

4. **Key format**: Any string (recommended: UUID or client-generated unique ID)

5. **TTL**: Idempotency keys expire after 24 hours (configurable)

## Error Handling

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Loan amount must be between 1000 and 100000",
    "details": {}
  },
  "trace_id": "abc-123-def-456",
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### Common Error Codes

- `VALIDATION_ERROR` (400): Request validation failed
- `AUTHENTICATION_ERROR` (401): Authentication failed
- `AUTHORIZATION_ERROR` (403): Authorization failed
- `BUSINESS_RULE_ERROR` (400): Business rule violation
- `NOT_FOUND` (404): Resource not found
- `EXTERNAL_SERVICE_ERROR` (502): External service failure
- `INTERNAL_ERROR` (500): Internal server error

## Logging

All requests are logged with structured JSON format:

```json
{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "INFO",
  "trace_id": "abc-123-def-456",
  "user_id": "123",
  "platform": "NOW",
  "endpoint": "/api/v1/loan/apply",
  "message": "Request received"
}
```

## Testing

### Run Unit Tests

```bash
pytest tests/unit/ -v
```

### Run Integration Tests

```bash
pytest tests/integration/ -v
```

### Run All Tests

```bash
pytest tests/ -v
```

## Adding New Endpoints

### 1. Create Validator (APIM Layer)

```python
# apim/validators/new_feature.py
from pydantic import BaseModel

class NOWNewFeatureRequest(BaseModel):
    field1: str
    field2: int
```

### 2. Create Route (APIM Layer)

```python
# apim/routes/new_feature.py
from flask import Blueprint, request, g
from apim.middleware.auth import require_auth
from logic.orchestrators.new_feature_orchestrator import NewFeatureOrchestrator

new_feature_bp = Blueprint('new_feature', __name__)

@new_feature_bp.route('/v1/new-feature', methods=['POST'])
@require_auth
def new_feature():
    # Implementation
    pass
```

### 3. Create Orchestrator (Logic Layer)

```python
# logic/orchestrators/new_feature_orchestrator.py
class NewFeatureOrchestrator:
    def process(self, request_data, platform, user_id, trace_id):
        # Orchestration logic
        pass
```

### 4. Create Service (Service Layer)

```python
# services/new_feature/new_feature_service.py
class NewFeatureService:
    def process(self, canonical_request):
        # Business logic
        pass
```

### 5. Register Blueprint

```python
# app.py
from apim.routes.new_feature import new_feature_bp
app.register_blueprint(new_feature_bp, url_prefix='/api')
```

## Platform Detection

Platform is detected in the following order:

1. **X-Platform header**: `X-Platform: NOW` or `X-Platform: Saathi`
2. **User-Agent**: Contains "now" or "saathi"
3. **URL path**: Contains "/now/" or "/saathi/"
4. **Default**: Unknown platform

## Versioning

API versioning is supported via URL path:

- `/api/v1/loan/apply` - Version 1
- `/api/v2/loan/apply` - Version 2 (future)

## Monitoring

### Health Check

```bash
curl http://localhost:5001/health
```

### Logs

Check application logs for:
- Request/response logging
- Error logging
- Performance metrics (trace_id for correlation)

## Troubleshooting

### Common Issues

1. **MongoDB Connection Error**
   - Verify MongoDB is running
   - Check connection string in `.env`
   - Verify network connectivity

2. **JWT Authentication Error**
   - Verify `JWT_SECRET_KEY` is set
   - Check token format and expiration

3. **External Service Errors**
   - Check `CORE_SERVICE_URL` and `FPL_SERVICE_URL`
   - Verify network connectivity
   - Check service status

4. **Validation Errors**
   - Check request format matches platform schema
   - Verify required fields are present

## Support

For issues or questions:
- Check logs with `trace_id` for request correlation
- Review [ARCHITECTURE_DESIGN.md](./ARCHITECTURE_DESIGN.md)
- Contact development team

---

**Last Updated**: January 2025