# ERP Project - Qwen Code Context

## Project Overview

This is a Laravel-based Enterprise Resource Planning (ERP) system built with modern web technologies. The application follows the Laravel framework conventions and incorporates Vue 3 with Inertia.js for the frontend, providing a seamless single-page application experience.

### Key Technologies & Architecture

- **Backend**: Laravel 12.x (PHP 8.2+)
- **Frontend**: Vue 3 with Inertia.js
- **Build System**: Vite with TypeScript support
- **Styling**: Tailwind CSS with custom components
- **Database**: MySQL (implied from Laravel usage)
- **Authentication**: Laravel Fortify with two-factor authentication
- **Authorization**: Spatie Laravel Permission package
- **File Handling**: Laravel Excel for importing attendance data
- **State Management**: Inertia.js for server-side rendering with client-side interactivity

### Core Features

1. **User Management**:
   - Employee profiles with detailed information (personal, contact, employment details)
   - Role-based access control (RBAC) with Admin/User roles
   - Status tracking (Temporary, Permanent) with end dates and increment scheduling
   - Password management and two-factor authentication

2. **Attendance Management**:
   - Bulk attendance data import via Excel files
   - Batch processing of attendance records
   - Detailed attendance records with clock-in/out times
   - Integration with employee profiles

3. **Dashboard Analytics**:
   - User statistics by role
   - Employee count visualization
   - Status tracking analytics

4. **Settings Management**:
   - Profile editing
   - Password updates
   - Appearance settings
   - Two-factor authentication configuration

### Directory Structure

```
erp-project/
├── app/                    # Application source code
│   ├── Actions/           # Business logic actions
│   ├── Console/           # Artisan commands
│   ├── Http/              # Controllers, middleware, requests
│   ├── Imports/           # Excel import classes
│   ├── Models/            # Eloquent models
│   └── Providers/         # Service providers
├── bootstrap/             # Framework bootstrapping
├── config/                # Configuration files
├── database/              # Migrations, seeds, factories
├── public/                # Public assets
├── resources/             # Frontend assets, views
├── routes/                # Route definitions
├── storage/               # Storage files
├── tests/                 # Test files
├── artisan                # Laravel CLI tool
├── composer.json          # PHP dependencies
├── package.json           # JS/TS dependencies
└── vite.config.ts         # Vite build configuration
```

### Key Models

- **User**: Core user model with employee details, status tracking, and role relationships
- **AttendanceBatch**: Represents a batch of imported attendance data
- **AttendanceRecord**: Individual attendance records linked to batches and users
- **UserStatusHistory**: Tracks status changes for employees over time
- **Role**: User roles managed by Spatie Laravel Permission

### Key Controllers

- **DashboardController**: Handles dashboard analytics and statistics
- **UserController**: Full CRUD operations for employee management
- **AttendanceUploadController**: Handles attendance file uploads and import processing
- **Settings Controllers**: Profile, password, appearance, and 2FA management

### Building and Running

#### Prerequisites
- PHP 8.2+
- Composer
- Node.js and npm
- Database (MySQL/MariaDB recommended)

#### Setup Commands

```bash
# Install PHP dependencies
composer install

# Install Node.js dependencies
npm install

# Copy environment file and generate app key
cp .env.example .env
php artisan key:generate

# Run database migrations
php artisan migrate

# Build frontend assets
npm run build

# Or run in development mode
npm run dev
```

#### Development Commands

```bash
# Start development server with hot reloading
npm run dev

# Alternative development command using composer script
composer run dev

# Run tests
composer run test
npm run test

# Build for production
npm run build

# Format code
npm run format
```

#### Environment Variables

The application uses standard Laravel environment variables. Key variables include:
- Database connection settings
- Mail configuration
- Redis settings (if used)
- Application key and environment

### Development Conventions

1. **Code Style**:
   - PSR-12 for PHP code
   - ESLint and Prettier for JavaScript/TypeScript
   - Tailwind CSS utility-first approach
   - TypeScript for type safety

2. **Architecture Patterns**:
   - MVC pattern with Laravel
   - Request-Response cycle with Form Requests for validation
   - Repository pattern through Eloquent models
   - Action classes for complex business logic

3. **Testing**:
   - PestPHP for unit and feature tests
   - Factory pattern for test data creation
   - Database seeding for development environments

4. **Security**:
   - Laravel Fortify for authentication
   - Spatie Permission for authorization
   - Input validation through Form Requests
   - CSRF protection
   - SQL injection prevention through Eloquent

### Key Dependencies

- **laravel/framework**: Core Laravel framework
- **inertiajs/inertia-laravel**: Server-side rendering bridge
- **spatie/laravel-permission**: Role and permission management
- **maatwebsite/excel**: Excel file import/export capabilities
- **laravel/fortify**: Authentication scaffolding
- **vue**, **@inertiajs/vue3**: Frontend framework and integration
- **tailwindcss**: Utility-first CSS framework

### Special Notes

- The application supports bulk attendance data import via Excel files with error handling and batch processing
- Employee status tracking includes temporary/permanent status with automatic increment date calculation
- The system uses a modern SPA architecture with Inertia.js for seamless page transitions
- File uploads are stored in the `storage/attendance-uploads/` directory organized by month/year
- The application includes comprehensive user audit trails for status changes