# Artiva cPanel Production Deployment Guide

This guide details how to deploy the **Artiva Frontend (React Single Page App)** and the **Artiva Backend (Node.js API)** to a cPanel hosting environment.

---

## 📦 Deployment Packages

Two ready-to-upload zip archives have been generated in your `deploy_cpanel/` directory:

| Package | Size | Contents | Upload Destination |
| :--- | :--- | :--- | :--- |
| [`artiva-frontend-cpanel.zip`](file:///c:/Users/USER/verifix/deploy_cpanel/artiva-frontend-cpanel.zip) | ~20 MB | Optimized production build + SPA `.htaccess` routing | `public_html/` or subdomain root (e.g. `app.yourdomain.com`) |
| [`artiva-backend-cpanel.zip`](file:///c:/Users/USER/verifix/deploy_cpanel/artiva-backend-cpanel.zip) | ~1.2 MB | Bundled API, `app.js`, `lib/`, `package.json`, `.env.example` | Node.js App Root folder (e.g. `/home/username/api`) |

---

## Part 1: Deploying the Backend API (Node.js)

### Step 1: Create the Node.js Application in cPanel
1. Log into your **cPanel Dashboard**.
2. Under the **Software** section, click **"Setup Node.js App"**.
3. Click the **"Create Application"** button.
4. Fill in the application parameters:
   - **Node.js version**: Select `18.x` or `20.x`
   - **Application mode**: `Production`
   - **Application root**: Enter `api` (this will create `/home/username/api`)
   - **Application URL**: Select your subdomain (e.g., `api.yourdomain.com`) or domain path
   - **Application startup file**: Enter `app.js`
5. Click **Create**.

### Step 2: Upload and Extract Backend Files
1. Open **cPanel File Manager**.
2. Navigate to your application root directory (`/home/username/api`).
3. If cPanel generated a default `app.js`, delete or overwrite it.
4. Click **Upload** in the toolbar and select `artiva-backend-cpanel.zip`.
5. Once uploaded, right-click `artiva-backend-cpanel.zip` and select **Extract**.
6. Verify the following files exist in `/home/username/api`:
   - `app.js`
   - `lib/` (contains `cpanel.js`, `index.js`, `cron.js`)
   - `package.json`
   - `.env.example`
   - `.htaccess`

### Step 3: Configure Firebase Service Account & Environment Variables
Because cPanel is outside Google Cloud, the backend uses a Firebase Service Account key:

1. **Obtain your Firebase Service Account JSON**:
   - Go to the [Firebase Console](https://console.firebase.google.com/) -> Select project `artiva-f24a8`.
   - Click the **Gear icon (Project Settings)** -> **Service accounts** tab.
   - Click **"Generate new private key"** and download the `.json` file.
   - Rename this file to `serviceAccountKey.json` and upload it to `/home/username/api/`.

2. **Configure `.env`**:
   - In File Manager under `/home/username/api/`, rename or copy `.env.example` to `.env`.
   - Edit `.env` with your real keys:
     ```ini
     PORT=3000
     NODE_ENV=production
     FIREBASE_PROJECT_ID=artiva-f24a8
     FIREBASE_SERVICE_ACCOUNT_PATH=serviceAccountKey.json

     # Paystack Keys
     PAYSTACK_SECRET_KEY=sk_live_...
     PAYSTACK_PUBLIC_KEY=pk_live_...

     # AES-256 PII Encryption Key (32+ characters)
     ENCRYPTION_KEY=artiva-prod-encryption-key-2026-abcde

     # Admin UID
     ADMIN_UID=Vlw9L5wiNgbwMAcvs0bqyLdiBwl2
     ```

### Step 4: Install Dependencies & Start the App
1. Return to cPanel -> **"Setup Node.js App"**.
2. Click the edit (pencil) icon next to your application.
3. Under **Detected configuration files**, click **"Run NPM Install"**.
4. Once completed, click **"Restart"** at the top.

### Step 5: Verify the Backend
Open your browser and navigate to:
- Health check: `https://api.yourdomain.com/health` (should return `{"status":"healthy",...}`)
- API Documentation: `https://api.yourdomain.com/api/docs` (Swagger UI)

---

## Part 2: Deploying the Frontend (React SPA)

### Step 1: Prepare the Target Directory
1. If deploying to your primary domain, files will go into `public_html/`.
2. If deploying to a subdomain (e.g. `app.yourdomain.com`), create the subdomain under **Domains** in cPanel and note its document root directory (e.g., `public_html/app` or `app.yourdomain.com`).

### Step 2: Upload and Extract Frontend Files
1. In cPanel **File Manager**, navigate to the document root directory.
2. In the top right corner of File Manager, click **Settings** -> check **"Show Hidden Files (dotfiles)"** -> **Save** (this ensures you can see and edit `.htaccess`).
3. Click **Upload** and upload `artiva-frontend-cpanel.zip`.
4. Right-click `artiva-frontend-cpanel.zip` and select **Extract** directly into the document root.
5. Verify the files extracted:
   - `index.html`
   - `.htaccess` (pre-configured for React Router SPA history fallback)
   - `assets/` (JS, CSS, fonts)
   - `manifest.webmanifest`, `sw.js` (PWA service worker)

### Step 3: Verify the Frontend
Navigate to `https://yourdomain.com` (or `https://app.yourdomain.com`).
- Test direct links (e.g., `/login`, `/dashboard`) and click browser refresh. The pre-packaged `.htaccess` ensures all deep links route seamlessly to `index.html` without 404 errors.

---

## Part 3: SSL / HTTPS (Let's Encrypt / AutoSSL)

1. In cPanel, navigate to **SSL/TLS Status**.
2. Select your frontend domain (`yourdomain.com`) and backend domain (`api.yourdomain.com`).
3. Click **"Run AutoSSL"**.
4. Wait 1-2 minutes until both domains show green active locks.

---

## Part 4: Paystack Webhook Configuration

1. Log into your [Paystack Dashboard](https://dashboard.paystack.com/).
2. Go to **Settings** -> **Webhooks**.
3. Set your Live Webhook URL to:
   ```
   https://api.yourdomain.com/api/payments/webhook
   ```
4. Save changes.

---

## Part 5: Scheduled Cron Job (Automatic Refunds)

The platform includes a background job that processes unfulfilled escrow refunds every 15 minutes:

1. In cPanel, navigate to **Cron Jobs**.
2. Under **Add New Cron Job**:
   - Common Settings: **Once Every 15 Minutes** (`*/15 * * * *`)
   - Command:
     ```bash
     cd /home/username/api && node lib/cron.js >> /home/username/api/cron.log 2>&1
     ```
     *(Note: Replace `/home/username` with your actual cPanel account username).*
3. Click **Add New Cron Job**.