# CoreGrand — Complete Setup Guide (Namecheap cPanel)

This walks you through everything, start to finish, in plain language. Follow it
in order and you won't miss a step. Total time: about 20–30 minutes.

Two reminders before you start:
- You only have to create the **database (an empty shell) and a database user**
  by hand. The app **creates all the tables by itself** the first time it runs.
- Keep the app on **https://** (secure). cPanel gives you free SSL.

---

## PART A — Log in to cPanel

1. Go to your Namecheap account ▸ **Dashboard** ▸ your hosting **Manage** ▸
   **cPanel** (or visit `https://yourdomain.ca/cpanel` and log in).
2. You'll see the cPanel home with sections like *Files*, *Databases*, *Domains*.

---

## PART B — Create the database and user (the only manual DB step)

1. In cPanel, under **Databases**, click **MySQL® Databases**.
2. **Create New Database**: type a name, e.g. `coregrand_books`, click **Create
   Database**.
   - cPanel adds your account prefix automatically, so the real name becomes
     something like `cpaneluser_coregrand_books`. **Write down the full name.**
3. Scroll to **MySQL Users ▸ Add New User**: enter a username (e.g.
   `coregrand_app`) and click **Password Generator** to make a strong password.
   **Copy the full username and password somewhere safe.** Click **Create User**.
4. Scroll to **Add User To Database**: pick your new user and your new database,
   click **Add**. On the next screen tick **ALL PRIVILEGES**, then **Make
   Changes**.

You now have: a database name, a database user, and that user's password. That's
all the app needs.

---

## PART C — Upload the files

1. In cPanel ▸ **Files** ▸ **File Manager**, open **public_html** (your website's
   web root). If CoreGrand will live on a subdomain (e.g. `books.yourdomain.ca`),
   open that subdomain's folder instead.
2. Click **Upload** and upload the contents of the project:
   - `index.html`
   - the `assets/` folder (css, js, img)
   - the `backend/` folder
3. After uploading the zip you can use **Extract** in File Manager to unzip it,
   then move files so the structure is:
   ```
   public_html/
   ├── index.html
   ├── assets/...
   └── backend/...
   ```

---

## PART D — Turn on HTTPS (free SSL)

1. cPanel ▸ **Security** ▸ **SSL/TLS Status**.
2. Select your domain, click **Run AutoSSL**. Wait a minute; it should show a
   green lock. Now `https://yourdomain.ca` works.

---

## PART E — Configure the backend (edit one file)

1. In File Manager, open `backend/config.php` ▸ right-click ▸ **Edit**.
2. Fill in the four things you saved earlier and pick two secrets:
   ```php
   'db' => [
     'host' => 'localhost',
     'name' => 'cpaneluser_coregrand_books',   // your full DB name
     'user' => 'cpaneluser_coregrand_app',     // your full DB user
     'pass' => 'THE_DB_PASSWORD_YOU_COPIED',
     'charset' => 'utf8mb4',
   ],
   'app' => [
     'name' => 'CoreGrand Group Inc.',
     'base_currency' => 'CAD',
     'cors_origin' => 'https://yourdomain.ca',  // the EXACT app address (or subdomain)
     'app_secret' => 'paste-a-long-random-string-here',
     'install_token' => 'another-random-string',
     'initial_admin_password' => 'ChooseAStrongAdminPassword',  // first admin login
   ],
   ```
   Tip for random strings: mash the keyboard for 30+ characters, or use any
   password generator.
3. **Save** the file.

---

## PART F — First run: the app builds its own tables

1. Visit your app: `https://yourdomain.ca` (or your subdomain).
2. The first time the backend is contacted, it automatically:
   - creates every database table,
   - seeds CAD currencies, the parent company + sample trade names, the chart of
     accounts and default Canadian taxes,
   - creates the **System Administrator** account
     (email `admin@coregrand.local`, password = the `initial_admin_password` you
     set in config.php).
3. Sign in as **System Administrator** with that password. Done — you're live.

> You do not need to run anything by hand. (An optional `install.php` is included
> if you ever want to trigger setup manually; if you use it, delete it afterand.)

---

## PART G — Live vs Demo

- On the sign-in screen there's a **Mode** selector:
  - **Live** — your real, private company data.
  - **Demo** — a safe learning sandbox with sample data. Anything you do here
    never touches Live, and a **Reset demo data** button restores the samples.
- Both modes share the same features, so every future update appears in both.
- Use Demo to train staff; switch to Live for real work.

---

## PART H — First things to do as the administrator

1. **Change the admin password** (account menu ▸ Change my password).
2. **Add your real users** (Admin Console ▸ Add user): set each person's name,
   role, email and a starting password. They can change it later.
3. **Review the permission matrix** (Users & Roles): click any dot to grant or
   remove a permission for a role. The system won't let you lock out the last
   administrator.
4. **Set tax rates** (Tax Centre) — confirm the correct Canadian federal and
   provincial rates with your accountant.
5. **Add your trade names** (Entities) and **targets** (Management Insight).

---

## PART I — Connect trade-name apps (optional, later)

Each external app (POS, billing, etc.) posts sales into the books over the API
using a per-entity key. Create keys in the `api_keys` table (or ask me to add a
small admin screen for it), then the app calls:

```
POST https://yourdomain.ca/backend/api/transactions
Authorization: Bearer <entity_api_key>
{ "date":"2026-06-20", "source":"GrandFresh POS", "memo":"Daily batch",
  "lines":[ {"account":"1000","debit":250000}, {"account":"4000","credit":250000} ] }
```

---

## If something goes wrong

- **Blank page / "Server error"**: re-check the four `db` values in config.php
  (a wrong DB name/user/password is the usual cause).
- **Can't log in from the browser**: make sure `cors_origin` in config.php is the
  EXACT address shown in your browser's address bar, including `https://`.
- **Emails not arriving**: bare cPanel mail often goes to spam — see
  `backend/README.md` for switching to your domain's SMTP (recommended).
- Still stuck? Tell me the exact message on screen and I'll pinpoint it.