# BANKING - Setup & Installation Guide

## Overview

BANKING is a full-featured digital banking platform built with Laravel 12, Tailwind CSS 4, and modern web technologies. It provides customer-facing banking services (accounts, transfers, cards, bill payments, airtime) alongside a comprehensive admin panel for managing customers, transactions, approvals, reports, and fraud monitoring. The application includes a built-in PWA for installable mobile/desktop experiences, role-based access control, and a complete audit trail.

---

## Prerequisites

- **PHP 8.2+** (with required extensions: mbstring, openssl, pdo, tokenizer, xml, ctype, json, bcmath)
- **MySQL 5.7+** / MariaDB 10.4+ (or SQLite for development)
- **Composer 2.x**
- **Node.js 18+** with npm (for frontend asset compilation via Vite)
- **Web server** (Apache with mod_rewrite, or Nginx)
- **XAMPP / WAMP / MAMP** (for local development)

---

## 1. Installation

### Clone / Download

```bash
cd C:\xampp\htdocs
# Place all banking files into the banking directory
cd banking
```

### Install Dependencies

```bash
composer install
npm install
```

### Environment Configuration

```bash
cp .env.example .env
php artisan key:generate
```

Edit `.env` and configure your database and application URL:

```ini
APP_NAME=BANKING
APP_ENV=local
APP_KEY=                    # Generated by key:generate
APP_DEBUG=true
APP_URL=http://localhost/banking/public

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=banking
DB_USERNAME=root
DB_PASSWORD=

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=587
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@banking.com"
MAIL_FROM_NAME="${APP_NAME}"
```

### Database Setup

Create the database before running migrations:

```sql
CREATE DATABASE banking CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Run Migrations & Seed

```bash
php artisan migrate:fresh --seed
```

This runs all 33 migration files and seeds the database with:
- Roles and permissions
- Site and theme settings
- Fee structures
- Interest settings
- Biller categories and providers
- Admin and demo customer accounts
- Sample transaction data

### Build Frontend Assets

```bash
# Development (with hot reload)
npm run dev

# Production
npm run build
```

Frontend stack: Tailwind CSS 4, Vite 7, Axios, Laravel Vite Plugin.

### Create Storage Link

```bash
php artisan storage:link
```

### Quick Setup (One Command)

A composer script is available that runs all setup steps:

```bash
composer setup
```

This executes: `composer install`, `.env` copy, `key:generate`, `migrate`, `npm install`, and `npm run build`.

---

## 2. Default Login Credentials

### Super Admin

| Field      | Value                |
|------------|----------------------|
| Email      | `admin@banking.com`  |
| Password   | `password`           |
| Login PIN  | `123456`             |
| Role       | Super Admin          |

### Admin

| Field      | Value                |
|------------|----------------------|
| Email      | `admin2@banking.com` |
| Password   | `password`           |
| Login PIN  | `123456`             |
| Role       | Admin                |

### Demo Customers

| Name              | Email                        | Password   | Login PIN | Transaction PIN |
|-------------------|------------------------------|------------|-----------|-----------------|
| James Anderson    | `james.anderson@email.com`   | `password` | `123456`  | `1234`          |
| Sarah Mitchell    | `sarah.mitchell@email.com`   | `password` | `123456`  | `1234`          |
| Michael Chen      | `michael.chen@email.com`     | `password` | `123456`  | `1234`          |
| Emily Rodriguez   | `emily.rodriguez@email.com`  | `password` | `123456`  | `1234`          |
| David Thompson    | `david.thompson@email.com`   | `password` | `123456`  | `1234`          |

---

## 3. Web Server Configuration

### Apache (XAMPP)

The `.htaccess` file in `public/` handles URL rewriting automatically. Ensure `mod_rewrite` is enabled in your Apache configuration.

Place the `banking` folder inside `C:\xampp\htdocs\` and access via:

```
http://localhost/banking/public
```

### Nginx

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/banking/public;
    index index.php;

    charset utf-8;
    client_max_body_size 10M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}
```

