Digital - System Architecture

Generated: 2025-10-16 Architecture Type: Laravel RESTful API Monolith with Multi-Module Structure Pattern: Multi-tenant SaaS Backend

System Overview
Architecture Principles
System Components
Data Architecture
API Architecture
Authentication & Authorization
Real-Time Architecture
Integration Architecture
Deployment Architecture

System Overview

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Client Applications                       │
├──────────────────────┬──────────────────────────────────────┤
│   VueJS Frontend     │       Mobile App (iOS/Android)       │
│   (Separate Repo)    │         (Separate Repo)              │
└──────────────────────┴──────────────────────────────────────┘
                            │
                            │ HTTPS / JSON
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Laravel REST API (This Repository)              │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  API Routes  │  │ Controllers  │  │ Middleware   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Form Requests│  │  Services    │  │   Models     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
           ┌────────────────┼────────────────┐
           │                │                │
           ▼                ▼                ▼
    ┌──────────┐     ┌──────────┐    ┌──────────┐
    │  MySQL   │     │  Redis   │    │  AWS S3  │
    │ Database │     │Cache/Queue│   │  Storage │
    └──────────┘     └──────────┘    └──────────┘
           │
           ▼
    ┌──────────────┐
    │ Meilisearch  │
    │Search Engine │
    └──────────────┘

Architecture Style

Pattern: Monolithic Laravel Application
API Type: RESTful JSON API
Tenancy: Row-level multi-tenancy (instance_id)
Modularity: Feature-based modules within monolith

Architecture Principles

1. Separation of Concerns

Presentation Layer (API): - Controllers handle HTTP requests/responses only - Thin controllers, business logic in services/models

Business Logic Layer: - Eloquent Models contain domain logic - Service classes for complex workflows - Manager classes for cross-cutting concerns (RightManager, ResponsibilityManager)

Data Access Pattern: - Direct Eloquent model usage (no Repository pattern) - Query logic lives in Models (scopes, relationships) - Complex queries extracted to Manager classes when needed

Data Layer: - Eloquent ORM for database abstraction - Migrations for schema versioning - Factories & Seeders for test data

2. DRY (Don’t Repeat Yourself)

Reusable Components: - Polymorphic models for universal features (Comment, Tag, NotificationLog) - Traits for shared behavior (HasOperations, Searchable, SoftDeletes) - Helpers for common functions (app/Helpers/general.php) - Form Requests for validation reuse

3. Convention over Configuration

Laravel Conventions: - PSR-4 autoloading (App\ namespace) - RESTful resource controllers - Eloquent naming conventions - Migration & model naming patterns

4. Security by Default

Built-in Protections: - CSRF protection (disabled for API, using Sanctum tokens) - XSS protection via Blade escaping - SQL injection prevention via Eloquent - Mass assignment protection ($fillable/$guarded)

System Components

Laravel MVC Structure

app/
├── Http/
│   ├── Controllers/
│   │   └── Api/              # 99 API Controllers
│   ├── Middleware/           # Authentication, tenant filtering
│   └── Requests/             # Form Request validation classes
├── Models/                   # 131 Eloquent Models
├── Helpers/                  # Utility functions
├── Managers/                 # Cross-cutting logic (Rights, Responsibilities)
├── Enums/                    # Enum constants (RightEnum, StatusEnum, etc.)
└── Traits/                   # Reusable model behaviors

Module Organization

8 Core Business Modules:

HR Module
- Models: User, Department, Role, Skill, UserFile, Evaluation
- Purpose: Employee management, org structure, evaluations
CRM Module
- Models: Deal, Organization, Person, Pipeline, Stage
- Purpose: Sales management, contact tracking
Projects & Tasks Module
- Models: Project, Task, Meeting, TaskTimer
- Purpose: Project collaboration, task tracking
Procedures Module
- Models: Procedure, Process, ProcessVersion, ProcedureLog
- Purpose: Business process documentation & execution
OKR Module
- Models: Objective, KeyResult, MasterGoal
- Purpose: Goal setting and tracking
Vacation Module
- Models: VacationDay, VacationType, VacationPlanner
- Purpose: Leave management
Asset Management Module
- Models: AssetManagementItem, AssetManagement
- Purpose: Equipment and asset tracking
AI Module
- Models: AiAgent, AiModel, AiThread, AiPrompt
- Purpose: AI-powered features (OpenAI integration)

Data Architecture

Multi-Tenancy Strategy

Row-Level Tenancy: php // Every model has instance_id for tenant isolation Schema::create('users', function (Blueprint $table) { $table->id(); $table->foreignId('instance_id')->constrained(); // ... other columns });

Automatic Tenant Scoping: ```php // Global scope on models protected static function boot() { parent::boot();

static::creating(function ($model) {
    if (!$model->instance_id) {
        $model->instance_id = auth()->user()->instance_id;
    }
});

} ```

