# SoftShore Billing v2.0 — Step-by-Step cPanel Production Deployment & User Guide

**Release Package:** `cpanel-production-release/` & `softshore-billing-cpanel-release.zip`  
**Initial Live Company:** `Demo Company` (`id: ten_softshore`, Subdomain: `demo`)  
**Database Engine:** MySQL 8 / MariaDB (`DB_DRIVER=mysql` with real-time relational + state table sync)

---

## Part 1: Super Admin & Demo Company Users (Credentials List)

The production database is pre-seeded with **only 1 company (`Demo Company`)** and **8 operational user accounts** (1 Platform Super Admin + 7 Demo Company Users across all RBAC roles).

| # | User Name | Role | Email / Login ID | Alternate Email | Password | Assigned Branch / Scope |
|---|-----------|------|------------------|-----------------|----------|-------------------------|
| 1 | **Kayser Ahmed (Super Admin)** | `Super Admin` | `superadmin@softshore.tech` | `kayser@softshore.tech` | `admin123` | Platform Global (All Companies) |
| 2 | **Tanvir Rahman (Company Admin)** | `Company Admin` | `admin@democompany.com` | `admin@softshore.tech` | `demo123` | Demo Company — Dhaka Head Office |
| 3 | **Nusrat Jahan (Branch Manager)** | `Company Manager` | `manager@democompany.com` | `manager@softshore.tech` | `demo123` | Demo Company — Chattogram Branch |
| 4 | **Farhana Akter FCA (Chief Accountant)** | `Accountant` | `accountant@democompany.com` | `accountant@softshore.tech` | `demo123` | Demo Company — Dhaka Head Office |
| 5 | **Rafiq Hasan (Sales Executive)** | `Company Executive` | `executive@democompany.com` | `executive@softshore.tech` | `demo123` | Demo Company — Dhaka Head Office |
| 6 | **Sadia Islam (Customer Success Lead)** | `Company Executive` | `sadia@democompany.com` | `sadia@softshore.tech` | `demo123` | Demo Company — Dhaka Head Office |
| 7 | **Kamrul Hasan (Cloud Support Engineer)** | `Company Executive` | `kamrul@democompany.com` | `kamrul@softshore.tech` | `demo123` | Demo Company — Chattogram Branch |
| 8 | **Mehedi Alam (Square Pharma IT)** | `Customer` | `customer@democompany.com` | `mehedi@squarepharma.com.bd` | `demo123` | Customer Self-Service Portal |

> **How to Sign In or Switch Users in Live UI:**  
> Click the **`Sign In / Demo Users`** button in the top navigation bar. You can either enter any Email + Password above, or click **`Switch / Login`** next to any user in the directory table for instant 1-click role switching.

---

## Part 2: Step-by-Step cPanel Deployment Guide (Live Operational Database)

### Step 1: Create the MySQL Database & User in cPanel
1. Log in to your **cPanel** dashboard.
2. Open **Databases** $\rightarrow$ **MySQL® Database Wizard** (or **MySQL® Databases**).
3. **Create a Database:** e.g. `cpaneluser_softshore_billing`
4. **Create a Database User:** e.g. `cpaneluser_dbuser` with a strong password.
5. **Add User to Database:** Check **ALL PRIVILEGES** and click **Make Changes**.

---

### Step 2: Import the Production SQL Dump (`cpanel_mysql_production.sql`)
1. In cPanel, open **Databases** $\rightarrow$ **phpMyAdmin**.
2. Select your newly created database (`cpaneluser_softshore_billing`) in the left sidebar.
3. Click the **Import** tab at the top.
4. Click **Choose File** and select:
   - `database/cpanel_mysql_production.sql` (included inside `softshore-billing-cpanel-release.zip` and `cpanel-production-release/database/cpanel_mysql_production.sql`).
5. Click **Import / Go** at the bottom.
   - This imports all 27 relational tables (`tenants`, `branches`, `roles`, `users`, `accounts`, `customers`, `products`, `subscriptions`, `leads`, `invoices`, `invoice_items`, `payments`, `journal_entries`, `ledger_entries`, `app_state_store`, etc.) pre-populated with **1 Company (`Demo Company`)**, **8 Users**, **33 COA Accounts**, **5 Customers**, **5 Products**, **4 Subscriptions**, and **5 Invoices**.
   - *(Note: Even if you skip manual import, when `DB_DRIVER=mysql` is set in `.env`, the Node.js server automatically creates any missing tables and seeds `Demo Company` on its first boot!)*

---

