# Orion Innovation

Laravel 12 + React SPA for the Orion Innovation public site and admin CMS. The public frontend is a React application served by Laravel; the admin panel lives at `/secure-access` and uses a Laravel Passport–protected REST API.

## Stack

| Layer | Technology |
|-------|------------|
| Backend | PHP 8.2+, Laravel 12 |
| Frontend | React 18, TypeScript, Vite, Tailwind CSS |
| Database | MySQL |
| Auth (admin) | Laravel Passport (OAuth2 bearer tokens) |
| Queue / cache / sessions | Database-driven by default |

## Server requirements

- PHP **8.2+** with extensions: `bcmath`, `ctype`, `curl`, `dom`, `fileinfo`, `json`, `mbstring`, `openssl`, `pdo`, `pdo_mysql`, `tokenizer`, `xml`
- **Composer** 2.x
- **Node.js** 18+ and **npm** (required on the build machine only)
- **MySQL** 8.x (or compatible)

---

## Production setup

### 1. Clone and install dependencies

```bash
git clone <repository-url> orioninnovation-azure
cd orioninnovation-azure

composer install --no-dev --optimize-autoloader
npm ci
```

### 2. Environment configuration

Copy the example env file and configure production values:

```bash
cp .env.example .env
```

Edit `.env` with at least the following:

```dotenv
APP_NAME="Orion Innovation"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_secure_password

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database
LOG_LEVEL=error
```

Generate the application key:

```bash
php artisan key:generate
```

#### Vite / frontend variables (build time)

These values are embedded during `npm run build`. Set them in `.env` **before** building:

```dotenv
VITE_APP_NAME="${APP_NAME}"
VITE_API_URL=
VITE_API_URL_ORION=https://app-orion-api-stg-eus-01.azurewebsites.net/api
VITE_ADMIN_API_URL=
VITE_ENCRYPT_KEY_1=
VITE_ENCRYPT_KEY_2=
VITE_ENCRYPT_KEY_3=
```

| Variable | Description |
|----------|-------------|
| `VITE_API_URL` | Base URL for Laravel public API calls (`/api/site-settings`, page preview, etc.). Leave empty when the API is served from the same domain (recommended). |
| `VITE_API_URL_ORION` | Base URL for the external Orion API. Endpoint path and HTTP method are configured on the grade family guides API component. |
| `VITE_ADMIN_API_URL` | Base URL for admin API calls. Leave empty for same-origin deployment. |
| `VITE_ENCRYPT_KEY_1/2/3` | Required for encrypted API responses in the admin panel. Must match the keys expected by the backend. |

> **Important:** Changing any `VITE_*` variable requires running `npm run build` again and redeploying `public/build/`.

### 3. Build frontend assets

```bash
npm run build
```

This compiles the public SPA (`resources/js/entry.tsx`) and admin panel (`resources/js/admin/entry.tsx`) into `public/build/`.

Ensure `public/hot` does **not** exist in production (remove it if present from local development).

### 4. Database setup

Create the MySQL database, then run migrations and seed initial data:

```bash
php artisan migrate --force
php artisan db:seed --force
```

The seeder creates a default admin user (`test@example.com` / `password`) and component data. **Change or replace this account before going live.**

### 5. Laravel Passport (admin authentication)

Install Passport encryption keys and OAuth clients:

```bash
php artisan passport:install --force
```

Passport keys are stored in `storage/`. Back them up and ensure the directory is writable by the web server.

Alternatively, set keys via environment variables:

```dotenv
PASSPORT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
PASSPORT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."
```

### 6. File permissions

Ensure the web server can write to:

- `storage/`
- `bootstrap/cache/`

Example (Linux):

```bash
chown -R www-data:www-data storage bootstrap/cache
chmod -R ug+rwx storage bootstrap/cache
```

### 7. Optimize Laravel for production

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
```

After any `.env` change, clear and rebuild caches:

```bash
php artisan config:clear && php artisan config:cache
```

### 8. Queue worker
 
The app uses the database queue driver. Run a persistent worker in production:

```bash
php artisan queue:work --tries=3 --timeout=90
```

Use **Supervisor**, **systemd**, or your hosting platform's process manager to keep the worker running.

### 9. Verify deployment

| Check | URL / command |
|-------|---------------|
| Health endpoint | `GET /up` |
| Public site | `https://your-domain.com` |
| Admin panel | `https://your-domain.com/secure-access` |
| Public API | `GET /api/site-settings` |
| Admin login | `POST /api/admin/login` |

---

## Application routes

| Path | Purpose |
|------|---------|
| `/` | Public React SPA |
| `/secure-access` | Admin CMS (React) |
| `/api/site-settings` | Public site settings |
| `/api/pages/preview/{slug}` | Page preview |
| `/api/admin/*` | Protected admin API (Bearer token) |

---

## Local development (reference)

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan passport:install
npm install
composer dev
```

`composer dev` starts the Laravel server, queue listener, and Vite dev server concurrently.

Or run separately:

```bash
php artisan serve
php artisan queue:listen
npm run dev
```

---

## Deployment checklist

- [ ] `APP_ENV=production`, `APP_DEBUG=false`
- [ ] Strong `APP_KEY` and database credentials
- [ ] `npm run build` executed with correct `VITE_*` values
- [ ] `public/hot` removed
- [ ] Migrations run (`php artisan migrate --force`)
- [ ] Passport keys installed
- [ ] Default admin password changed
- [ ] Laravel caches built (`config:cache`, `route:cache`, `view:cache`)
- [ ] Queue worker running
- [ ] `storage/` and `bootstrap/cache/` writable
- [ ] HTTPS enabled