Query Filtering: php // Always filter by instance $users = User::where('instance_id', auth()->user()->instance_id)->get();

Database Schema Patterns

1. Polymorphic Relationships

Universal features using polymorphic associations:

// comments table
Schema::create('comments', function (Blueprint $table) {
    $table->id();
    $table->foreignId('instance_id');
    $table->foreignId('user_id');
    $table->morphs('commentable');  // commentable_type, commentable_id
    $table->text('content');
    $table->timestamps();
});

// Usage
$task->comments()->create(['content' => '...']);
$deal->comments()->create(['content' => '...']);

2. Pivot Tables with Attributes

Many-to-many with extra data:

// user_right pivot table
Schema::create('user_right', function (Blueprint $table) {
    $table->foreignId('user_id');
    $table->foreignId('right_id');
    $table->integer('scope')->default(0);  // Extra attribute
    $table->timestamps();
});

3. Hierarchical Data

Self-referencing tables:

// Departments with parent/child hierarchy
Schema::create('departments', function (Blueprint $table) {
    $table->id();
    $table->foreignId('parent_id')->nullable()->constrained('departments');
    // ...
});

// Users with manager/subordinate hierarchy
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->foreignId('parent_function_id')->nullable()->constrained('users');
    // ...
});

4. Soft Deletes

All primary models use soft deletes:

use Illuminate\Database\Eloquent\SoftDeletes;

class User extends Model
{
    use SoftDeletes;
}

API Architecture

RESTful Design

Resource-Oriented Endpoints:

# Standard CRUD
GET    /api/users           # List
POST   /api/users           # Create
GET    /api/users/{id}      # Show
PUT    /api/users/{id}      # Update
DELETE /api/users/{id}      # Delete (soft delete)

# Nested Resources
GET    /api/users/{id}/tasks
POST   /api/users/{id}/tasks
GET    /api/users/{id}/subordinates

# Custom Actions
POST   /api/users/{id}/assign-right
PUT    /api/users/{id}/change-password
POST   /api/tasks/{id}/complete

Request/Response Format