### PHP Built-in Server (Development Only)

```bash
php artisan serve
```

Access at `http://localhost:8000`. Do not use in production.

---

## 4. PWA Setup

The application is PWA-ready out of the box. Key files:

| File              | Purpose                                      |
|-------------------|----------------------------------------------|
| `public/manifest.json` | PWA manifest with app name, icons, theme |
| `public/sw.js`    | Service worker for offline caching           |
| `public/icons/`   | PWA icons in 8 sizes (72px to 512px)         |

After logging in, the browser will display an install prompt for adding BANKING to the home screen or desktop. The service worker caches static assets while bypassing dynamic routes (`/dashboard`, `/admin`, `/api`) to ensure fresh data on every visit.

To regenerate PWA icons from the SVG source:

```bash
php public/icons/generate-icons.php
```

---

## 5. Configuration

### Appearance / Theme

Log in as Super Admin and navigate to **Admin > Settings > Appearance**:

- Change primary, secondary, and accent colors
- Upload custom logo and favicon
- Adjust sidebar style and typography
- Changes apply immediately via the `theme_settings` table

### General Settings

Navigate to **Admin > Settings > General**:

- Bank name and branding
- Contact information
- Default currency
- Timezone

### Transaction Limits

Navigate to **Admin > Settings > Transactions**:

- Minimum and maximum transfer amounts
- Daily transfer limits
- Single transaction caps

### Fees

Navigate to **Admin > Settings > Fees**:

- Transfer fees (flat or percentage)
- Withdrawal fees
- Deposit fees
- Bill payment and airtime fees

### Interest Settings

Navigate to **Admin > Settings > Interest**:

- Per-account-type interest rates (savings, business, current)

### Security Settings

Navigate to **Admin > Settings > Security**:

- PIN lockout thresholds
- Session timeout configuration

### Notifications

Navigate to **Admin > Settings > Notifications**:

- Email notification toggles
- SMS notification settings

### Content Management

Navigate to **Admin > Settings > Content**:

- Homepage content
- Terms and conditions
- About page content

---

## 6. Production Deployment

### Security Checklist

- [ ] Set `APP_DEBUG=false` in `.env`
- [ ] Set `APP_ENV=production`
- [ ] Use HTTPS (SSL/TLS certificate)
- [ ] Set `SESSION_ENCRYPT=true`
- [ ] Configure a production mail driver (SMTP, SES, Mailgun)
- [ ] Set restrictive file permissions (`chmod 755` directories, `chmod 644` files)
- [ ] Disable directory listing (`Options -MultiViews -Indexes` already in `.htaccess`)
- [ ] Enable PHP OPcache
- [ ] Remove `.env` and `vendor/` from public web access
- [ ] Set `BCRYPT_ROUNDS=12` or higher

### Recommended php.ini Settings

```ini
memory_limit = 256M
max_execution_time = 60
upload_max_filesize = 10M
post_max_size = 10M
opcache.enable = 1
opcache.memory_consumption = 128
opcache.interned_strings_buffer = 8
opcache.max_accelerated_files = 10000
```

### Queue Worker (Production)

If using the database queue driver (default), run a queue worker:

```bash
php artisan queue:work --sleep=3 --tries=3
```

Use a process manager like Supervisor to keep it running.

---

## 7. Project Structure

