# Online Banking PWA — Architecture & Implementation Plan

## Overview
A production-oriented fintech Progressive Web App built with Laravel 10 (PHP 8.2+), MySQL, Bootstrap 5, and Chart.js. Provides a customer banking portal and a secure administrator management system. Designed for cPanel hosting with phpMyAdmin.

---

## Technology Stack
| Layer | Technology |
|-------|-----------|
| Backend | PHP 8.2+, Laravel 10.x |
| Database | MySQL 8.0+ |
| Frontend | Bootstrap 5, Chart.js, Blade templating |
| Auth | Laravel Auth (session-based), hashed passwords/PINs, OTP |
| Email | Laravel Mail via configurable SMTP |
| PDF | barryvdh/laravel-dompdf |
| QR | simplesoftwareio/simple-qrcode |
| Images | intervention/image (receipt rendering) |
| PWA | Web manifest, service worker, installable icons |

---

## Brand Identity
- Primary banking blue: `#123B70`
- CTA blue: `#2878DF`
- Accent teal: `#0F9F83`
- Soft background: `#F8FAFC`
- Text: `#172B4D`
- Borders: `#E5EAF1`
- Light theme throughout, rounded cards, subtle shadows

---

## Database ERD (24 tables)

```
users ──< accounts ──< balances
users ──< beneficiaries
users ──< transfer_pins
users ──< otp_verifications
users ──< login_history
users ──< notifications
users ──< support_conversations ──< support_messages

accounts ──< transactions ──< ledger_entries
transactions ──< receipts

admins ──< audit_logs
admins > roles ──< permissions
admins ──< account_restrictions

verification_rules (COT/Tax/IMF config)
smtp_settings
bank_settings
authentication_settings
```

### Key tables
1. `users` — customers (id, name, email, phone, email_verified_at, password, two_factor_secret, status, avatar, ...)
2. `admins` — staff (id, name, email, password, role_id, is_active, last_login_at)
3. `roles` — admin roles (admin, manager, support, compliance)
4. `permissions` — granular actions per role
5. `accounts` — bank accounts (user_id, account_number [unique], account_type, currency, status)
6. `balances` — account balances (account_id, available_balance, ledger_balance)
7. `beneficiaries` — saved transfer recipients
8. `transactions` — transfers (reference [unique], sender_account_id, beneficiary_name, beneficiary_account, beneficiary_bank, amount, currency, description, status, verification_stage, settlement_status, ...)
9. `ledger_entries` — double-entry bookkeeping (transaction_id, account_id, entry_type [debit/credit], amount)
10. `transfer_pins` — hashed transfer PINs (user_id, pin_hash, changed_at)
11. `otp_verifications` — OTP records (user_id, code_hash, purpose, expires_at, attempts, verified_at)
12. `verification_rules` — admin-configured COT/Tax/IMF rules (type, enabled, required_amount_min, code_prefix, description, legal_basis)
13. `account_restrictions` — restriction history (user_id, status, reason, admin_note, restricted_by, restricted_at, review_at, restored_at)
14. `smtp_settings` — encrypted SMTP config
15. `bank_settings` — bank name, logo, support email, phone, branding
16. `authentication_settings` — OTP expiry, attempt limits, password policy, session config
17. `notifications` — customer notifications
18. `support_conversations` — chat sessions (user_id, status, assigned_admin_id)
19. `support_messages` — messages (conversation_id, sender_type, body, attachments)
20. `receipts` — generated receipts (transaction_id, receipt_code [unique], verification_url, pdf_path)
21. `audit_logs` — admin action audit trail
22. `login_history` — customer login records (user_id, ip, user_agent, login_at)

---

## Application Architecture

### Directory structure
```
app/
├── Http/Controllers/
│   ├── Auth/          (register, login, password reset, email verify, OTP)
│   ├── Customer/      (dashboard, transfers, beneficiaries, profile, verification, receipts, support)
│   └── Admin/         (dashboard, customers, transactions, verification settings, account status, SMTP, system, admin mgmt, support)
├── Http/Middleware/   (admin guard, account restriction, 2FA)
├── Http/Requests/     (validated form requests)
├── Models/            (24 Eloquent models with relationships)
└── Services/
    ├── TransferService       (atomic transfers, locking, idempotency, double-entry ledger)
    ├── OtpService            (OTP generation, hashing, expiry, attempt limits)
    ├── ReceiptService        (PDF/image generation, QR codes)
    ├── VerificationService   (PIN/OTP/COT stage management)
    └── SmtpConfigService     (runtime SMTP from DB, encrypted credentials)
```

### Security model
- CSRF tokens on all forms
- Server-side authorization (never trust client balances)
- Atomic DB transactions with `SELECT ... FOR UPDATE` row locking
- Idempotency keys on transfers (unique transaction references)
- Double-entry ledger — every transfer creates paired debit/credit entries
- Hashed passwords (bcrypt), hashed transfer PINs (bcrypt), hashed OTPs (bcrypt/hash)
- Encrypted SMTP credentials (Laravel encrypter)
- Rate limiting on login and OTP resend
- Role-based access control for admin portal
- Account restrictions enforced in middleware + controller layers

---

## Transfer Verification Flow (3-stage progress bar)

```
Customer initiates transfer
        │
        ▼
[STAGE 1: Transfer PIN — 40%]
        │ validate hashed PIN
        ▼
[STAGE 2: Email OTP — 70%]
        │ generate time-limited OTP → SMTP email
        │ verify code, handle expiry/attempt limits/resend cooldown
        ▼
[STAGE 3: COT/Compliance — 100%]
        │ admin-configured verification rules
        │ disclose purpose + legal basis
        │ verification ≠ settlement
        ▼
Settlement status (separate from verification)
  → PENDING → SUCCESSFUL (provider confirms) / FAILED
```

100% = verification complete. Settlement tracked separately. Transaction labelled SUCCESSFUL only when settlement is confirmed. Simulated environment clearly labelled.

---

## Phases

| Phase | Deliverables |
|-------|-------------|
| 1 | Architecture, ERD, plan (this document) |
| 2 | Laravel skeleton, MySQL schema, migrations, auth |
| 3 | Customer dashboard, account/profile pages |
| 4 | Transfer system, PIN, OTP, COT progress UI |
| 5 | Admin portal, account restrictions, config |
| 6 | SMTP integration, notifications, live chat |
| 7 | Receipt generation, PDF/image/QR/print |
| 8 | PWA manifest, service worker, responsive design |
| 9 | Tests, security validation |
| 10 | cPanel deployment guide, final docs |

---

## Account statuses
`active`, `blocked`, `suspended`, `frozen`, `inactive`, `dormant` — enforced server-side via middleware + service-layer checks. Restricted customers see a premium modal when attempting transfers.