# ShortcutPlan Platform — Chunk 1 Setup Guide

This is the foundation chunk. After completing this, you'll have:
- CodeIgniter 4 installed on your server
- Database created with migrations run
- Admin login working at `shortcutplan.com/admin`
- Settings page where you can change logo, site name, colors, etc.
- Branding visible on both admin and public pages

---

## STEP 1 — Server Prerequisites

SSH into your VPS and verify these:

```bash
# Check PHP version (must be 8.2+)
php -v

# Check required extensions
php -m | grep -E "intl|mbstring|curl|mysqli|mysqlnd|gd|imagick|zip|xml|bcmath|fileinfo"

# Check Composer
composer --version

# Check MySQL
mysql --version
```

If any extension is missing, enable it via cPanel → Select PHP Version → Extensions.

Required extensions:
- `intl` (CRITICAL — CI4 won't run without this)
- `mbstring`
- `curl`
- `mysqli` and `mysqlnd`
- `gd` or `imagick` (for logo uploads/resizing)
- `zip`
- `xml`
- `bcmath`
- `fileinfo`
- `openssl`

---

## STEP 2 — Create MySQL Database

In cPanel → MySQL Databases:

1. Create a new database. Suggested name: `shortcut_platform` (cPanel will prefix it with your username, so it becomes something like `youruser_shortcut_platform`)
2. Create a new database user. Suggested name: `shortcut_user`
3. Set a strong password — save it somewhere safe
4. Add the user to the database with **ALL PRIVILEGES**

Note down:
- Full DB name (with cPanel prefix)
- Username (with cPanel prefix)
- Password
- Host (usually `localhost`)

---

## STEP 3 — Install CodeIgniter 4 via Composer

SSH into your server and run:

```bash
cd /home/YOURUSER
composer create-project codeigniter4/appstarter shortcutplan
cd shortcutplan
```

This creates `/home/YOURUSER/shortcutplan/` with the full CI4 framework.

Verify it worked:
```bash
php spark
```
You should see the CI4 ASCII logo and command list.

---

## STEP 4 — Point Domain to /public

In cPanel → Domains → Manage:

1. Find `shortcutplan.com`
2. Change Document Root from `public_html` to `/home/YOURUSER/shortcutplan/public`
3. Save

This is critical — it keeps app code, config, and storage outside the web-accessible folder.

---

## STEP 5 — Configure .env File

```bash
cd /home/YOURUSER/shortcutplan
cp env .env
nano .env
```

Set these values (uncomment by removing `#`):

```ini
CI_ENVIRONMENT = production

app.baseURL = 'https://shortcutplan.com/'
app.indexPage = ''
app.forceGlobalSecureRequests = true

# Session settings
session.driver = 'CodeIgniter\Session\Handlers\FileHandler'
session.savePath = WRITEPATH . 'session'

# Database
database.default.hostname = localhost
database.default.database = YOURUSER_shortcut_platform
database.default.username = YOURUSER_shortcut_user
database.default.password = YOUR_DB_PASSWORD_HERE
database.default.DBDriver = MySQLi
database.default.DBPrefix =
database.default.port = 3306

# Encryption (generate a 32-byte hex string)
encryption.key = hex2bin:GENERATE_THIS_NEXT_STEP

# Email handler will be configured via the admin Settings page later
```

Generate the encryption key:
```bash
php spark key:generate
```
This automatically writes the key to your `.env`.

---

## STEP 6 — Install Required Composer Packages

```bash
cd /home/YOURUSER/shortcutplan
composer require codeigniter4/shield
composer require stripe/stripe-php
```

---

## STEP 7 — Drop In Custom Application Code

Upload the contents of the `custom/` folder from this delivery into your CI4 installation.

The structure mirrors CI4's, so it's a direct merge:

```
custom/app/        →  /home/YOURUSER/shortcutplan/app/
custom/public/     →  /home/YOURUSER/shortcutplan/public/
custom/storage/    →  /home/YOURUSER/shortcutplan/storage/
```

**Method via cPanel:** zip the `custom` folder, upload via File Manager, extract, then move the contents into the matching folders.

**Method via SSH:** rsync or scp the files up.

After upload, set permissions:
```bash
cd /home/YOURUSER/shortcutplan
chmod -R 755 writable/ storage/
chown -R YOURUSER:YOURUSER writable/ storage/
```

---

## STEP 8 — Run Migrations

```bash
cd /home/YOURUSER/shortcutplan

# Shield's auth migrations
php spark shield:setup

# Our custom migrations (settings table, etc.)
php spark migrate
```

You should see output like:
```
Running all new migrations...
Running: 2026-01-01-000001_CreateSettingsTable
Done migrations.
```

---

## STEP 9 — Create First Admin User

```bash
php spark shield:user create
```

When prompted:
- Username: `admin`
- Email: `admin@shortcutplan.com`
- Password: choose a strong one

Then assign admin role:
```bash
php spark shield:user addgroup admin@shortcutplan.com admin
```

---

## STEP 10 — Seed Default Settings

```bash
php spark db:seed DefaultSettingsSeeder
```

This populates the settings table with starting values for:
- site_name = "ShortcutPlan"
- primary_color = "#2563eb"
- support_email = "support@shortcutplan.com"
- (and placeholder values for Stripe, Elastic Email, Meta Pixel — you'll fill these via the admin later)

---

## STEP 11 — Verify Everything Works

1. Visit `https://shortcutplan.com/` → should show a basic public page with "ShortcutPlan" branding
2. Visit `https://shortcutplan.com/admin` → should show login page
3. Log in with the admin user from Step 9
4. Should redirect to admin dashboard
5. Click Settings → change site name to test
6. Refresh public homepage → new site name should appear

---

## Troubleshooting

**500 error on first load:**
- Check `writable/logs/log-YYYY-MM-DD.log`
- Most common: missing `intl` extension or wrong DB credentials

**"Class CodeIgniter\Shield not found":**
- Run `composer dump-autoload`

**Migration errors:**
- Check DB user has ALL PRIVILEGES on the database
- Check `.env` DB credentials are correct

**Blank page:**
- Set `CI_ENVIRONMENT = development` temporarily in `.env` to see actual error

---

## What's Next (Chunk 2)

Once Chunk 1 is verified working, we move to:
- Stripe API key configuration (test + live mode toggle)
- Elastic Email API key configuration
- Meta Pixel + CAPI configuration
- Logo upload with image validation
- All accessible from the admin Settings page