# Seraph3 - IT Service Management System

## Project Overview

Seraph3 is a comprehensive IT Service Management (ITSM) system built with Laravel 12 and PHP 8.2+. It's designed for computer assistance companies to manage bookings, clients, invoices, stock, and various business operations through a modular architecture.

## 🏗️ Architecture Analysis: Models vs Modules

### Current Hybrid Architecture

The project uses a **hybrid architecture** with both traditional Laravel Models and custom Modules:

#### Traditional Models (`app/Models/`)
- **Purpose**: Core application entities and shared functionality
- **Contains**: User authentication, permissions, settings, status management
- **Examples**: `User.php`, `Status.php`, `Permission.php`, `Group.php`

#### Modular Structure (`app/Modules/`)
- **Purpose**: Feature-specific business logic organized by domain
- **Structure**: Each module is self-contained with controllers, models, views, routes
- **Examples**: Bookings, Clients, Invoices, Stock, Admin

### 🤔 Architecture Concerns & Recommendations

**Current Issues:**
1. **Mixed Patterns**: Having both `app/Models` and `app/Modules/*/models` creates confusion
2. **Inconsistent Imports**: Different case sensitivity (`Models` vs `models`)
3. **Dependency Confusion**: Some modules depend on traditional models, others are self-contained

**Recommended Approach:**
```
Option 1: Full Modular (Recommended)
├── app/Modules/
│   ├── Core/                    # Move User, Permission, Status here
│   ├── Bookings/
│   ├── Clients/
│   └── ...

Option 2: Domain-Driven Design
├── app/Domains/
│   ├── Authentication/
│   ├── ServiceManagement/
│   ├── ClientManagement/
│   └── ...
```

## 📁 Project Structure

```
seraph3/
├── 🔧 Application Core
│   ├── app/
│   │   ├── Commands/              # Artisan console commands
│   │   ├── Console/               # Command scheduling and kernel
│   │   ├── Http/                  # Controllers, middleware, requests
│   │   ├── Models/                # Traditional Laravel models
│   │   ├── Modules/               # Feature modules (see below)
│   │   ├── Providers/             # Service providers
│   │   └── Services/              # Business logic services
│   │
├── 🎨 Frontend & Assets
│   ├── public/                    # Web-accessible files
│   │   ├── css/                   # Stylesheets
│   │   ├── js/                    # JavaScript files
│   │   ├── images/                # Image assets
│   │   └── fonts/                 # Font files
│   │
│   ├── resources/
│   │   ├── views/                 # Blade templates
│   │   ├── assets/                # Source assets (SCSS, JS)
│   │   └── lang/                  # Localization files
│   │
├── 🗄️ Database & Configuration
│   ├── database/
│   │   ├── migrations/            # Database schema changes
│   │   ├── seeds/                 # Data seeders
│   │   └── factories/             # Model factories for testing
│   │
│   ├── config/                    # Application configuration
│   └── routes/                    # Route definitions
│   │
├── 🧪 Testing & Scripts
│   ├── tests/                     # PHPUnit tests
│   ├── scripts/                   # Custom shell scripts
│   └── storage/                   # Application storage (logs, cache)
│
└── 🐳 DevOps
    ├── docker-compose.yml         # Docker configuration
    ├── dockerfile                 # Docker image definition
    └── .env files                 # Environment configuration
```

## 🧩 Modules Breakdown

### Core Business Modules

#### 📋 Bookings Module
- **Purpose**: Service request and task management
- **Features**:
  - Task creation and assignment
  - QA (Quality Assurance) workflows
  - Follow-up management
  - Onsite service scheduling
  - Service type categorization (repair, support, onsite)
- **Key Files**:
  - Controllers: `TaskController`, `QAController`, `OnsiteController`
  - Models: `Task`, `TaskSubtype`, `Booking`
  - Views: Task management interfaces

#### 👥 Clients Module
- **Purpose**: Customer and client relationship management
- **Features**:
  - Client profile management
  - Customer contact information
  - Contract management
  - Client-specific pricing
- **Key Files**:
  - Models: `Client`, `Customer`
  - Controllers: `ClientsController`, REST API controllers
  - Views: Client management interfaces

#### 💰 Invoices Module
- **Purpose**: Billing and invoice management
- **Features**:
  - Invoice generation
  - Payment tracking
  - Integration with accounting systems
- **Integration**: KashFlow accounting system

#### 📦 Stock Module
- **Purpose**: Inventory management
- **Features**:
  - Parts and equipment tracking
  - Stock level monitoring
  - Purchase order management

#### 👨‍💼 Admin Module
- **Purpose**: System administration
- **Features**:
  - User management
  - System settings
  - Contracts administration
  - Permissions and roles

### Supporting Modules

#### 📊 Stats Module
- **Purpose**: Reporting and analytics
- **Features**: Performance metrics, business intelligence

#### 💬 Chat Module
- **Purpose**: Internal communication
- **Features**: Team messaging, notifications

#### ☎️ Asterisk Module
- **Purpose**: VoIP integration
- **Features**: Call management, phone system integration

#### 👔 HR Module
- **Purpose**: Human resources management
- **Features**: Employee management, scheduling

#### 🔔 Notifications Module
- **Purpose**: Alert system
- **Features**: Email, SMS, push notifications