```
banking/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/                  # 14 admin controllers
│   │   │   │   ├── AccountController.php
│   │   │   │   ├── AuditController.php
│   │   │   │   ├── CardController.php
│   │   │   │   ├── CustomerController.php
│   │   │   │   ├── DashboardController.php
│   │   │   │   ├── DepositController.php
│   │   │   │   ├── FraudController.php
│   │   │   │   ├── MessageController.php
│   │   │   │   ├── ReportController.php
│   │   │   │   ├── SettingController.php
│   │   │   │   ├── StaffController.php
│   │   │   │   ├── SupportController.php
│   │   │   │   ├── TransactionController.php
│   │   │   │   └── WithdrawalController.php
│   │   │   ├── Auth/                   # 3 auth controllers
│   │   │   │   ├── AuthenticatedSessionController.php
│   │   │   │   ├── ForgotPinController.php
│   │   │   │   └── RegisteredUserController.php
│   │   │   ├── Customer/               # 15 customer controllers
│   │   │   │   ├── AccountController.php
│   │   │   │   ├── AirtimeController.php
│   │   │   │   ├── BeneficiaryController.php
│   │   │   │   ├── BillPaymentController.php
│   │   │   │   ├── CardController.php
│   │   │   │   ├── DashboardController.php
│   │   │   │   ├── DepositController.php
│   │   │   │   ├── MessageController.php
│   │   │   │   ├── NotificationController.php
│   │   │   │   ├── ProfileController.php
│   │   │   │   ├── SecurityController.php
│   │   │   │   ├── SupportController.php
│   │   │   │   ├── TransactionController.php
│   │   │   │   ├── TransferController.php
│   │   │   │   └── WithdrawalController.php
│   │   │   ├── Controller.php
│   │   │   ├── HomeController.php
│   │   │   └── PwaController.php
│   │   └── Middleware/                  # 5 custom middleware
│   │       ├── AdminMiddleware.php
│   │       ├── CheckRole.php
│   │       ├── EnsurePinIsNotLocked.php
│   │       ├── EnsureUserIsActive.php
│   │       └── SuperAdminMiddleware.php
│   ├── Models/                         # 30 Eloquent models
│   │   ├── Account.php
│   │   ├── AirtimeTransaction.php
│   │   ├── AuditLog.php
│   │   ├── Beneficiary.php
│   │   ├── Biller.php
│   │   ├── BillerCategory.php
│   │   ├── BillPayment.php
│   │   ├── Card.php
│   │   ├── CardRequest.php
│   │   ├── DataTransaction.php
│   │   ├── Deposit.php
│   │   ├── Device.php
│   │   ├── Fee.php
│   │   ├── InterestSetting.php
│   │   ├── LoginAttempt.php
│   │   ├── Message.php
│   │   ├── Notification.php
│   │   ├── Permission.php
│   │   ├── Provider.php
│   │   ├── ProviderProduct.php
│   │   ├── Role.php
│   │   ├── SecurityEvent.php
│   │   ├── SiteSetting.php
│   │   ├── SupportMessage.php
│   │   ├── SupportTicket.php
│   │   ├── ThemeSetting.php
│   │   ├── Transaction.php
│   │   ├── TransactionEntry.php
│   │   ├── User.php
│   │   └── Withdrawal.php
│   ├── Policies/                       # 5 authorization policies
│   │   ├── AccountPolicy.php
│   │   ├── CardPolicy.php
│   │   ├── SupportTicketPolicy.php
│   │   ├── TransactionPolicy.php
│   │   └── UserPolicy.php
│   ├── Providers/
│   └── Services/                       # 18 business logic services
│       ├── AccountService.php
│       ├── AirtimeService.php
│       ├── AuditService.php
│       ├── AuthService.php
│       ├── BillPaymentService.php
│       ├── CardService.php
│       ├── DepositService.php
│       ├── FraudService.php
│       ├── MessageService.php
│       ├── NotificationService.php
│       ├── ReportService.php
│       ├── SecurityService.php
│       ├── SettingService.php
│       ├── SupportService.php
│       ├── TransactionService.php
│       ├── TransferService.php
│       ├── UserService.php
│       └── WithdrawalService.php
├── database/
│   ├── migrations/                     # 33 migration files
│   ├── seeders/                        # 12 seeder classes
│   └── database.sqlite                 # Default SQLite database
├── public/
│   ├── .htaccess                       # Apache rewrite rules
│   ├── index.php                       # Application entry point
│   ├── manifest.json                   # PWA manifest
│   ├── sw.js                           # Service worker
│   ├── robots.txt
│   ├── favicon.ico
│   ├── css/app.css                     # Compiled Tailwind CSS
│   ├── js/app.js                       # Compiled JavaScript
│   └── icons/                          # PWA icons (SVG + generation script)
├── resources/
│   └── views/
│       ├── layouts/                    # 4 layout templates
│       │   ├── public.blade.php
│       │   ├── customer.blade.php
│       │   ├── admin.blade.php
│       │   └── app.blade.php
│       ├── auth/                       # 3 auth views
│       │   ├── login.blade.php
│       │   ├── register.blade.php
│       │   └── forgot-pin.blade.php
│       ├── customer/                   # 15 customer view directories
│       │   ├── dashboard.blade.php
│       │   ├── accounts/
│       │   ├── airtime/
│       │   ├── beneficiaries/
│       │   ├── bills/
│       │   ├── cards/
│       │   ├── deposits/
│       │   ├── messages/
│       │   ├── notifications/
│       │   ├── profile/
│       │   ├── security/
│       │   ├── support/
│       │   ├── transactions/
│       │   ├── transfer/
│       │   └── withdrawals/
│       ├── admin/                      # 17 admin view directories
│       │   ├── dashboard.blade.php
│       │   ├── accounts/
│       │   ├── airtime/
│       │   ├── audit/
│       │   ├── beneficiaries/
│       │   ├── billpayments/
│       │   ├── cards/
│       │   ├── customers/
│       │   ├── deposits/
│       │   ├── fraud/
│       │   ├── messages/
│       │   ├── reports/
│       │   ├── settings/
│       │   ├── staff/
│       │   ├── support/
│       │   ├── transactions/
│       │   └── withdrawals/
│       ├── components/                 # 6 reusable Blade components
│       │   ├── confirm-modal.blade.php
│       │   ├── data-table.blade.php
│       │   ├── flash-messages.blade.php
│       │   ├── modal.blade.php
│       │   ├── pagination.blade.php
│       │   └── stat-card.blade.php
│       ├── home.blade.php
│       └── welcome.blade.php
├── routes/
│   └── web.php                         # All routes (243 lines)
├── config/                             # 10 Laravel config files
├── composer.json
├── package.json
├── vite.config.js
└── phpunit.xml
```

