# Installation Guide

## Requirements
- PHP 8.3+
- Composer 2.x
- MySQL 8+ or PostgreSQL 14+
- Node.js 18+ (only if compiling frontend assets beyond the inline-CSS Blade views included)

## Local setup

```bash
composer create-project laravel/laravel school-portal "12.*"
cd school-portal

composer require laravel/sanctum barryvdh/laravel-dompdf simplesoftwareio/simple-qrcode

# Copy this package's files into the new project, preserving paths:
#   database/migrations/*  →  database/migrations/
#   database/seeders/*      →  database/seeders/
#   app/Models/*             →  app/Models/
#   app/Services/*            →  app/Services/
#   app/Http/Controllers/*     →  app/Http/Controllers/
#   app/Http/Middleware/*       →  app/Http/Middleware/
#   resources/views/*            →  resources/views/
#   routes/web.php, routes/api.php  →  routes/  (overwrite the defaults)

cp .env.example .env
php artisan key:generate
```

Edit `.env`:
```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=school_portal
DB_USERNAME=root
DB_PASSWORD=

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=

# Not read automatically — these are read via SystemSetting::get() per
# school instead, but you can seed sensible defaults here if preferred.
```

Register the `role` middleware alias in `bootstrap/app.php` — see
`routes/bootstrap_app_middleware_snippet.php` in this package for the
exact snippet.

```bash
php artisan storage:link
php artisan migrate
php artisan db:seed --class=Database\\Seeders\\RoleSeeder
php artisan db:seed --class=Database\\Seeders\\DemoDataSeeder   # optional demo data

php artisan serve
```

Visit `http://localhost:8000` for the public site, `/login` for the
dashboard. Demo login (if you ran `DemoDataSeeder`):
`[email protected]` / `Password123!` — **change this immediately in
production.**

## Production deployment (outline)

This package gives you the application code. Production readiness also
requires infrastructure decisions specific to your host — outlined here,
not something a code package can hand you finished:

1. **Web server**: Nginx + PHP-FPM (or a managed platform like Laravel
   Forge / Vapor). Point the document root at `public/`.
2. **Queue worker**: `php artisan queue:work` under Supervisor, for
   anything you move to `ShouldQueue` (email sending, SMS dispatch, PDF
   generation on demand).
3. **Scheduler**: add `* * * * * php artisan schedule:run` to cron —
   needed for any scheduled tasks (e.g. daily attendance digest, backup
   jobs) you add via `routes/console.php`.
4. **Backups**: install `spatie/laravel-backup`, configure a disk
   (S3/Backblaze), schedule `php artisan backup:run` daily.
5. **Caching**: set `CACHE_STORE=redis` and `SESSION_DRIVER=redis` in
   production for real concurrency — file-based caching doesn't scale
   past a single server.
6. **HTTPS**: mandatory — student data, payment references, and
   documents with QR verification links all need to be served over TLS.
7. **Environment**: `APP_ENV=production`, `APP_DEBUG=false` — never
   expose stack traces to end users.

## Payment gateway setup

Add your Paystack/Flutterwave/Monnify secret keys via the Settings
screen (`/settings`, stored per-school in `system_settings`), then
implement the webhook handler each provider requires — verify the
signature, then call `FinanceService::recordPayment()` with the matched
invoice. This isn't included because it needs your actual merchant
account and webhook secret to test against.