#### 🎮 Gamification Module
- **Purpose**: Employee engagement
- **Features**: Achievement system, leaderboards

### Integration Modules

#### 🔗 Adldap Module
- **Purpose**: Active Directory integration
- **Features**: LDAP authentication, user synchronization

#### 📧 Ews Module
- **Purpose**: Exchange Web Services integration
- **Features**: Email integration, calendar sync

#### 💬 Mattermost Module
- **Purpose**: Team collaboration platform integration

#### 🍬 Sugarcrm Module
- **Purpose**: CRM system integration

## 🛠️ Technology Stack

### Backend
- **Framework**: Laravel 12
- **PHP Version**: 8.2+
- **Database**: MySQL
- **Cache**: Redis
- **Queue**: Redis/Database
- **Authentication**: Laravel Passport (OAuth2)

### Frontend
- **Templates**: Blade templating engine
- **CSS Framework**: Custom CSS with Bootstrap elements
- **JavaScript**: Vanilla JS with some libraries
- **Assets**: Laravel Mix for compilation

### Third-Party Integrations
- **Accounting**: KashFlow API, Xero API
- **Communication**: Twilio (SMS), HipChat
- **VoIP**: Asterisk/FreePBX
- **Directory**: LDAP/Active Directory
- **Email**: Exchange Web Services
- **Search**: Elasticsearch
- **PDF Generation**: DomPDF
- **Excel**: Maatwebsite Excel
- **QR Codes**: Simple QrCode
- **Image Processing**: Intervention Image

### DevOps & Development
- **Containerization**: Docker & Docker Compose
- **Testing**: PHPUnit
- **Debugging**: Laravel Debugbar
- **Version Control**: Git
- **Dependency Management**: Composer

## 🚀 Key Features

### Service Management
- **Multi-type Services**: Repairs, support, onsite visits
- **Quality Control**: QA workflow for service validation
- **Task Assignment**: Automated and manual task distribution
- **SLA Management**: Service level agreement tracking
- **Follow-up System**: Automated customer follow-ups

### Client Management
- **Dual Client Types**: Business clients and individual customers
- **Contract Management**: Service agreements and pricing
- **Contact History**: Complete interaction timeline
- **Custom Pricing**: Client-specific rate structures

### Business Operations
- **Inventory Control**: Parts and equipment tracking
- **Invoicing**: Automated billing with accounting integration
- **Reporting**: Comprehensive business analytics
- **User Management**: Role-based access control

### Communication & Integration
- **Multi-channel Notifications**: Email, SMS, push notifications
- **VoIP Integration**: Call logging and management
- **Team Collaboration**: Internal messaging and chat
- **External Integrations**: CRM, accounting, directory services

## 🔧 Development Setup

### Prerequisites
- Docker & Docker Compose
- PHP 8.2+ (if running locally)
- Composer
- Node.js & NPM (for asset compilation)

### Quick Start
```bash
# Clone repository
git clone <repository-url> seraph3
cd seraph3

# Start Docker containers
docker-compose up -d

# Install dependencies
docker-compose exec app composer install

# Run migrations
docker-compose exec app php artisan migrate

# Seed database
docker-compose exec app php artisan db:seed
```

### Available Services
- **Application**: http://localhost:8000
- **Database Admin**: http://localhost:8080 (Adminer)
- **MySQL**: localhost:3306
- **Redis**: localhost:6379

## 📝 Common Commands

```bash
# Application commands
docker-compose exec app php artisan migrate
docker-compose exec app php artisan cache:clear
docker-compose exec app php artisan queue:work

# Database operations
docker-compose exec app php artisan migrate:fresh --seed
docker-compose exec app php artisan tinker

# Testing
docker-compose exec app php vendor/bin/phpunit
```

## 🎯 Future Recommendations

### Architecture Improvements
1. **Consolidate Module Structure**: Move all models to modules, eliminate `app/Models`
2. **Implement Domain-Driven Design**: Organize by business domains rather than technical layers
3. **Service Layer**: Extract business logic from controllers to dedicated service classes
4. **Event-Driven Architecture**: Implement domain events for better decoupling

### Technical Debt
1. **Namespace Consistency**: Standardize import paths and naming conventions
2. **API Versioning**: Implement proper API versioning strategy
3. **Testing Coverage**: Increase unit and integration test coverage
4. **Documentation**: Add comprehensive API documentation with OpenAPI/Swagger

### Modern Laravel Features
1. **Livewire Integration**: For reactive UI components
2. **Laravel Sanctum**: Consider migrating from Passport for SPA authentication
3. **Laravel Horizon**: For queue monitoring and management
4. **Laravel Telescope**: Enhanced debugging and monitoring

## 📞 Support & Maintenance

This system appears to be a production IT service management platform. Regular maintenance should include:

- **Security Updates**: Keep Laravel and dependencies updated
- **Database Optimization**: Monitor and optimize database queries
- **Log Monitoring**: Regular log analysis for errors and performance issues
- **Backup Strategy**: Implement comprehensive backup and recovery procedures
- **Performance Monitoring**: Track application performance and user experience

---

*Last Updated: 2025-07-02*
*Laravel Version: 12.x*
*PHP Version: 8.2+* 