### Step 3: Upload the Production Release ZIP to cPanel File Manager
1. In cPanel, open **Files** $\rightarrow$ **File Manager**.
2. Navigate to your target application folder (for example, `/home/cpaneluser/softshore-billing` or your subdomain folder `/home/cpaneluser/billing.yourdomain.com`).
3. Click **Upload** and upload **`softshore-billing-cpanel-release.zip`**.
4. Right-click `softshore-billing-cpanel-release.zip` $\rightarrow$ click **Extract** into your application root directory.
5. Verify your application directory contains:
   - `app.js` *(cPanel Node.js Selector startup entry file)*
   - `package.json` & `package-lock.json`
   - `dist/` *(Pre-compiled production React 18 SPA frontend — no build step required on server!)*
   - `server/` *(Express REST API, Double-Entry Accounting Engine, MySQL Sync Engine, Notification Engine)*
   - `database/` *(`cpanel_mysql_production.sql`, `schema.sql`, `softshore_db.json`)*
   - `.env` *(or `.env.example`)*
   - `.htaccess`

---

### Step 4: Configure `.env` with Your Live MySQL Credentials
1. In cPanel File Manager (enable **Show Hidden Files (dotfiles)** in Settings at top-right), right-click **`.env`** (or rename `.env.example` to `.env`) and click **Edit**:
   ```env
   NODE_ENV=production
   PORT=4000
   APP_NAME="SoftShore Billing v2.0"
   APP_URL=https://billing.yourdomain.com

   # Live cPanel MySQL Database Connection
   DB_DRIVER=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=cpaneluser_softshore_billing
   DB_USERNAME=cpaneluser_dbuser
   DB_PASSWORD=YOUR_CPANEL_MYSQL_PASSWORD

   # Outbound SMTP & BGTel SMS Gateway
   SMTP_HOST=mail.softshore.tech
   SMTP_PORT=465
   SMTP_SECURE=true
   SMTP_USER=no-reply@softshore.tech
   SMTP_PASS=YOUR_SMTP_PASSWORD
   SMTP_FROM_EMAIL=no-reply@softshore.tech

   SMS_GATEWAY_URL=https://apipro.bgtelsms.com/onetomany
   SMS_ACODE=30000075
   SMS_API_KEY=00694cc4892224ee3eefffed2330becadcb8cade
   SMS_SENDER_ID=KidLand
   ```
2. Click **Save Changes**.

---

### Step 5: Configure "Setup Node.js App" in cPanel
1. In cPanel, go to **Software** $\rightarrow$ **Setup Node.js App**.
2. Click **Create Application**:
   - **Node.js version:** Select **18.x**, **20.x**, or **22.x / 24.x** (any Node 18+ version).
   - **Application mode:** `Production`
   - **Application root:** Enter your folder path (e.g. `softshore-billing` or `billing.yourdomain.com`)
   - **Application URL:** Select your domain/subdomain (e.g. `billing.yourdomain.com`)
   - **Application startup file:** `app.js`
3. Click **Create** at the top-right.
4. Once created, click **Run NPM Install** button inside the Node.js App page.
   - Because `dist/` is already pre-built in the release package, only lightweight runtime dependencies (`express`, `cors`, `mysql2`, `dotenv`) are installed in seconds!
5. Click **Restart** to start the application.
6. Visit your domain (`https://billing.yourdomain.com`). Look at the top header badge:
   - You will see **`Company: Demo Company`** and **`MySQL Live (cpaneluser_softshore_billing)`** confirming live MySQL database persistence!

---

### Step 6: Configure Automated cPanel Cron Jobs (SRS Section 9)
In **cPanel $\rightarrow$ Advanced $\rightarrow$ Cron Jobs**, add these 3 automated background jobs (replace `https://billing.yourdomain.com` with your live URL):

```cron
# 1. Daily Subscription Renewal & Auto-Invoice Generation (Runs daily at 00:05 AM)
5 0 * * * curl -s -X POST https://billing.yourdomain.com/api/v1/cron/run -H "Content-Type: application/json" -d '{"tenant_id":"ten_softshore","job_type":"subscription_invoicing"}' >/dev/null 2>&1

# 2. Pre-Due (3 Days Before) & Overdue Email/SMS Reminder Dispatcher (Every 15 Minutes)
*/15 * * * * curl -s -X POST https://billing.yourdomain.com/api/v1/cron/run -H "Content-Type: application/json" -d '{"tenant_id":"ten_softshore","job_type":"reminders_and_overdue"}' >/dev/null 2>&1

# 3. Silent General Ledger Queue Processor (Every 5 Minutes)
*/5 * * * * curl -s -X POST https://billing.yourdomain.com/api/v1/cron/run -H "Content-Type: application/json" -d '{"tenant_id":"ten_softshore","job_type":"gl_queue_processor"}' >/dev/null 2>&1
```

---

## Part 3: Step-by-Step Operational Tutorials (Updated for All New Features)

### Tutorial 1: How to Add or Edit a Customer
1. Go to **Customers Directory** (or **CRM & Sales Pipeline** $\rightarrow$ **Customer Directory** tab).
2. Click **`+ Add New Customer`** at the top-right (or fill in the **Add New Customer Profile** card).
3. Enter **Customer / Contact Name**, **Company Name**, **Email**, **Phone (`+880...`)**, **Credit Limit**, **Tax BIN**, and **Opening Advance Balance**.
4. To edit an existing customer at any time, click the **`Edit`** button on their row in the Customer Directory table, update any field, and click **Save Changes**.

