Imported from HazemDesign/Baladi-App (Backend/BALADI-GRADUATION-PROJECT/AGENTS.md). Install upstream with npx skills add HazemDesign/Baladi-App --skill BALADI-GRADUATION-PROJECT. Copyright stays with the author.

BALADI-GRADUATION-PROJECT - AGENTS.md

Project Overview

• Framework: Laravel 12 (PHP 8.3.16)
• Database: SQLite (local), MySQL (production)
• Admin Panel: Blade templates with Tailwind CSS (CDN)
• API: RESTful endpoints for Flutter mobile app

Critical Commands

• Start server: php artisan serve --host=127.0.0.1 --port=8000
• Run migrations: php artisan migrate
• Seed database: php artisan db:seed
• Clear cache: php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear

File Structure

• Routes: routes/web.php (redirects to login), routes/admin.php (all admin routes)
• Admin Controllers: app/Http/Controllers/Admin/
• API Controllers: app/Http/Controllers/Api/
• Views: resources/views/admin/
• Layout: resources/views/admin/layouts/app.blade.php
• Translations: lang/ar.json, lang/en.json (JSON format, used with __('key'))

Key Conventions

• Language: Session-based via SetAdminLocale middleware, default Arabic
• RTL/LTR: Auto-switched based on language — Arabic = RTL (right sidebar), English = LTR (left sidebar)
• Dark theme: bg-gray-900 base, Tailwind dark colors throughout
• Font: Cairo (Google Fonts)
• City-scoped access: Admins can only access reports from assigned governorates via FiltersByAdminGovernorates trait
• Severity values: Low, Medium, High, Critical (NOT pending)
• Status values: pending, in_progress, resolved, rejected

SQLite Compatibility

When writing raw SQL queries, always check the driver:

$driver = DB::connection()->getDriverName();
if ($driver === 'sqlite') {
    // Use strftime(), julianday()
} else {
    // Use YEAR(), MONTH(), TIMESTAMPDIFF()
}

Admin Routes (from routes/admin.php)

• Auth: /admin/login, /admin/logout
• Dashboard: /admin/dashboard, /admin/dashboard/ai-insights, /admin/dashboard/export-reports
• Resources: reports, categories, users, notifications, comments
• Settings: /admin/settings (GET), /admin/settings (POST)
• Super Admin only: governorates, admins
• Export routes always defined BEFORE resource routes (e.g., reports/export before reports/{report})

Sidebar Behavior

• Desktop expanded: 16rem width, icons + labels visible
• Desktop mini: 4rem width, icons centered, labels hidden
• Mobile: Full overlay sidebar, tap overlay to close
• Toggle button: Always in header bar — switches between full ↔ mini on desktop
• State saved: localStorage key adminSidebarMode (values: full, mini, closed)
• Settings page: /admin/settings — choose sidebar state (full/mini) + language (Arabic/English)
• Sidebar position: Auto-flips with language — Arabic = right, English = left

Session Keys

• admin_language — 'ar' or 'en'
• admin_sidebar_state — 'full' or 'mini'

Middleware

• admin_locale — Sets App::setLocale() from session admin_language
• admin — Checks user has admin role
• super_admin — Checks user has admin role (full access)

Known Gotchas

1. Never put pending in severity validation rules — it's a status, not severity
2. Export routes must be registered before resource routes to avoid route conflicts
3. ReportController@store has extensive AI image analysis fallback logic — do not simplify
4. Cache::remember() closures must capture $driver via use ($driver) when containing SQLite-specific queries
5. Use __('key') for translations — keys are in lang/{ar,en}.json
6. The admin_locale middleware is applied to the entire admin route prefix group