---

## 8. Features List

### Customer Features
- Registration with email and 6-digit login PIN
- Multi-factor authentication (email/password + PIN)
- Account dashboard with balance overview and charts
- Multiple account types: Savings, Current, Business
- Money transfers with 4-digit transaction PIN confirmation
- Beneficiary management (save frequent recipients)
- Deposit requests with proof upload
- Withdrawal requests
- Card management: physical and virtual cards
- Card freeze, unfreeze, and block
- Bill payments by category
- Airtime and data purchase
- Transaction history with receipt generation
- Push notifications and in-app messages
- Support ticket system with messaging
- Profile management and photo upload
- Security center (PIN changes, device management, login history)

### Admin Features
- Admin dashboard with analytics and charts
- Customer management (view, suspend, activate, delete)
- Account management and manual balance adjustment
- Transaction oversight (view, approve, reverse)
- Deposit approval/rejection workflow
- Withdrawal approval/rejection workflow
- Card request approval/rejection
- Card block/unblock
- Internal messaging to customers
- Support ticket assignment and resolution
- Staff account management
- Report generation (daily, monthly, by type)
- Report export functionality
- Audit log viewer
- Fraud monitoring and flagged transactions
- Security event tracking

### System Features
- Role-based access control (Super Admin, Admin, Customer)
- 5 authorization policies
- 18 service classes for business logic
- 12 database seeders
- PWA with offline caching
- Responsive design
- Theme customization (colors, logo, favicon)
- Configurable fees, interest rates, and transaction limits
- Comprehensive audit trail
- Fraud detection and monitoring

---

## 9. API Services Architecture

The business logic is encapsulated in 18 service classes under `app/Services/`. Payment providers can be integrated by extending the relevant service:

| Service                      | File                                    | Purpose                              |
|------------------------------|-----------------------------------------|--------------------------------------|
| `TransferService`            | `app/Services/TransferService.php`      | Internal and external transfers      |
| `DepositService`             | `app/Services/DepositService.php`       | Deposit processing and approval      |
| `WithdrawalService`          | `app/Services/WithdrawalService.php`    | Withdrawal processing and approval   |
| `BillPaymentService`         | `app/Services/BillPaymentService.php`   | Utility and bill payments            |
| `AirtimeService`             | `app/Services/AirtimeService.php`       | Airtime and data purchases           |
| `CardService`                | `app/Services/CardService.php`          | Card issuance and management         |
| `AccountService`             | `app/Services/AccountService.php`       | Account CRUD and balance management  |
| `TransactionService`         | `app/Services/TransactionService.php`   | Transaction recording and queries    |
| `AuthService`                | `app/Services/AuthService.php`          | Authentication and PIN management    |
| `UserService`                | `app/Services/UserService.php`          | User management and profiles         |
| `NotificationService`        | `app/Services/NotificationService.php`  | Notification dispatch                |
| `MessageService`             | `app/Services/MessageService.php`       | Internal messaging                   |
| `SupportService`             | `app/Services/SupportService.php`       | Support ticket management            |
| `SecurityService`            | `app/Services/SecurityService.php`      | Security events and device tracking  |
| `AuditService`               | `app/Services/AuditService.php`         | Audit logging                        |
| `FraudService`               | `app/Services/FraudService.php`         | Fraud detection and flagging         |
| `ReportService`              | `app/Services/ReportService.php`        | Report generation                    |
| `SettingService`             | `app/Services/SettingService.php`       | Application settings management      |

Each service is designed for extensibility. To integrate a real payment provider, extend the relevant service and implement the provider-specific API calls.

---

## 10. Routes Overview

All routes are defined in `routes/web.php` and organized into three groups:

### Public Routes
| Method | URI                              | Name              |
|--------|----------------------------------|-------------------|
| GET    | `/`                              | `home`            |
| GET    | `/login`                         | `login`           |
| POST   | `/login`                         | (login handler)   |
| GET    | `/register`                      | `register`        |
| POST   | `/register`                      | (register handler)|
| POST   | `/logout`                        | `logout`          |
| GET    | `/forgot-pin`                    | `password.request`|
| POST   | `/forgot-pin`                    | `password.email`  |
| GET    | `/manifest.json`                 | `pwa.manifest`    |
| GET    | `/sw.js`                         | `pwa.serviceWorker`|

### Customer Routes (prefix: `/dashboard`)
Requires `auth`, `EnsureUserIsActive`, `EnsurePinIsNotLocked` middleware.

Dashboard, accounts, transfers, deposits, withdrawals, cards, beneficiaries, bill payments, airtime, transactions, notifications, messages, support, security, and profile management.

### Admin Routes (prefix: `/admin`)
Requires `auth`, `AdminMiddleware` middleware.

Dashboard, customer management, account management, transaction management, deposits, withdrawals, cards, messaging, support, settings (general, appearance, security, transactions, notifications, fees, interest, content), staff management, reports, audit, and fraud monitoring.

---

## 11. Compliance Note

This is a banking software platform and prototype. For production deployment, ensure compliance with:

- Applicable financial regulations in your jurisdiction
- Know Your Customer (KYC) requirements
- Anti-Money Laundering (AML) regulations
- Data protection laws (GDPR, CCPA, etc.)
- PCI-DSS standards for card data handling
- Secure storage of sensitive financial data
- Regular security audits and penetration testing

---

## Development Commands

```bash
# Start all development services (server, queue, logs, vite)
composer dev

# Run tests
composer test

# Clear caches
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

# Re-seed database
php artisan migrate:fresh --seed

# Generate PWA icons
php public/icons/generate-icons.php
```