# Deployment Guide — Apex Heritage Mortgage ERP (Truehost / cPanel)

This is a standard Laravel 11 application. It was scaffolded in a sandboxed environment
where Packagist (getcomposer.org / repo.packagist.org) is not reachable, so **`vendor/` is
NOT included** — you'll run `composer install` on Truehost where you've confirmed
Composer + SSH access.

## 1. Upload

Upload the whole project folder to a directory **outside** `public_html`, e.g.:
```
/home/yourcpaneluser/apex-mortgage-erp/
```
Never put the Laravel root inside `public_html` directly — only `public/` should be web-facing.

## 2. Point the domain/subdomain at `public/`

In cPanel → **Domains** (or Subdomains), set the document root to:
```
/home/yourcpaneluser/apex-mortgage-erp/public
```
If your plan doesn't allow setting document root to a folder outside public_html, use the
standard workaround instead:
- Copy `public/index.php` → `public_html/index.php`
- Edit the two `require` paths inside it to point up to `../apex-mortgage-erp/vendor/autoload.php`
  and `../apex-mortgage-erp/bootstrap/app.php`
- Copy `public/.htaccess` → `public_html/.htaccess`

## 3. SSH in and install dependencies

```bash
cd ~/apex-mortgage-erp
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate
```

## 4. Configure `.env`

Edit `.env` with your real values:
- `APP_URL` — your live domain
- `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` — create these first in cPanel → **MySQL
  Databases** (cPanel prefixes both DB name and user with your cPanel username automatically)
- `MAIL_*` — your Truehost SMTP credentials (same pattern used on your other SMTP-driven builds)
- Confirm `APP_DEBUG=false` and `APP_ENV=production` — **never** run this live with debug on;
  it's a financial system and stack traces would leak customer/loan data.

## 5. Migrate and seed

```bash
php artisan migrate --force
php artisan db:seed --force
```
This creates the demo staff accounts (see below) and sample applications matching the
screenshots you shared. **Change every demo password immediately after first login**, then
either delete the demo seeder data or replace it with real staff/customer records before
go-live.

## 6. Storage symlink & permissions

```bash
php artisan storage:link
chmod -R 755 storage bootstrap/cache
```
Document uploads (KYC, title docs, valuation reports) go into `storage/app/private` — this is
intentionally NOT web-accessible, since these are sensitive financial/identity documents.

## 7. Cache for production

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```
Re-run these after every deploy of new code (and clear with `optimize:clear` before you next
`git pull` + change `.env`, or cached config will mask your changes).

## 8. Cron (for future phases — queues, reminders, SLA escalations)

cPanel → **Cron Jobs**, add:
```
* * * * * cd /home/yourcpaneluser/apex-mortgage-erp && php artisan schedule:run >> /dev/null 2>&1
```

## 9. Demo login credentials (seeded)

| Role | Email | Password |
|---|---|---|
| System Administrator | admin@apexheritage.ng | Password!234 |
| Relationship/Account Officer | ao@apexheritage.ng | Password!234 |
| Relationship Manager | rm@apexheritage.ng | Password!234 |
| Risk Officer | risk@apexheritage.ng | Password!234 |
| Legal Officer | legal@apexheritage.ng | Password!234 |
| Mortgage Committee | committee@apexheritage.ng | Password!234 |
| Finance Officer | finance@apexheritage.ng | Password!234 |
| Auditor | audit@apexheritage.ng | Password!234 |

**Rotate all of these before any real customer data enters the system.**

## Security notes specific to this build

- Sessions and cache use the `database` driver (no Redis dependency — matches shared hosting
  reality). Session table auto-clears via Laravel's normal garbage collection.
- All document uploads are designed to land in `storage/app/private`, never `public/`. Phase 2
  file-upload controllers must respect this — do not switch to the `public` disk for KYC/legal
  documents.
- `SESSION_SECURE_COOKIE=true` is set in `.env.example` — only works once your domain is on
  HTTPS (Truehost/cPanel AutoSSL). Confirm SSL is active before going live.
- Role-based access is enforced server-side via the `role:` middleware on every route group —
  not just hidden in the sidebar. Confirmed in `routes/web.php`.

## What's built vs. what's next

**Live now (Phase 1 + 2 + 3 — all 11 sidebar modules from the PRD have real screens):**
- Auth, Dashboard, Borrower Portal (AI Prequalification calculator)
- AO Workspace, RM Portal, Risk & Operations, Legal Workspace, Manager Portal — full
  origination-to-approval chain, auto-advancing through stages as each track completes
- **IT Admin** — System Rules (19 seeded rules across product/approval/compliance/validation
  categories, editable inline, matches your screenshot exactly), Closing Cost Fees, User
  Management (suspend/reactivate staff), API Configuration (integration status board)
- **Portfolio Monitoring** — real aggregates off disbursed loans (performing/at-risk/collection
  rate), per-loan performance table
- **Finance Portal** — budget allocations by product/branch with utilization bars
- **Audit Portal** — Audit Records + a genuinely useful **Activity Log** tab that surfaces
  `application_stage_history` directly: every stage transition, who did it, when, from what IP

**Genuinely not built yet (beyond this PRD's Phase 1-3 scope, flagged honestly):**
- Document upload/storage UI (schema exists in `application_documents`, no controller yet)
- Loan disbursement workflow itself (currently seeded directly to `disbursed` status —
  there's no "Finance Officer clicks disburse" screen yet)
- Repayment schedule generation / amortization tables (PRD Section 15, Mortgage Servicing)
- Credit bureau / core banking / SMS gateway *actual* API integration (IT Admin shows these
  as configuration status, not live connections)
- Notification engine (email/SMS/WhatsApp alerts) — PRD Section 21
- Reporting exports (Excel/PDF/CSV/Power BI) — PRD Section 19

Per the PRD's own overall assessment, a full enterprise mortgage platform at the standard of
major financial institutions runs 400-600 pages of implementation spec. This build covers the
origination-to-approval workflow spine plus admin/reporting shells — the highest-value 40-50%
of what's scoped, matching what the screenshots you shared actually demonstrate.