# Copilot Instructions for AI Agents

## Project Overview

-   This is a Laravel-based web application for managing perizinan (permits), with a normalized database structure and dashboard analytics.
-   Key entities: `Kategori`, `DashboardPerizinan`, `TerakhirTerbit`, `IzinTercepat`, with relations enforced via foreign keys and PascalCase field names.
-   Data flows from database to dashboard/API endpoints, with helpers mapping string names to KategoriID and providing DB fallback.

## Architecture & Data Flow

-   **Controllers** (e.g., `app/Http/Controllers/DashboardController.php`): Handle API/dashboard requests, use helpers for data formatting, always query DB (no static arrays).
-   **Helpers** (e.g., `app/Helpers/DashboardHelper.php`): Accept string kategori, map to KategoriID, query DB for fallback, output in PascalCase.
-   **Models** (e.g., `app/Models/Kategori.php`): Eloquent models with explicit relations; always use PascalCase for DB fields.
-   **Migrations** (e.g., `database/migrations/`): Define normalized schema, foreign keys, and PascalCase columns.
-   **Seeders** (e.g., `database/seeders/DatabaseSeeder.php`): Populate Kategori and other reference tables.

## Developer Workflows

-   **Build/Serve**: Use `php artisan serve` for local dev; assets via Vite (`npm run dev`).
-   **Sync Data**: Run `php artisan perizinan:sync --all` to sync all permit data (used in cronjobs).
-   **Testing**: Use `php artisan test` for PHPUnit tests in `tests/Feature` and `tests/Unit`.
-   **Cronjob**: On server, set up cron to run sync command regularly (see shell script in docs).

## Conventions & Patterns

-   **PascalCase**: All DB fields, model properties, and API outputs use PascalCase.
-   **String-to-ID Mapping**: Helpers accept string kategori, map to KategoriID, fallback to DB if not found.
-   **No Static Arrays**: All dashboard/API data must come from DB, not hardcoded arrays.
-   **Frontend Data Import**: Use window variables for initial chart data, AJAX for dynamic updates (see `resources/js/homeOneChart.js`).

## Integration Points

-   **External**: Uses Laravel packages (see `composer.json`), e.g., `barryvdh/laravel-dompdf` for PDF generation.
-   **Frontend**: Blade templates in `resources/views/`, JS in `resources/js/`.
-   **Database**: SQLite for local dev (`database/database.sqlite`).

## Key Files & Directories

-   `app/Helpers/DashboardHelper.php`: Helper logic for dashboard data
-   `app/Http/Controllers/DashboardController.php`: Main dashboard/API controller
-   `app/Models/Kategori.php`: Kategori model (ensure correct namespace)
-   `database/migrations/`: All migration files
-   `database/seeders/DatabaseSeeder.php`: Seeder logic
-   `resources/js/homeOneChart.js`: Frontend chart integration
-   `routes/web.php`: Route definitions

## Example Patterns

-   Helper usage: `DashboardHelper::getSummaryByKategori('Pertek')` (maps to KategoriID, queries DB)
-   Controller usage: `$data = DashboardHelper::getSummaryByKategori($kategoriString);`
-   Cronjob: `* * * * * cd /path/to/project && php artisan perizinan:sync --all >> /dev/null 2>&1`

---

If any conventions or workflows are unclear, please ask for clarification or examples from the codebase.