# How The System Works

## 🎯 Overview

The Core Engine System is **additive** - it adds new functionality **without breaking** your existing code.

## 📊 System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Flask Application (app.py)                │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         EXISTING CODE (Still Works!)                │    │
│  │                                                       │    │
│  │  /auth/*          → auth/auth.py                     │    │
│  │  /models/*        → models/models.py                 │    │
│  │  /gateway/*       → gateway/forwarder.py             │    │
│  │  SocketIO         → extensions/extensions.py          │    │
│  │                                                       │    │
│  │  ✅ All existing endpoints work as before!            │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         NEW: Core Engine System                      │    │
│  │                                                       │    │
│  │  /api/v1/loan/apply → core_engine/                   │    │
│  │                       ├── apim/      (API Gateway)   │    │
│  │                       ├── logic/    (Orchestration) │    │
│  │                       └── services/ (Business Logic)│    │
│  │                                                       │    │
│  │  ✅ New endpoints for multi-platform support         │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                          │
                          │
        ┌─────────────────┴─────────────────┐
        │                                     │
   ┌────▼────┐                          ┌────▼────┐
   │ MongoDB │                          │ External│
   │ (db.py) │                          │  APIs   │
   └─────────┘                          └─────────┘
```

## 🔄 Request Flow Comparison

### Existing Endpoint (Still Works!)
```
Client → /auth/v1/POSTloginsendotp
         ↓
    auth/auth.py
         ↓
    MongoDB (via db.py)
         ↓
    Response
```

### New Core Engine Endpoint
```
Client → /api/v1/loan/apply
         ↓
    core_engine/apim/routes/loan.py (Validation, Auth)
         ↓
    core_engine/logic/orchestrators/loan_orchestrator.py (Orchestration)
         ↓
    core_engine/services/loan/loan_service.py (Business Logic)
         ↓
    MongoDB (via db.py - same as before!)
         ↓
    Response
```

## 📁 Folder Structure

```
pebble26/
│
├── 📂 EXISTING FOLDERS (Unchanged)
│   ├── auth/              ✅ Still works!
│   ├── models/            ✅ Still works!
│   ├── gateway/           ✅ Still works!
│   ├── extensions/        ✅ Still works!
│   ├── db.py              ✅ Shared by both systems
│   └── config.py          ✅ Existing config
│
├── 📂 NEW: core_engine/ (Isolated)
│   ├── apim/              🆕 API Gateway Layer
│   ├── logic/             🆕 Orchestration Layer
│   ├── services/          🆕 Service Layer
│   ├── domain/             🆕 Domain Models
│   └── common/            🆕 Common Utilities
│
└── app.py                 🔄 Updated to register both
```

## 🔌 Shared Resources

Both systems share:

1. **Flask App Instance** (`app`)
   - Same Flask application
   - Same CORS settings
   - Same SocketIO instance

2. **MongoDB Connection** (`db.py`)
   - Same database connection
   - Same connection pooling
   - Different collections (no conflicts)

3. **Environment Variables** (`.env`)
   - Both read from same `.env` file
   - Existing code uses: `MONGODB_USER_LIVE`, `JWT_SECRET_KEY`, etc.
   - Core Engine uses: Same variables + some new ones

4. **SocketIO** (`extensions/extensions.py`)
   - Shared SocketIO instance
   - Both can use WebSocket features

## 🚦 What Happens Without .env File?

### Scenario 1: No .env File

```
App Starts: ✅ YES
Existing Endpoints: ✅ WORK (they have their own error handling)
Core Engine Endpoints: ⚠️ MAY FAIL (need .env variables)
Console: ⚠️ Shows warnings
```

### Scenario 2: Partial .env File

```
App Starts: ✅ YES
Existing Endpoints: ✅ WORK
Core Engine Endpoints: ⚠️ PARTIAL (some features may not work)
Console: ⚠️ Shows warnings for missing variables
```

### Scenario 3: Complete .env File

```
App Starts: ✅ YES
Existing Endpoints: ✅ WORK
Core Engine Endpoints: ✅ WORK
Console: ✅ No warnings
```

## 🔍 Database Collections

### Existing Collections (Unchanged)
- `user_master` (from auth module)
- `otp_requests` (from auth module)
- Your existing collections...

### New Collections (Created by Core Engine)
- `loan_requests` (loan applications)
- `idempotency_keys` (idempotency cache with TTL)

**No conflicts!** They use different collection names.

## 🧪 Testing

### Test 1: Existing Endpoint
```bash
curl http://localhost:5001/api/test
# Should work even without .env
```

### Test 2: Existing Auth
```bash
curl -X POST http://localhost:5001/auth/v1/POSTloginsendotp \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+919999999990", "country_code": "+91"}'
# Should work if you have MongoDB configured
```

### Test 3: New Core Engine Endpoint
```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" \
  -d '{"loan_amount": 5000, "purpose": "Business"}'
# Needs .env file with MongoDB and JWT config
```

## ⚙️ Configuration

### Minimum .env for Core Engine
```bash
MONGODB_USER_LIVE=username
MONGODB_PASSWORD_LIVE=password
MONGODB_HOST_LIVE=host
MONGODB_PORT_LIVE=27017
MONGODB_DB_LIVE=database
JWT_SECRET_KEY=secret
```

### Optional (for full features)
```bash
# IMPORTANT: Set your actual core service URL
CORE_SERVICE_URL=your_core_service_url_here
FPL_SERVICE_URL=https://fpl.nanope.ai
```

## 🎯 Key Points

1. ✅ **Existing code is untouched** - All your existing endpoints work
2. ✅ **New code is isolated** - Lives in `core_engine/` folder
3. ✅ **Shared resources** - Both use same MongoDB, Flask app, SocketIO
4. ✅ **No conflicts** - Different collection names, different routes
5. ✅ **Graceful degradation** - App starts even without .env (with warnings)

## 🚀 Getting Started

1. **Create `.env` file** (see `.env.example`)
2. **Install dependencies**: `pip install -r requirements.txt`
3. **Run app**: `python app.py`
4. **Test existing endpoints** - Should work as before
5. **Test new endpoints** - Should work with proper .env

## 📚 Documentation

- **Quick Start**: `QUICK_START.md`
- **Detailed Setup**: `SETUP_GUIDE.md`
- **API Documentation**: `CORE_ENGINE_README.md`
- **Architecture**: `ARCHITECTURE_DESIGN.md`

---

**Bottom Line**: The Core Engine System adds new functionality without breaking anything. Your existing code continues to work exactly as before! 🎉