perling/.github/copilot-instructions.md

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.