# Modular Route Structure Documentation

## Overview

The routes have been organized into a modular structure for better maintainability, scalability, and organization. This new structure provides:

- **Route Grouping**: Logical grouping of related endpoints
- **Middleware Integration**: Consistent authentication and authorization
- **Version Control**: Support for API versioning (v1, v2, etc.)
- **Clean Architecture**: Separation of concerns and better code organization

## Structure

```
app/Routes/
├── RoutesLoader.php          # Main route loader class
├── Groups/                   # Route group definitions
│   ├── AuthGroup.php        # Authentication routes
│   ├── UserGroup.php        # User management routes
│   ├── CompanyGroup.php     # Company management routes
│   ├── ReportGroup.php      # Report management routes
│   └── AdminGroup.php       # Admin panel routes
├── auth.php                 # Legacy (can be removed)
├── users.php               # Legacy (can be removed)
├── companies.php           # Legacy (can be removed)
└── reports.php             # Legacy (can be removed)
```

## Route Groups

### 1. Authentication Group (`/api/v1/auth`)

**Public Routes** (no authentication required):
- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/refresh` - Refresh JWT token
- `POST /api/v1/auth/forgot-password` - Password reset request
- `POST /api/v1/auth/reset-password` - Password reset
- `GET /api/v1/auth/verify-email/{token}` - Email verification
- `POST /api/v1/auth/resend-verification` - Resend verification email

**Protected Routes** (authentication required):
- `POST /api/v1/auth/logout` - User logout
- `POST /api/v1/auth/change-password` - Change password
- `GET /api/v1/auth/check` - Check authentication status
- `POST /api/v1/auth/2fa/setup` - Setup 2FA
- `POST /api/v1/auth/2fa/verify` - Verify 2FA
- `POST /api/v1/auth/2fa/disable` - Disable 2FA
- `GET /api/v1/auth/sessions` - Get user sessions
- `DELETE /api/v1/auth/sessions/{session_id}` - Revoke session
- `DELETE /api/v1/auth/sessions/all` - Revoke all sessions
- `GET /api/v1/auth/profile` - Get user profile
- `PUT /api/v1/auth/profile` - Update user profile

### 2. User Group (`/api/v1/users`)

**Profile Routes** (self-access):
- `GET /api/v1/users/profile` - Get own profile
- `PUT /api/v1/users/profile` - Update own profile
- `DELETE /api/v1/users/profile` - Delete own account
- `POST /api/v1/users/profile/avatar` - Upload avatar
- `DELETE /api/v1/users/profile/avatar` - Delete avatar

**Management Routes** (admin/manager access):
- `GET /api/v1/users` - List all users
- `POST /api/v1/users` - Create new user
- `GET /api/v1/users/{id}` - Get user details
- `PUT /api/v1/users/{id}` - Update user
- `DELETE /api/v1/users/{id}` - Delete user
- `PATCH /api/v1/users/{id}/status` - Update user status
- `POST /api/v1/users/{id}/activate` - Activate user
- `POST /api/v1/users/{id}/deactivate` - Deactivate user

**Bulk Operations**:
- `POST /api/v1/users/bulk/activate` - Bulk activate users
- `POST /api/v1/users/bulk/deactivate` - Bulk deactivate users
- `DELETE /api/v1/users/bulk` - Bulk delete users

**Search and Export**:
- `GET /api/v1/users/search` - Search users
- `GET /api/v1/users/filter` - Filter users
- `GET /api/v1/users/export/csv` - Export users to CSV
- `GET /api/v1/users/export/pdf` - Export users to PDF

### 3. Company Group (`/api/v1/companies`)

**Basic CRUD**:
- `GET /api/v1/companies` - List companies
- `POST /api/v1/companies` - Create company
- `GET /api/v1/companies/{id}` - Get company details
- `PUT /api/v1/companies/{id}` - Update company
- `DELETE /api/v1/companies/{id}` - Delete company

**User Management**:
- `GET /api/v1/companies/{id}/users` - Get company users
- `POST /api/v1/companies/{id}/users` - Assign user to company
- `DELETE /api/v1/companies/{id}/users/{user_id}` - Remove user from company
- `PUT /api/v1/companies/{id}/users/{user_id}/role` - Update user role

**Analytics**:
- `GET /api/v1/companies/{id}/analytics/overview` - Company analytics
- `GET /api/v1/companies/{id}/analytics/users` - User analytics
- `GET /api/v1/companies/{id}/analytics/reports` - Report analytics
- `GET /api/v1/companies/{id}/analytics/performance` - Performance metrics

**Settings**:
- `GET /api/v1/companies/{id}/settings` - Get company settings
- `PUT /api/v1/companies/{id}/settings` - Update company settings
- `POST /api/v1/companies/{id}/settings/logo` - Upload company logo
- `DELETE /api/v1/companies/{id}/settings/logo` - Delete company logo

### 4. Report Group (`/api/v1/reports`)

**Basic CRUD**:
- `GET /api/v1/reports` - List reports
- `POST /api/v1/reports` - Create report
- `GET /api/v1/reports/{id}` - Get report details
- `PUT /api/v1/reports/{id}` - Update report
- `DELETE /api/v1/reports/{id}` - Delete report

**Generation**:
- `POST /api/v1/reports/generate/user/{user_id}` - Generate user report
- `POST /api/v1/reports/generate/company/{company_id}` - Generate company report
- `POST /api/v1/reports/generate/custom` - Generate custom report
- `POST /api/v1/reports/generate/scheduled` - Generate scheduled report

**Download/Export**:
- `GET /api/v1/reports/{id}/download/pdf` - Download as PDF
- `GET /api/v1/reports/{id}/download/excel` - Download as Excel
- `GET /api/v1/reports/{id}/download/csv` - Download as CSV
- `GET /api/v1/reports/{id}/download/json` - Download as JSON

**Sharing**:
- `POST /api/v1/reports/{id}/share` - Share report
- `GET /api/v1/reports/{id}/share/link` - Get share link
- `DELETE /api/v1/reports/{id}/share/link` - Revoke share link
- `GET /api/v1/reports/{id}/share/permissions` - Get share permissions
- `PUT /api/v1/reports/{id}/share/permissions` - Update share permissions

**Scheduling**:
- `GET /api/v1/reports/schedule` - Get scheduled reports
- `POST /api/v1/reports/schedule` - Schedule report
- `PUT /api/v1/reports/schedule/{schedule_id}` - Update schedule
- `DELETE /api/v1/reports/schedule/{schedule_id}` - Delete schedule
- `POST /api/v1/reports/schedule/{schedule_id}/run` - Run scheduled report

**Templates**:
- `GET /api/v1/reports/templates` - Get report templates
- `POST /api/v1/reports/templates` - Create template
- `GET /api/v1/reports/templates/{template_id}` - Get template
- `PUT /api/v1/reports/templates/{template_id}` - Update template
- `DELETE /api/v1/reports/templates/{template_id}` - Delete template

### 5. Admin Group (`/api/v1/admin`)

**Dashboard**:
- `GET /api/v1/admin/dashboard` - Admin dashboard
- `GET /api/v1/admin/overview` - System overview
- `GET /api/v1/admin/statistics` - System statistics

**System Management**:
- `GET /api/v1/admin/system/info` - System information
- `GET /api/v1/admin/system/health` - System health check
- `POST /api/v1/admin/system/backup` - Create backup
- `GET /api/v1/admin/system/backups` - List backups
- `POST /api/v1/admin/system/restore/{backup_id}` - Restore backup

**User Management**:
- `GET /api/v1/admin/users` - Get all users (admin view)
- `GET /api/v1/admin/users/analytics` - User analytics
- `POST /api/v1/admin/users/{id}/impersonate` - Impersonate user
- `POST /api/v1/admin/users/{id}/reset-password` - Reset user password
- `POST /api/v1/admin/users/{id}/unlock` - Unlock user account

**Logs and Audit**:
- `GET /api/v1/admin/logs/activity` - Activity logs
- `GET /api/v1/admin/logs/audit` - Audit logs
- `GET /api/v1/admin/logs/errors` - Error logs
- `GET /api/v1/admin/logs/security` - Security logs

**Settings**:
- `GET /api/v1/admin/settings` - System settings
- `PUT /api/v1/admin/settings` - Update system settings
- `GET /api/v1/admin/settings/email` - Email settings
- `PUT /api/v1/admin/settings/email` - Update email settings

**Security**:
- `GET /api/v1/admin/security/sessions` - Active sessions
- `DELETE /api/v1/admin/security/sessions/{session_id}` - Kill session
- `GET /api/v1/admin/security/failed-logins` - Failed login attempts
- `POST /api/v1/admin/security/ban-ip` - Ban IP address

## System Routes

**Health and Info**:
- `GET /health` - Health check endpoint
- `GET /api` - API information
- `GET /` - Root redirect to /api

## Middleware

### AuthMiddleware
- Validates JWT tokens
- Extracts user information
- Sets user attributes in request

### AdminMiddleware
- Checks for admin privileges
- Requires AuthMiddleware to run first
- Validates user roles (admin, super_admin)

## Benefits

1. **Modularity**: Each route group is self-contained
2. **Scalability**: Easy to add new route groups
3. **Maintainability**: Clear separation of concerns
4. **Consistency**: Standardized middleware application
5. **Documentation**: Clear endpoint organization
6. **Version Control**: Support for API versioning
7. **Security**: Consistent authentication/authorization
8. **Testing**: Easier to test individual route groups

## Usage

The new route structure is automatically loaded by the `RoutesLoader` class in `public/index.php`. No changes are needed to existing API calls - all endpoints maintain backward compatibility.

## Future Expansion

To add new route groups:

1. Create a new group file in `app/Routes/Groups/`
2. Add the group to `RoutesLoader.php`
3. Create corresponding controller methods
4. Add appropriate middleware

Example:
```php
// app/Routes/Groups/NotificationGroup.php
return function (RouteCollectorProxy $notifications) {
    $notifications->get('', [NotificationController::class, 'index']);
    $notifications->post('', [NotificationController::class, 'create']);
    // ... other routes
};
```