# Matendes HRM - Developer Guide

## Overview

Matendes HRM is a modern, scalable Human Resource Management system built with Laravel 11 and React 18. This guide provides comprehensive information for developers to understand, customize, and extend the system.

## Architecture

### Backend (Laravel 11)
- **Framework**: Laravel 11 with Sanctum authentication
- **Database**: SQLite (development) / MySQL (production)
- **API**: RESTful API with versioning (v1)
- **Authentication**: Multi-factor authentication with role-based permissions
- **Caching**: Redis for sessions and application cache

### Frontend (React 18)
- **Framework**: React 18 with Vite
- **UI Library**: PrimeReact for modern components
- **State Management**: Redux Toolkit for global state
- **Routing**: React Router for SPA navigation

## Core Modules

### 1. Authentication System
- Multi-factor authentication (MFA)
- Role-based access control (RBAC)
- JWT token management with Sanctum
- Session management

**Key Files:**
- `app/Http/Controllers/Api/V1/AuthController.php`
- `app/Models/User.php`
- `app/Services/AuthenticationService.php`

### 2. Employee Management
- Complete employee profiles
- Document management
- Employment history tracking
- Onboarding workflows

**Key Files:**
- `app/Http/Controllers/Api/V1/HRM/EmployeeController.php`
- `app/Models/Employee.php`
- `app/Services/EmployeeManagementService.php`

### 3. Organization Structure
- Multi-tenant company management
- Branch and department hierarchy
- Job positions and roles

**Key Files:**
- `app/Http/Controllers/Api/V1/Organization/`
- `app/Models/Company.php, Branch.php, Department.php`

### 4. Settings & Features
- Dynamic feature toggles
- System configuration management
- User preferences

**Key Files:**
- `app/Http/Controllers/Api/V1/SettingsController.php`
- `app/Models/Setting.php`
- `app/Services/SettingsService.php`

### 5. Notification System
- Multi-channel notifications (Email, SMS, Push)
- Template management
- Notification preferences

**Key Files:**
- `app/Http/Controllers/Api/V1/NotificationController.php`
- `app/Services/Notifications/NotificationService.php`

## API Structure

### Base URL
```
/api/v1/
```

### Authentication
All protected endpoints require Bearer token:
```
Authorization: Bearer {token}
```

### Core Endpoints

#### Authentication
```
POST /auth/login
POST /auth/register
POST /auth/logout
POST /auth/refresh
GET  /auth/profile
PUT  /auth/profile
```

#### Employee Management
```
GET    /hrm/employees
POST   /hrm/employees
GET    /hrm/employees/{id}
PUT    /hrm/employees/{id}
DELETE /hrm/employees/{id}
```

#### Organization
```
GET    /organization/companies
POST   /organization/companies
GET    /organization/branches
POST   /organization/branches
GET    /organization/departments
POST   /organization/departments
```

#### Settings
```
GET    /settings
POST   /settings
GET    /settings/{key}
PUT    /settings/{key}
DELETE /settings/{key}
GET    /settings/features
POST   /settings/features/enable
```

## Database Schema

### Key Tables

#### Users
- Authentication and user profiles
- MFA device management
- Role assignments

#### Employees
- Extended employee information
- Links to organizational structure
- Employment history

#### Companies/Branches/Departments
- Multi-tenant organizational hierarchy
- Location and contact information

#### Settings
- Dynamic configuration system
- Feature toggles
- User preferences

## Development Setup

### Prerequisites
- PHP 8.2+
- Composer
- Node.js 18+
- SQLite/MySQL

### Installation
```bash
# Clone repository
git clone <repository-url>
cd matendes-hrm

# Backend setup
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed

# Frontend setup
cd frontend
npm install
npm run dev

# Start backend server
php artisan serve
```

### Development Commands

#### Backend
```bash
# Run migrations
php artisan migrate

# Seed database
php artisan db:seed

# Clear cache
php artisan cache:clear
php artisan config:clear

# Run tests
php artisan test
```

#### Frontend
```bash
# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

## Code Standards

### Laravel Conventions
- Use meaningful controller, model, and service names
- Follow PSR-12 coding standards
- Use form request validation
- Implement proper error handling
- Use resource classes for API responses

### React Conventions
- Use functional components with hooks
- Implement proper prop types
- Use Redux for global state management
- Follow component composition patterns

### Naming Conventions
- Controllers: `{Name}Controller.php`
- Models: `{Name}.php` (singular)
- Services: `{Name}Service.php`
- Resources: `{Name}Resource.php`
- Requests: `{Action}{Name}Request.php`

## Security Guidelines

### API Security
- Always validate input data
- Use proper authentication middleware
- Implement rate limiting
- Sanitize database queries
- Use HTTPS in production

### Data Protection
- Encrypt sensitive data
- Implement proper access controls
- Log security events
- Regular security audits

## Testing

### Backend Testing
- Feature tests for API endpoints
- Unit tests for services and models
- Integration tests for complex workflows

### Frontend Testing
- Component testing with Jest
- E2E testing with Cypress
- Visual regression testing

## Deployment

### Production Checklist
- [ ] Configure environment variables
- [ ] Set up database with proper indexes
- [ ] Configure queue workers
- [ ] Set up SSL certificates
- [ ] Configure caching (Redis)
- [ ] Set up monitoring and logging
- [ ] Configure backup systems

### Environment Configuration
```env
APP_ENV=production
APP_DEBUG=false
DB_CONNECTION=mysql
QUEUE_CONNECTION=redis
CACHE_DRIVER=redis
SESSION_DRIVER=redis
```

## Customization Guide

### Adding New Modules
1. Create controller in `app/Http/Controllers/Api/V1/`
2. Create model in `app/Models/`
3. Create migration in `database/migrations/`
4. Add routes in `routes/api/v1/`
5. Create tests in `tests/Feature/`

### Adding New Features
1. Add feature toggle in settings
2. Implement feature check middleware
3. Create feature-specific controllers
4. Add frontend components
5. Update documentation

### Custom Permissions
1. Add permission in seeder
2. Attach to roles
3. Use in middleware or policies
4. Update frontend permissions

## Troubleshooting

### Common Issues

#### Authentication Errors
- Check Sanctum configuration
- Verify token expiration
- Check CORS settings

#### Database Issues
- Run migrations
- Check database connection
- Verify foreign key constraints

#### Frontend Issues
- Clear browser cache
- Check API endpoints
- Verify proxy configuration

### Debug Tools
- Laravel Telescope for debugging
- React DevTools for frontend
- Postman for API testing

## API Documentation

A comprehensive API documentation is available at `/api/documentation` when the application is running.

## Support & Contributing

### Getting Help
- Check this documentation first
- Review test files for examples
- Create detailed issue reports

### Contributing
- Follow coding standards
- Write tests for new features
- Update documentation
- Submit clear pull requests

## Performance Optimization

### Backend Optimization
- Use database indexes
- Implement query optimization
- Use caching strategically
- Optimize file uploads

### Frontend Optimization
- Implement lazy loading
- Use React.memo for optimization
- Optimize bundle size
- Implement proper error boundaries

---

**Last Updated**: August 2025
**Version**: 1.0.0