# Setup Guide - Core Engine System

## How It Works

The Core Engine System is designed to work **alongside** your existing codebase. Here's how everything fits together:

### Architecture Overview

```
┌─────────────────────────────────────────────────┐
│              Flask Application (app.py)          │
│  ┌──────────────────────────────────────────┐   │
│  │  Existing Modules (Still Work!)          │   │
│  │  - auth/ (authentication)                │   │
│  │  - models/ (data models)                  │   │
│  │  - gateway/ (API gateway forwarder)       │   │
│  │  - extensions/ (SocketIO, etc.)          │   │
│  └──────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────┐   │
│  │  NEW: Core Engine System                  │   │
│  │  - core_engine/apim/ (API Gateway Layer)  │   │
│  │  - core_engine/logic/ (Orchestration)     │   │
│  │  - core_engine/services/ (Business Logic)│   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
```

### Key Points

1. **Existing Code Still Works**: Your `auth/`, `models/`, `gateway/`, and `extensions/` folders are untouched and continue to work as before.

2. **New Code is Isolated**: The Core Engine System lives in `core_engine/` and doesn't interfere with existing code.

3. **Shared Resources**: Both systems share:
   - Same Flask app instance
   - Same MongoDB database (via `db.py`)
   - Same environment variables
   - Same SocketIO instance

## Setup Steps

### 1. Create .env File

Copy the example file and fill in your values:

```bash
# Copy the example file
cp .env.example .env

# Or create manually
```

**Minimum Required Variables** (for Core Engine to work):
```bash
MONGODB_USER_LIVE=your_username
MONGODB_PASSWORD_LIVE=your_password
MONGODB_HOST_LIVE=your_host
MONGODB_PORT_LIVE=27017
MONGODB_DB_LIVE=your_database
JWT_SECRET_KEY=your_secret_key
```

**Optional Variables** (for full functionality):
```bash
# IMPORTANT: Set your actual core service URL
CORE_SERVICE_URL=your_core_service_url_here
FPL_SERVICE_URL=https://fpl.nanope.ai
AWS_REGION=us-west-2
SNS_ACCESS_KEY=your_key
SNS_SECRET_ACCESS_KEY=your_secret
```

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

**New dependencies added**:
- `pydantic>=1.10.0` (for validation)
- `pytest` (for testing)

### 3. Verify Setup

```bash
# Test if imports work
python -c "from core_engine.common.config import Config; print('Config OK')"

# Test if app starts (will show config errors if any)
python app.py
```

## How Requests Flow

### Existing Endpoints (Still Work!)

```
POST /auth/v1/POSTloginsendotp     → auth/auth.py
GET  /models/...                   → models/models.py
POST /gateway/kyc/...               → gateway/forwarder.py
```

### New Core Engine Endpoints

```
POST /api/v1/loan/apply            → core_engine/apim/routes/loan.py
                                     → core_engine/logic/orchestrators/loan_orchestrator.py
                                     → core_engine/services/loan/loan_service.py
```

## Database Collections

The Core Engine System will create/use these MongoDB collections:

- `loan_requests` - Loan applications
- `idempotency_keys` - Idempotency key cache (with TTL)

Your existing collections remain unchanged.

## Configuration Validation

The app will validate configuration on startup. If variables are missing, you'll see:

```
Configuration error: Missing required configuration: MONGODB_USER_LIVE, JWT_SECRET_KEY
```

**This won't crash the app** - it just prints a warning. The app will still start, but Core Engine endpoints may fail until configuration is complete.

## Testing the System

### 1. Test Existing Endpoints (Should Still Work)

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

### 2. Test New Core Engine Endpoint

```bash
# First, get a JWT token from existing auth endpoint
# Then test loan application
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" \
  -d '{
    "loan_amount": 5000,
    "purpose": "Business",
    "term_days": 30
  }'
```

## Troubleshooting

### Issue: "ModuleNotFoundError: No module named 'core_engine'"

**Solution**: Make sure you're running from the project root directory:
```bash
cd C:\Users\1GEN\OneDrive\Documents\GitHub\pebble26
python app.py
```

### Issue: "Configuration error: Missing required configuration"

**Solution**: Create `.env` file with required variables (see step 1 above).

### Issue: "MongoDB connection error"

**Solution**: 
1. Verify MongoDB is running
2. Check `.env` file has correct MongoDB credentials
3. Test connection: `mongodb://user:password@host:port/`

### Issue: "JWT_SECRET_KEY not configured"

**Solution**: Add `JWT_SECRET_KEY=your_secret_key` to `.env` file.

### Issue: Existing endpoints not working

**Solution**: They should still work! The Core Engine doesn't modify existing code. If they're broken, check:
1. Are you running from the correct directory?
2. Are all existing dependencies installed?
3. Check Flask logs for errors

## What Happens Without .env File?

The app will:
1. ✅ Still start (Flask app initializes)
2. ✅ Existing endpoints work (they use their own config)
3. ⚠️ Core Engine endpoints may fail (they need .env variables)
4. ⚠️ You'll see configuration warnings in console

## Environment Variable Priority

1. **System environment variables** (highest priority)
2. **`.env` file** (loaded by `python-dotenv`)
3. **Default values** (in `core_engine/common/config.py`)

## Next Steps

1. ✅ Create `.env` file with your MongoDB and JWT credentials
2. ✅ Test existing endpoints to ensure they still work
3. ✅ Test new Core Engine endpoint: `/api/v1/loan/apply`
4. ✅ Check logs for any warnings or errors

## Support

- See `CORE_ENGINE_README.md` for detailed API documentation
- See `ARCHITECTURE_DESIGN.md` for architecture details
- Check application logs for trace IDs to debug issues

---

**Remember**: The Core Engine System is **additive** - it adds new functionality without breaking existing code!