#RuralPointADVANCE - Loan Management System

A comprehensive Django-based loan management system designed for Kenyan financial institutions, specifically built for **BRANCH BUSINESS ADVANCE**.

## 🎨 Color Palette

- **Primary**: Deep Blue `#0A3D62`
- **Secondary**: Teal Blue `#3C9EBD`
- **Background**: White `#FFFFFF`
- **Success**: Green `#2ECC71`
- **Error**: Red `#E74C3C`

## 🏗️ System Architecture

### Core Modules

1. **🔐 Authentication & User Management** (`users/`)
   - Custom User model with phone/email login
   - Role-based access control (Admin, Loan Officer, Auditor, Borrower)
   - OTP verification system
   - KYC data management
   - PIN-based mobile authentication

2. **💵 Loan Management** (`loans/`)
   - Loan product definitions
   - Application workflow with approval process
   - Active loan tracking
   - Repayment management
   - Rollover functionality
   - M-Pesa integration (mock)

3. **📊 Reports & Analytics** (`reports/`)
   - Credit scoring system
   - Comprehensive reporting
   - Notification system
   - System settings management

4. **🧾 Document Generation** (`utils/`)
   - Offer letter generation
   - Receipt creation
   - Loan statements
   - Document templates

## 🚀 Quick Start

### Prerequisites

- Python 3.8+
- Django 5.2+
- SQLite (default) or MySQL

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd branch-system
   ```

2. **Install dependencies**
   ```bash
   pip install django pillow reportlab openpyxl xlsxwriter
   ```

3. **Run migrations**
   ```bash
   python manage.py makemigrations
   python manage.py migrate
   ```

4. **Create superuser**
   ```bash
   python manage.py createsuperuser
   ```

5. **Load sample data**
   ```bash
   python manage.py load_sample_data
   ```

6. **Run the development server**
   ```bash
   python manage.py runserver
   ```

### Access Points

- **Admin Interface**: http://localhost:8000/admin/
- **Dashboard**: http://localhost:8000/dashboard/
- **API Endpoints**: Available for future mobile app integration

## 👥 User Roles

### Admin
- Full system access
- User management
- System configuration
- Report generation

### Loan Officer
- Approve/reject loan applications
- Manage borrowers
- Process repayments
- Handle rollover requests

### Auditor
- View audit logs
- Generate reports
- Monitor system activity

### Borrower
- Submit loan applications
- View loan status
- Make repayments
- Request rollovers

## 📋 Core Features

### Loan Products
- **Personal Loan**: Quick emergency loans
- **Business Advance**: Business expansion funding
- **Salary Loan**: Employee salary-based loans
- **Emergency Loan**: Urgent financial needs
- **Asset Finance**: Equipment and asset financing

### Application Workflow
1. Borrower submits application
2. Auto-approval check (configurable)
3. Manual review by loan officer
4. Approval/rejection with notes
5. Offer letter generation
6. Loan disbursement

### Repayment System
- Multiple payment methods (M-Pesa, Bank, Cash, Cheque)
- Automatic payment tracking
- Late payment penalties
- Receipt generation

### Credit Scoring
- Repayment history analysis
- Income assessment
- Rollover frequency tracking
- Employment stability evaluation

### Document Generation
- **Offer Letters**: PDF generation with terms
- **Receipts**: Payment confirmation documents
- **Statements**: Loan balance reports
- **Templates**: Customizable document formats

## 🔧 Configuration

### System Settings
- Default interest rates
- Processing fees
- Late payment penalties
- Auto-approval thresholds
- M-Pesa integration settings

### Email & SMS
- Template-based notifications
- Automated reminders
- Status updates
- Payment confirmations

## 📊 Reporting

### Available Reports
- **Borrower Reports**: Active, dormant, blacklisted users
- **Loan Reports**: Disbursements, outstanding, defaults
- **Collection Reports**: Expected vs actual payments
- **Default Reports**: Overdue loan analysis
- **Rollover Reports**: Extension statistics

### Export Formats
- PDF (using ReportLab)
- Excel (using openpyxl)
- CSV (for data analysis)

## 🔐 Security Features

- Role-based access control
- Audit trail logging
- Session management
- Password policies
- PIN-based authentication

## 📱 Mobile-Ready Design

The system is designed with mobile-first principles:
- Responsive dashboard
- Touch-friendly interface
- PIN-based login for mobile users
- API-ready architecture for future mobile app

## 🛠️ Development

### Project Structure
```
branch-system/
├── ruralpoint_system/          # Main project settings
├── users/                  # User management
├── loans/                  # Loan operations
├── reports/                # Analytics & reporting
├── utils/                  # Document generation
├── templates/              # HTML templates
├── static/                 # CSS, JS, images
├── media/                  # Uploaded files
└── manage.py
```

### Key Models
- `CustomUser`: Extended user model with KYC data
- `LoanProduct`: Loan product definitions
- `LoanApplication`: Application workflow
- `Loan`: Active loan tracking
- `Repayment`: Payment management
- `LoanScoring`: Credit assessment
- `Notification`: System notifications

### Admin Interface
Comprehensive Django admin with:
- Custom admin classes
- Bulk actions
- Advanced filtering
- Export capabilities
- Audit logging

## 🔮 Future Enhancements

### Planned Features
- **Mobile App**: React Native application
- **API Integration**: RESTful API with DRF
- **Advanced Analytics**: Machine learning scoring
- **Blockchain**: Smart contract integration
- **AI Chatbot**: Customer support automation

### M-Pesa Integration
- STK Push implementation
- C2B payment processing
- Real-time payment verification
- Transaction reconciliation

## 📞 Support

For technical support or questions:
- Email: support@branchbusinessadvance.com
- Phone: +254 XXX XXX XXX

## 📄 License

This project is proprietary software developed forRuralPointADVANCE.

---

**Built with ❤️ for Kenyan Fintech Innovation** 