# RMBXchange Project Settings Documentation

## Overview
This document provides a comprehensive guide to all configurable settings in the RMBXchange platform. Settings are managed through the admin dashboard and stored in the `settings` table.

---

## Table of Contents
1. [Accessing Settings](#accessing-settings)
2. [Payment Gateway Settings](#payment-gateway-settings)
3. [SMS Provider Settings](#sms-provider-settings)
4. [Email Configuration](#email-configuration)
5. [Exchange Rate Settings](#exchange-rate-settings)
6. [Wallet System Settings](#wallet-system-settings)
7. [Authentication Settings](#authentication-settings)
8. [Live Chat Integration](#live-chat-integration)
9. [Admin Notification Settings](#admin-notification-settings)
10. [Database Migration](#database-migration)

---

## Accessing Settings

**Admin Dashboard URL:** `/admin/settings`

**Requirements:**
- Admin account with `is_admin = 1`
- Logged in to the system

**Navigation:**
1. Log in to admin dashboard at `/admin/dashboard`
2. Click "Settings" in the top navigation
3. Configure settings and click "Save Settings"

---

## Payment Gateway Settings

### Hubtel Payment Gateway

**Purpose:** Process GHS payments for wallet top-ups and exchanges

**Required Settings:**

| Setting Key | Description | Example Value |
|------------|-------------|---------------|
| `hubtel_client_id` | Hubtel API Client ID | `your-client-id` |
| `hubtel_client_secret` | Hubtel API Client Secret | `your-client-secret` |
| `hubtel_merchant_account` | Merchant account number | `HM12345` |

**Setup Instructions:**
1. Register at [Hubtel Developer Portal](https://developers.hubtel.com)
2. Create a new application
3. Copy Client ID and Client Secret
4. Add merchant account number
5. Enter credentials in admin settings

**Documentation:** See `HUBTEL_INTEGRATION.md` for detailed setup

---

## SMS Provider Settings

### Overview
RMBXchange supports three SMS providers with automatic fallback functionality.

### Provider Selection

**Setting Key:** `sms_provider`

**Available Options:**
- `bulksms_ghana` - BulkSMS Ghana
- `sms_online_gh` - SMS Online GH
- `mnotify` - mNotify API

### 1. BulkSMS Ghana

**Required Settings:**

| Setting Key | Description |
|------------|-------------|
| `bulksms_api_key` | BulkSMS Ghana API Key |
| `bulksms_sender_id` | Sender ID (e.g., "RMBXchange") |

**API Endpoint:** `https://api.bulksmsgh.com/v1/sms/send`

**Setup:**
1. Register at BulkSMS Ghana
2. Purchase SMS credits
3. Generate API key
4. Register sender ID
5. Enter credentials in settings

### 2. SMS Online GH

**Required Settings:**

| Setting Key | Description |
|------------|-------------|
| `sms_online_api_key` | SMS Online GH API Key |
| `sms_online_sender_id` | Sender ID |

**API Endpoint:** `https://api.smsonlinegh.com/v4/message/sms/send`

**Setup:**
1. Register at SMS Online GH
2. Top up account
3. Get API key from dashboard
4. Configure sender ID
5. Enter credentials in settings

### 3. mNotify API

**Required Settings:**

| Setting Key | Description |
|------------|-------------|
| `mnotify_api_key` | mNotify API Key |
| `mnotify_sender_id` | Sender ID |

**API Endpoint:** `https://api.mnotify.com/api/sms/quick`

**Success Response Code:** `2000`

**Setup:**
1. Register at [mNotify](https://mnotify.com)
2. Purchase SMS credits
3. Generate API key
4. Register sender ID
5. Enter credentials in settings

**Documentation:** See `MNOTIFY_INTEGRATION.md` for detailed setup

### SMS Fallback System

**How It Works:**
1. System attempts to send via primary provider
2. If primary fails, automatically tries email notification
3. Admin receives alert about SMS failure
4. System logs all attempts for debugging

**Documentation:** See `SMS_FALLBACK_SYSTEM.md`

---

## Email Configuration

### SMTP Settings

**Required Settings:**

| Setting Key | Description | Example |
|------------|-------------|---------|
| `smtp_host` | SMTP server hostname | `smtp.gmail.com` |
| `smtp_port` | SMTP port | `587` |
| `smtp_username` | SMTP username/email | `your-email@gmail.com` |
| `smtp_password` | SMTP password/app password | `your-app-password` |
| `smtp_encryption` | Encryption type | `tls` or `ssl` |
| `smtp_from_address` | From email address | `noreply@rmbxchange.com` |
| `smtp_from_name` | From name | `RMBXchange` |

### Email Templates

**Available Templates:**
- Welcome email (`emails.welcome`)
- Order completed (`emails.order-completed`)
- Wallet top-up (`emails.wallet-topup`)
- Withdrawal submitted (`emails.withdrawal-submitted`)
- Withdrawal approved (`emails.withdrawal-approved`)
- Withdrawal rejected (`emails.withdrawal-rejected`)
- SMS failure alert (`emails.sms-failure-alert`)
- Admin message (`emails.admin-message`)

**Documentation:** See `EMAIL_TEMPLATES.md`

---

## Exchange Rate Settings

### Configuration

**Setting Keys:**

| Setting Key | Description | Default |
|------------|-------------|---------|
| `exchange_rate` | GHS to CNY rate | `0.57` |
| `exchange_rate_source` | Rate source | `manual` or `api` |
| `rate_update_frequency` | Update frequency (minutes) | `60` |

### Rate Display

**Conversion Logic:**
- **Stored Rate:** GHS to CNY (e.g., 0.57)
- **Display Rate:** CNY to GHS (1 / 0.57 = 1.7857)

**Example:**
```
Stored: 1 GHS = 0.57 CNY
Display: 1 CNY = 1.7857 GHS
```

### Manual Rate Updates

**Admin Dashboard:**
1. Go to Settings
2. Update "Exchange Rate (GHS to CNY)"
3. Save settings
4. Rate updates immediately across platform

### Automated Rate Updates

**Command:** `php artisan exchange:check-rate`

**Schedule:** Can be added to Laravel scheduler

**Documentation:** See `EXCHANGE_RATE_SYSTEM.md`

---

## Wallet System Settings

### Wallet Features

**Setting Keys:**

| Setting Key | Description | Type | Default |
|------------|-------------|------|---------|
| `wallet_enabled` | Enable/disable wallet | Boolean | `true` |
| `wallet_topup_enabled` | Enable top-ups | Boolean | `true` |
| `wallet_withdrawal_enabled` | Enable withdrawals | Boolean | `true` |
| `min_topup_amount` | Minimum top-up (GHS) | Number | `10` |
| `max_topup_amount` | Maximum top-up (GHS) | Number | `10000` |
| `min_withdrawal_amount` | Minimum withdrawal (CNY) | Number | `50` |
| `max_withdrawal_amount` | Maximum withdrawal (CNY) | Number | `50000` |

### Wallet Workflow

**Top-Up Process:**
1. User enters GHS amount
2. System converts to CNY using exchange rate
3. Payment processed via Hubtel
4. CNY credited to wallet on success

**Withdrawal Process:**
1. User requests CNY withdrawal
2. Admin reviews and approves/rejects
3. User receives notification
4. CNY deducted from wallet on approval

**Documentation:** See `WALLET_SYSTEM.md`

---

## Authentication Settings

### Google OAuth

**Setting Keys:**

| Setting Key | Description |
|------------|-------------|
| `google_oauth_enabled` | Enable Google Sign-In |
| `google_client_id` | Google OAuth Client ID |
| `google_client_secret` | Google OAuth Client Secret |
| `google_redirect_uri` | OAuth redirect URL |

**Setup:**
1. Create project in Google Cloud Console
2. Enable Google+ API
3. Create OAuth 2.0 credentials
4. Add authorized redirect URI: `https://yourdomain.com/auth/google/callback`
5. Enter credentials in settings

**Documentation:** See `GOOGLE_OAUTH_SETUP.md`

### Password Reset

**Setting Keys:**

| Setting Key | Description | Default |
|------------|-------------|---------|
| `password_reset_enabled` | Enable password reset | `true` |
| `reset_token_expiry` | Token expiry (minutes) | `60` |

**Documentation:** See `PASSWORD_RESET_SYSTEM.md`

---

## Live Chat Integration

### Tawk.to Widget

**Setting Keys:**

| Setting Key | Description |
|------------|-------------|
| `tawk_enabled` | Enable Tawk.to chat |
| `tawk_property_id` | Tawk.to Property ID |
| `tawk_widget_id` | Tawk.to Widget ID |

**Setup:**
1. Register at [Tawk.to](https://www.tawk.to)
2. Create a property
3. Get Property ID and Widget ID from admin panel
4. Enter IDs in settings
5. Widget appears on all pages when enabled

**Testing Command:**
```bash
php artisan tawk:check-config
```

**Documentation:** See `TAWK_TO_SETUP_COMPLETE.md`

---

## Admin Notification Settings

### SMS Alerts for Admins

**Setting Keys:**

| Setting Key | Description |
|------------|-------------|
| `admin_sms_enabled` | Enable admin SMS alerts |
| `admin_phone_number` | Admin phone number |

**Notifications Sent:**
- New withdrawal requests
- Large transactions (>1000 GHS)
- System errors
- SMS delivery failures

**Documentation:** See `ADMIN_SMS_ALERTS.md`

### Email Alerts

**Setting Keys:**

| Setting Key | Description |
|------------|-------------|
| `admin_email_enabled` | Enable admin email alerts |
| `admin_email` | Admin email address |

**Notifications Sent:**
- New user registrations
- Withdrawal requests
- Payment confirmations
- System errors

---

## Database Migration

### SQLite to MySQL Migration

**Command:**
```bash
php artisan db:migrate-to-mysql
```

**What It Does:**
1. Connects to both SQLite and MySQL
2. Runs fresh migrations on MySQL
3. Copies all data from SQLite to MySQL
4. Preserves all settings, users, and records

**Tables Migrated:**
- users
- orders
- settings
- notifications
- wallet_transactions
- pages
- cache

**Prerequisites:**
1. MySQL server running
2. Database created: `CREATE DATABASE buy_rmb;`
3. `.env` configured for MySQL
4. SQLite file exists at `database/database.sqlite`

**Configuration:**

Update `.env` file:
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=buy_rmb
DB_USERNAME=root
DB_PASSWORD=your_password
```

**Post-Migration:**
```bash
php artisan config:clear
php artisan cache:clear
```

---

## Settings Model Usage

### Retrieving Settings

**In Controllers:**
```php
use App\Models\Setting;

// Get single setting
$rate = Setting::get('exchange_rate', 0.57);

// Get boolean setting
$walletEnabled = Setting::get('wallet_enabled', true);

// Check if setting exists
if (Setting::has('tawk_enabled')) {
    // Setting exists
}
```

**In Blade Templates:**
```blade
@php
    $rate = \App\Models\Setting::get('exchange_rate', 0.57);
@endphp

<p>Current Rate: {{ $rate }}</p>
```

### Updating Settings

**Via Admin Dashboard:**
- Navigate to `/admin/settings`
- Update values in form
- Click "Save Settings"

**Programmatically:**
```php
use App\Models\Setting;

// Set single value
Setting::set('exchange_rate', 0.58);

// Set multiple values
Setting::setMany([
    'exchange_rate' => 0.58,
    'wallet_enabled' => true,
    'min_topup_amount' => 20
]);
```

---

## Environment Variables

### Critical .env Settings

```env
# Application
APP_NAME="RMBXchange"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=buy_rmb
DB_USERNAME=root
DB_PASSWORD=your_password

# Mail (can be overridden by admin settings)
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@rmbxchange.com
MAIL_FROM_NAME="${APP_NAME}"

# Session
SESSION_DRIVER=database
SESSION_LIFETIME=120

# Cache
CACHE_DRIVER=database
```

---

## Troubleshooting

### Settings Not Saving

**Check:**
1. Admin user logged in (`is_admin = 1`)
2. Database connection working
3. `settings` table exists
4. No validation errors in form

**Solution:**
```bash
php artisan migrate
php artisan config:clear
```

### SMS Not Sending

**Check:**
1. SMS provider selected in settings
2. API credentials correct
3. Sender ID registered
4. Sufficient SMS credits
5. Phone number format correct (+233...)

**Debug:**
```bash
# Check SMS configuration
php artisan tinker
>>> \App\Models\Setting::get('sms_provider')
>>> \App\Models\Setting::get('mnotify_api_key')
```

**Documentation:** See `SMS_TROUBLESHOOTING.md`

### Email Not Sending

**Check:**
1. SMTP credentials correct
2. App password used (not regular password for Gmail)
3. Less secure apps enabled (if applicable)
4. Port 587 not blocked by firewall

**Test:**
```bash
php artisan tinker
>>> Mail::raw('Test email', function($msg) {
    $msg->to('test@example.com')->subject('Test');
});
```

### Exchange Rate Not Updating

**Check:**
1. Rate source set correctly
2. API endpoint accessible
3. Cron job running (if automated)

**Manual Update:**
```bash
php artisan exchange:check-rate
```

---

## Security Best Practices

### API Keys
- Never commit API keys to version control
- Use `.env` file for sensitive credentials
- Rotate keys regularly
- Use different keys for staging/production

### Database
- Use strong passwords
- Restrict database access to localhost
- Regular backups
- Enable SSL for remote connections

### Admin Access
- Use strong admin passwords
- Limit admin accounts
- Enable 2FA (if implemented)
- Monitor admin activity logs

---

## Backup and Recovery

### Database Backup

**MySQL:**
```bash
mysqldump -u root -p buy_rmb > backup_$(date +%Y%m%d).sql
```

**Restore:**
```bash
mysql -u root -p buy_rmb < backup_20260430.sql
```

### Settings Export

**Export all settings:**
```bash
php artisan tinker
>>> \App\Models\Setting::all()->toJson()
```

### Full Backup Checklist
- [ ] Database dump
- [ ] `.env` file
- [ ] Uploaded files (`storage/app`)
- [ ] Configuration files
- [ ] SSL certificates

---

## Related Documentation

- `ADMIN_SETUP.md` - Admin account setup
- `HUBTEL_INTEGRATION.md` - Payment gateway setup
- `MNOTIFY_INTEGRATION.md` - mNotify SMS setup
- `SMS_FALLBACK_SYSTEM.md` - SMS fallback mechanism
- `EMAIL_TEMPLATES.md` - Email template customization
- `EXCHANGE_RATE_SYSTEM.md` - Exchange rate management
- `WALLET_SYSTEM.md` - Wallet functionality
- `GOOGLE_OAUTH_SETUP.md` - Google Sign-In setup
- `TAWK_TO_SETUP_COMPLETE.md` - Live chat setup
- `CMS_SYSTEM.md` - Content management

---

## Support

For technical support or questions about settings:
- Check related documentation files
- Review Laravel logs: `storage/logs/laravel.log`
- Test in staging environment first
- Contact system administrator

---

**Last Updated:** April 30, 2026  
**Version:** 1.0  
**Maintained By:** RMBXchange Development Team