### Tutorial 2: How to Add or Edit a Product / Service (with User-Friendly Dropdowns)
1. Navigate to **Products & Services** in the left sidebar.
2. In the **Add Product or Service** form (or by clicking **`Edit`** on any existing row), use the structured dropdowns:
   - **Category Dropdown:** Choose from *SaaS Subscription*, *Cloud & Hosting*, *Software Development*, *IT & Managed Services*, *Cybersecurity & Audit*, *Networking & Bandwidth*, *Hardware & Equipment*, *Annual Maintenance (AMC)*, or select *Custom Category*.
   - **Billing / Measurement Unit Dropdown:** Choose from *Month*, *Year*, *Quarter*, *License*, *User / Seat*, *Instance / VM*, *Unit / Piece*, *Hour*, *Project*, or *Custom Unit*.
   - **VAT / Tax Rate % Dropdown:** Choose `15% (Standard VAT)`, `10%`, `7.5%`, `5%`, `0% (Tax Exempt)`, or custom.
   - **Revenue & COGS GL Account Searchable Dropdowns:** Search and bind the exact Chart of Accounts code (`4100 Service Revenue`, `4000 Product Sales Revenue`, `5000 Cost of Goods Sold`, etc.).

### Tutorial 3: How to Search Subscriptions & Use the Payment Calendar
1. **Search Customer Subscriptions:** Go to **Subscriptions & Cycles**. In the **Active & Paused Customer Subscriptions** header, use the **Search Customer / Plan / Cycle** input box and the **Status Filter (`All`, `Active`, `Paused`)** to filter subscriptions immediately.
2. **Payment Calendar Menu:** Click **Payment Calendar** in the left sidebar under *Billing & Finance*:
   - **Top Monthly Summary Banner:** View the selected month's **Total Invoiced Amount**, **Already Collected Amount**, **Due / Outstanding Amount**, and collection rate progress bar.
   - **Day-Wise Calendar Grid:** Navigate months (`Prev Month`, `Today`, `Next Month`) or filter by Customer/Branch. Click any date cell to inspect that day's invoices, print an invoice copy, or record a payment in 1 click.

### Tutorial 4: How to Use the Customer-Wise Bill Collection Report
1. Click **Bill Collection Report** in the left sidebar under *Billing & Finance*.
2. Filter the report using:
   - **Date Range:** `From Date` and `To Date` (plus quick presets: *This Month*, *This Year*, *All Time*)
   - **Customer Selection:** Searchable Customer Dropdown (`Search by customer name, company, code, or phone`)
   - **Payment Status:** `All Statuses`, `Paid (Fully Collected)`, `Partially Paid`, `Due / Unpaid (Sent + Partial + Overdue)`, or `Overdue Only`
   - **Payment Method / Gateway:** `bKash`, `SSLCommerz`, `Bank EFT`, `Cash`, etc.
3. Switch between **Customer-Wise Summary + Invoice Details**, **Customer Summary Only**, and **Invoice & Payment Details Only**, or click **Export CSV** / **Print Report**.

### Tutorial 5: Capture CRM Leads with Multiple Products, Edit Kanban Leads & Filter Executive Tasks
1. **Capture Lead with Multiple Products:** Go to **CRM & Sales Pipeline**. In **Capture New CRM Lead**, use the **Interested Products / Services (Multiple Choice)** dropdown to attach one or more products/services to the lead.
2. **Edit Any Lead in Kanban (Except Won):** On any Kanban card in `New`, `Contacted`, `Qualified`, `Proposal Sent`, `Negotiation`, or `Lost`, click the **`Edit`** button to modify the lead's details, stage, value, or interested products. Leads in the **`Won`** column are locked (`Won (Locked)`).
3. **Log Interaction / Support Request & Search Descending Timeline:**
   - Switch to the **Interaction Logs & Executive Tasks** tab.
   - Select **multiple company employees** and **multiple company customers**, or toggle **Customer Support / Task Request** to auto-assign the task to **all employees of that company**.
   - Use the **Customer Search Dropdown** and **Priority Filter (`Urgent`, `High`, `Normal`, `Low`)** in the **Timeline & Executive Task Checklist** (which loads in **descending created time** order).

### Tutorial 6: How to Design Your Company's Printed Invoice Copy & Configure Notification Types
1. Go to **Branches, RBAC & Settings**.
2. **Notification Types (Multiple Choice):** Select `Email (SMTP)`, `SMS (BGTel Gateway)`, or both.
3. **Printed Invoice Copy Designer:** Click the **Printed Invoice Copy Designer** tab to customize your company's layout preset (`SoftShore Official Teal Grid`, `Modern Corporate Banner`, or `Classic Executive Bordered`), header/table colors (`#156a83`, `#dbf1f8`), company logo, bank details, and signatory block with live preview.