# AGENTS.md ## Project Identity This repository is the active Laravel CMS for the Higher Ground Academy website. - Active local project path: `C:\xampp\htdocs\hgaacademy-cms` - Original static template/reference only: `C:\Users\Sabir Patel\dev\hgaacademy\hga-website V2.0` - Live test site: `https://hgav1.3as.us` - Live admin: `https://hgav1.3as.us/admin/login` - InMotion server project root: `/home/nasus05/hgav1.3as.us` - Required production document root: `/home/nasus05/hgav1.3as.us/public` Always edit the XAMPP Laravel project, not the old static template folder. ## Tech Stack - Laravel 12 - PHP 8.3 on InMotion, XAMPP PHP locally - Blade templates - Custom admin/CMS, not Filament - MySQL - Public storage via `php artisan storage:link` ## Local Workflow Use PowerShell from: ```powershell C:\xampp\htdocs\hgaacademy-cms ``` Useful commands: ```powershell & 'C:\xampp\php\php.exe' artisan test & 'C:\xampp\php\php.exe' artisan migrate & 'C:\xampp\php\php.exe' artisan optimize:clear ``` Before finishing work: ```powershell git status --short --branch & 'C:\xampp\php\php.exe' artisan test git add git commit -m "" git push origin main ``` ## Production Deploy Commands Run on InMotion bash: ```bash cd ~/hgav1.3as.us git pull origin main composer install --no-dev --optimize-autoloader php artisan migrate --force php artisan optimize:clear php artisan config:clear php artisan route:clear php artisan view:clear php artisan storage:link ``` If `php artisan storage:link` says the link already exists, that is okay. ## Admin Auth Admin login is custom and reads credentials from `.env`. Relevant files: - `app/Http/Controllers/Admin/AuthController.php` - `app/Http/Middleware/AdminAuthenticated.php` - `config/admin.php` Important: - Do not hard-code admin credentials. - Admin credentials are `ADMIN_EMAIL` and `ADMIN_PASSWORD` in `.env`. ## Main Public Routes Defined in `routes/web.php`. - `/` - `/about` - `/academics` - `/admissions` - `/news-events` - `/documents` - `/external-links` - `/building-company` - `/contact` Legacy static-template redirects are also defined in `routes/web.php`. ## Admin Sections Current admin sections: - Pages: `/admin/pages` - News & Events: `/admin/news-events` - Documents: `/admin/documents` - External Links: `/admin/external-links` - Emergency Alert: `/admin/emergency-alert` - School Calendar shortcut: `/admin/school-calendar` Admin layout and shared styles live in: - `resources/views/layouts/admin.blade.php` The admin UI has intentionally been made compact and web-app-like. Keep new admin screens tight: small controls, compact tables, icon actions, minimal card nesting. ## Pages CMS Editable page records live in the `pages` table. Important fields: - `title` - `slug` - `meta_title` - `meta_description` - `content` - `hero_image` - `sections` - `is_published` Homepage sections use `pages.sections` JSON. The homepage currently uses: - `sections.emergency` - `sections.calendar` Page admin: - Controller: `app/Http/Controllers/Admin/PageController.php` - Views: `resources/views/admin/pages/` ## Emergency Alert Emergency Alert is an independent admin screen: - Admin URL: `/admin/emergency-alert` - Controller: `app/Http/Controllers/Admin/EmergencyAlertController.php` - View: `resources/views/admin/emergency-alert/edit.blade.php` It still stores data in the home page `sections.emergency` JSON so the homepage can render it without another table. Public rendering: - `resources/views/home.blade.php` - CSS in `public/css/components.css` The public alert was made intentionally prominent with high-contrast red styling. ## School Calendar Calendar editing remains inside the Home page editor, with a shortcut route: - `/admin/school-calendar` It redirects to the Home page editor anchor: - `#school-calendar-editor` Calendar data is stored in `pages.sections.calendar`. It supports separate Google Calendar embeds for: - Elementary - Middle - High Public calendar CTA links open in a new tab. ## News & Events News and Events are combined into one admin and one public list. Admin: - Controller: `app/Http/Controllers/Admin/NewsEventController.php` - Views: `resources/views/admin/news-events/` Public: - Controller: `app/Http/Controllers/NewsEventsController.php` - Route: `/news-events` Fields: - title - rich description/body - optional image - optional PDF - featured checkbox Ordering: - Featured first - Then newest created descending Homepage shows featured News & Events cards. ## Document Store Document Store supports two levels: - Category - Subcategory Database: - Model: `app/Models/Document.php` - Migration added: `database/migrations/2026_08_03_000001_add_subcategory_to_documents_table.php` Admin: - Controller: `app/Http/Controllers/Admin/DocumentController.php` - Views: `resources/views/admin/documents/` - Route: `/admin/documents` Admin create flow is bulk upload: - Select or create Category - Subcategory dropdown filters based on selected Category - Select or create Subcategory - Upload multiple PDFs - Title defaults to file name - Description defaults to file name, but can be edited before upload Admin document index includes instant client-side search across: - title - description - category - subcategory - PDF path Public: - Controller: `app/Http/Controllers/DocumentStoreController.php` - View: `resources/views/pages/documents/index.blade.php` - JS: `public/js/document-store.js` - Route: `/documents` Public behavior: - No "All" category option - First category is active by default - No "All" subcategory option - First subcategory in the active category is active by default - This is intentional because there may be many documents ## External Links External Links is a public portal shortcut page controlled by admin. Database: - Model: `app/Models/ExternalLink.php` - Migration: `database/migrations/2026_08_03_000002_create_external_links_table.php` Admin: - Controller: `app/Http/Controllers/Admin/ExternalLinkController.php` - Views: `resources/views/admin/external-links/` - Route: `/admin/external-links` Fields: - title - description - external URL - optional icon upload - sort order - active checkbox Public: - Controller: `app/Http/Controllers/ExternalLinksController.php` - View: `resources/views/pages/external-links/index.blade.php` - Route: `/external-links` Public links open in a new tab with `rel="noopener noreferrer"`. If no icon is uploaded, the public card shows an initials fallback. ## Public Navigation Header component: - `resources/views/components/site-header.blade.php` Current nav includes: - Home - About - Academics - Admissions - News & Events - Documents - External Links - Building Company - Contact Be careful adding more top-level nav items because the header can get crowded. ## Styling Notes Main public CSS: - `public/css/components.css` - `public/css/pages.css` - `public/css/responsive.css` Admin CSS is inline in: - `resources/views/layouts/admin.blade.php` Recent design direction: - Keep public design visually consistent with the HGA theme. - Do not rewrite the design unless needed. - Admin should be compact, modern, and efficient. - Use small icon action buttons in admin tables. - Avoid bulky cards or large controls in admin workflows. ## Testing Current feature tests cover: - Admin page editing - Emergency Alert - Calendar shortcut and Google Calendar URL normalization - News & Events - Documents category/subcategory and bulk upload - Admin document search - External Links Run all tests before committing: ```powershell & 'C:\xampp\php\php.exe' artisan test ``` ## Compliance Context This is a public school website CMS, not a student information system. Do not add storage for student records, grades, health records, parent private data, discipline data, or other FERPA/MGDPA-sensitive information without a separate privacy/security design. For school compliance, future work should consider: - Role-based admin access - Audit logs - Stronger admin user management - File upload scanning/restrictions - Accessibility checks for uploaded PDFs - Privacy notices for any forms ## Git Notes Repository: - `origin` should point to `https://github.com/sabirpatel/hgaacademy-cms-laravel.git` - Main branch: `main` The project was renamed locally to HGA Academy V2 in metadata, but the active folder remains: ```txt C:\xampp\htdocs\hgaacademy-cms ``` Do not use destructive git commands such as `git reset --hard` unless the user explicitly asks.