Standard Success Response: json { "success": true, "data": { "id": 123, "name": "John Doe", // ... }, "message": "Operation successful" }

Standard Error Response: json { "success": false, "message": "Validation failed", "errors": { "email": ["The email field is required."] } }

Middleware Stack

Route::middleware(['api', 'auth:sanctum', 'instance'])->group(function () {
    // API routes
});

Middleware Responsibilities: - auth:sanctum - Authenticate API token - instance - Enforce tenant isolation - throttle - Rate limiting - Custom middleware for rights checking

Authentication & Authorization

Authentication (Laravel Sanctum)

Token-Based Auth: ```php // Login POST /api/auth/login { “email”: “user@example.com”, “password”: “password” }

// Response { “token”: “1|abc123…”, “user”: {…} }

// Authenticated Requests Authorization: Bearer 1|abc123… ```

Authorization (Rights System)

Role vs Rights Distinction: - Role = Job Position (e.g., “Senior Developer”) - Right = Permission (e.g., ADMIN_CRM, EMPLOYEE_TASK)

Permission Check: ```php // In FormRequest public function authorize() { return $this->user()->hasRight(RightEnum::ADMIN_USER); }

// In Controller if (!auth()->user()->hasRight(RightEnum::ADMIN_CRM)) { return response()->json([‘error’ => ‘Unauthorized’], 403); } ```

Scope-Based Filtering:

Scope	Value	Access Level
NONE	0	No access
OWN	1	Only own records
DEPARTMENT_DOWN	2	Own dept + subordinate depts
ALL	3	All records in instance

Special Role: - MASTER_ADMIN - Unrestricted access to everything in instance

Real-Time Architecture

WebSocket Server

Package: beyondcode/laravel-websockets

Architecture: Laravel Application │ ├─► WebSocket Server (Port 6001) │ └─► Pusher protocol compatible │ └─► Broadcasting System ├─► Channels (private, presence, public) └─► Events (TaskAssigned, DealUpdated, etc.)

Event Broadcasting: ```php // Broadcast event broadcast(new TaskAssigned($task, $user))->toOthers();

// Client subscription (VueJS) Echo.private(user.${userId}) .listen(‘TaskAssigned’, (e) => { // Handle notification }); ```

Push Notifications (Firebase)

Flow: Laravel Backend │ ├─► Create NotificationLog ├─► Send Firebase FCM message │ │ │ ▼ │ Firebase Cloud Messaging │ │ │ ├─► Mobile App (iOS/Android) │ └─► Web Browser │ └─► Queue Email (CronjobMail)

3-Channel Notification System: 1. In-app (NotificationLog + WebSocket) 2. Email (CronjobMail + Queue) 3. Push (Firebase FCM)

Integration Architecture

AWS S3 Storage

Configuration: php // config/filesystems.php 's3' => [ 'driver' => 's3', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION'), 'bucket' => env('AWS_BUCKET'), ]

Usage: ```php // Store file Storage::disk(‘s3’)->put(‘avatars/user-123.jpg’, $file);

// Get URL $url = Storage::disk(‘s3’)->url(‘avatars/user-123.jpg’); ```

Meilisearch (Full-Text Search)

Architecture: Laravel Scout │ ├─► Searchable Models (User, Task, Deal, etc.) │ │ │ └─► toSearchableArray() │ ▼ Meilisearch Engine │ └─► Global Search Index

Search Query: php // Search across all searchable models $results = User::search('john')->get(); $tasks = Task::search('urgent')->get();

OpenAI Integration

Features: - GPT-powered text generation - Conversation threading (AiThread) - Custom AI agents with roles (AiAgent) - Prompt templates (AiPrompt)

Vector Storage (Pinecone): - Embeddings for semantic search - Document similarity matching

Stripe Payment Processing

Features: - One-time payments - Subscription management - Webhook handling

Deployment Architecture

Production Environment

Recommended Stack: ┌────────────────────────────────────────┐ │ Load Balancer (nginx) │ └────────────────────────────────────────┘ │ ┌───────────┴───────────┐ │ │ ┌─────▼──────┐ ┌───────▼────┐ │ App Server │ │ App Server │ │ (PHP-FPM) │ │ (PHP-FPM) │ └────────────┘ └────────────┘ │ │ └───────────┬───────────┘ │ ┌────────────┴───────────────┐ │ │ ┌────▼─────┐ ┌──────▼──────┐ │ │ MySQL │ │ Redis │ │ │ (Primary)│ │ Cache/Queue │ │ └──────────┘ └─────────────┘ │ │ ┌────────▼────────┐ │ Meilisearch │ │ Search Engine │ └─────────────────┘

Background Workers

Required Services: ```bash

Queue worker (for jobs)

php artisan queue:work

Schedule runner (cron)

- - - - cd /path && php artisan schedule:run

WebSocket server

php artisan websockets:serve ```

Scaling Considerations

Horizontal Scaling: - Multiple app servers behind load balancer - Shared session storage (Redis) - Shared file storage (S3)

Database Scaling: - Read replicas for heavy read operations - Index optimization on frequently queried columns

Cache Strategy: - Redis for session, cache, queue - Cache user rights and permissions - Cache custom fields configuration

Security Architecture

Data Protection

Multi-Tenancy Security: php // Middleware ensures all queries filtered by instance_id class EnsureTenantScope { public function handle($request, Closure $next) { if (auth()->check()) { $instanceId = auth()->user()->instance_id; // Validate all requests operate within tenant boundary } return $next($request); } }

Audit Trail: ```php use Panoscape\History\HasOperations;

class Deal extends Model { use HasOperations; // Automatic change tracking }

// Query history $deal->history; // All historical changes ```

Input Validation

Form Request Classes: ```php class UserFormRequest extends FormRequest { public function authorize() { return $this->user()->hasRight(RightEnum::ADMIN_USER); }

public function rules()
{
    return [
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users,email',
        // ...
    ];
}

} ```

Performance Optimization

Eager Loading

Prevent N+1 Queries: ```php // ❌ BAD - N+1 problem $users = User::all(); foreach ($users as $user) { echo $user->department->name; // Query per user }

// ✅ GOOD - Eager load $users = User::with(‘department’)->get(); ```

Caching Strategy

Cache Layers: 1. Application Cache (Redis) - Rights, custom fields, frequently accessed data 2. Query Result Cache - Expensive queries cached with TTL 3. HTTP Cache - API response caching for static endpoints

Database Indexing

Key Indexes: ```sql – Multi-tenancy INDEX idx_instance_id ON users (instance_id);

– Foreign keys INDEX idx_department_id ON users (department_id);

– Composite indexes for common queries INDEX idx_instance_status ON tasks (instance_id, status); ```

Digital - System Architecture

Table of Contents

System Overview

High-Level Architecture

Architecture Style

Architecture Principles

1. Separation of Concerns

2. DRY (Don’t Repeat Yourself)

3. Convention over Configuration

4. Security by Default

System Components

Laravel MVC Structure

Module Organization

Data Architecture

Multi-Tenancy Strategy

Database Schema Patterns

API Architecture

RESTful Design

Request/Response Format

Middleware Stack

Authentication & Authorization

Authentication (Laravel Sanctum)

Authorization (Rights System)

Real-Time Architecture

WebSocket Server

Push Notifications (Firebase)

Integration Architecture

AWS S3 Storage

Meilisearch (Full-Text Search)

OpenAI Integration

Stripe Payment Processing

Deployment Architecture

Production Environment

Background Workers

Queue worker (for jobs)

Schedule runner (cron)

WebSocket server

Scaling Considerations

Security Architecture

Data Protection

Input Validation

Performance Optimization

Eager Loading

Caching Strategy

Database Indexing

Related Documentation