# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**MyHIJAU** is a Laravel 11 application that manages Malaysia's green technology certification platform. It's a comprehensive certification management system for environmentally friendly products and services, serving multiple user roles including companies, evaluators, administrators, and the public.

## Common Development Commands

### Setup & Environment
```bash
# Initial setup
composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate:fresh --seed

# Daily development
npm run watch          # Watch frontend assets (Terminal 1)  
php artisan serve      # Development server (Terminal 2)
```

### Database Operations
```bash
php artisan migrate              # Run migrations
php artisan migrate:fresh --seed # Fresh setup with data
php artisan db:seed             # Run all seeders
```

### Frontend Build Commands
```bash
npm run dev         # Development build
npm run watch       # Watch for changes
npm run production  # Production build
```

### Testing & Code Quality
```bash
vendor/bin/phpunit              # Run all tests
vendor/bin/phpunit --testsuite=Unit     # Unit tests only
vendor/bin/phpunit --testsuite=Feature  # Feature tests only
vendor/bin/pint                 # Format code with Laravel Pint
```

### Custom Artisan Commands
```bash
php artisan application:check-expiry          # Check expired applications
php artisan application:pay-later-reminder    # Payment reminders
php artisan events:send-confirmations         # Event confirmation emails
```

## Architecture Overview

### Core Business Modules
- **Application Management**: Multi-stage certification workflow (Draft → Screening → Evaluation → Approval → Published)
- **Company Management**: Company profiles, multi-user support, role-based access
- **Evaluation System**: Role-specific evaluation interfaces with complex workflow
- **Payment Management**: Payment verification, invoicing, receipt handling  
- **Event Management**: Training events with QR code attendance and certificates
- **Content Management**: Landing pages, banners, news, testimonials

### User Roles & Permissions
The application uses Spatie Laravel Permission package with these key roles:
- **Super Admin/Admin**: Full system access
- **Screening Officers**: Initial application review
- **Evaluators** (Junior/Senior): Application evaluation
- **Project Leader/Director**: Oversight and approval
- **Finance Officers**: Payment processing
- **Company Users**: Submit and manage applications

### Key Models & Relationships
- `Application` - Core certification applications with complex status workflow
- `Company` - Company profiles with multiple users
- `User` - Multi-role users with permissions
- `Payment` - Payment tracking and verification
- `Event` - Training events and workshops
- `ProductGroup` - Hierarchical product categorization

### Database Design Patterns
- Role-based access control with company segregation
- Complex state machine for application status transitions  
- Audit logging through application_logs table
- Hierarchical product/service categorization
- Geographic data (states, countries) for address management

### Frontend Architecture
- **Blade Templates**: Component-based with multiple layouts (auth, default, system, event)
- **KT Metronic Theme**: Bootstrap-based admin theme with custom styling
- **JavaScript Stack**: jQuery, DataTables, ApexCharts, CKEditor, SweetAlert2
- **Asset Compilation**: Laravel Mix with custom theme build tools

### Key Development Patterns
- Repository pattern (implicit) with domain-organized controllers
- Form Request classes for validation
- Model Observers for business logic (application numbering, logging)
- Service classes for complex business operations
- Resource Controllers following RESTful conventions

## File Organization

```
app/
├── Http/Controllers/
│   ├── Apps/         # Admin functionality
│   ├── Company/      # Company-specific features  
│   ├── Evaluation/   # Evaluation workflow
│   ├── Settings/     # Content management
│   └── Auth/         # Authentication
├── Models/           # Eloquent models with complex relationships
├── Middleware/       # Role-based access control
├── Console/Commands/ # Custom artisan commands
└── Services/         # Business logic services

resources/
├── views/           # Blade templates organized by module
├── _keenthemes/     # Theme framework assets
└── js/css/          # Custom frontend assets
```

## Development Guidelines

### Authentication & Authorization
- All routes protected by role-based middleware
- Company data segregation enforced at model level
- Multi-role users require careful permission checking
- First-time login flow handled by custom middleware

### Application Workflow
The certification process follows a strict state machine:
1. **Draft** → Company creates application
2. **Screening** → Initial review by screening officers  
3. **Evaluation** → Multi-stage evaluation by junior/senior evaluators
4. **Leadership Review** → Project leader and director approval
5. **Admin Approval** → Final administrative approval
6. **Published** → Certificate issued and publicly listed

### Testing Structure
- Feature tests for application workflows and user interactions
- Unit tests for models and business logic
- Database factories available for all major models
- Test environment configured with in-memory database

### Common Patterns to Follow
- Use Form Request classes for complex validation
- Implement model scopes for data filtering by company/role
- Follow the existing controller organization by business domain
- Use the helper functions in `app/Helpers/Helpers.php`
- Maintain the status transition logging for audit purposes

## Key Dependencies
- **Livewire 3.5**: For reactive UI components
- **Spatie Laravel Permission**: Role-based access control
- **Laravel Excel**: Import/export functionality
- **DomPDF**: PDF generation for certificates and reports
- **Laravel Socialite**: Social authentication
- **Yajra DataTables**: Server-side data tables

## Before Deploying
```bash
vendor/bin/pint        # Format code
vendor/bin/phpunit     # Run tests
npm run production     # Build production assets
php artisan config:cache
php artisan route:cache
php artisan view:cache
```