Digital - Project Overview

Generated: 2025-10-16 Project Type: Laravel REST API Service (Backend-only) Version: Laravel 10.x on PHP 8.2 Repository Type: Monolith

Executive Summary

Digital is an enterprise-level Laravel REST API backend serving VueJS frontend and mobile applications. The system provides comprehensive business management capabilities including HR, CRM, Project Management, Asset Management, Procedures, OKR tracking, Vacation management, and AI-powered features.

Quick Stats

Metric	Count
Eloquent Models	131 models
API Controllers	99 controllers
Database Migrations	368 migrations
API Routes	~1,775 lines of route definitions
Business Modules	8 core modules
Supported Languages	5 (de, en, es, it, ro)

Project Purpose

Digital serves as a centralized platform for:

Human Resources Management - Employee lifecycle, evaluations, documents, org charts
Customer Relationship Management - Deals, contacts, organizations, sales pipeline
Project & Task Management - Projects, tasks, meetings, collaboration
Procedure Management - Business processes, approvals, analytics
OKR Tracking - Objectives, key results, progress monitoring
Vacation Management - Leave requests, approvals, planning
Asset Management - Equipment tracking, assignments, maintenance
AI Integration - OpenAI powered features, embeddings via Pinecone

Architecture Overview

Repository Structure

Type: Monolithic Laravel application
Pattern: RESTful API (JSON responses only)
Deployment: Single codebase serving multiple client applications

Client Applications (Separate Repositories)

Web Frontend: VueJS SPA
Mobile App: iOS/Android mobile application

Multi-Tenancy

Tenant Isolation: instance_id column on all models
Data Segregation: Complete data separation between organizations
Shared Infrastructure: Single database with row-level tenancy

Technology Stack

Core Framework

Technology	Version	Purpose
PHP	8.2+	Backend language
Laravel	10.x	MVC framework
MySQL	5.7/8.0	Primary database
Redis	Latest	Cache & queue backend

Key Laravel Packages

Package	Purpose
Laravel Sanctum	API token authentication
Laravel Scout	Full-text search (Meilisearch)
Laravel WebSockets	Real-time notifications
Spatie Sluggable	URL-friendly slugs
Panoscape History	Audit trail (ModelHistory)

Third-Party Integrations

Service	Purpose
AWS S3	Cloud file storage
Stripe	Payment processing
OpenAI	AI features (GPT models)
Pinecone	Vector database (embeddings)
Meilisearch	Fast search engine
Firebase	Push notifications
Google APIs	Google service integrations

Document & Data Processing

Package	Purpose
DomPDF	PDF generation
PHPWord	Word document export
Laravel Excel	Excel import/export
Intervention Image	Image manipulation

Business Modules

1. HR & User Management

Core Models: User, Department, Role, Skill, UserFile, Evaluation

Features: - Employee lifecycle management (onboarding, transfers, exits) - Organizational structure (departments, roles, hierarchy) - Performance evaluations & bonuses - Document management with expiry tracking - Skills & competencies tracking - Organizational charts

Rights: Role = Job Position (NOT permissions). Actual permissions managed via Rights system.

2. CRM (Customer Relationship Management)

Core Models: Deal, Organization, Person, Pipeline, Stage

Features: - Sales pipeline management - Contact management (organizations & persons) - Deal tracking through customizable stages - Custom fields per entity type - Activity logging & history

3. Projects & Tasks

Core Models: Project, Task, Meeting, MeetingSession, TaskTimer

Features: - Project creation & member management - Task assignment & tracking - Time tracking per task - Meeting scheduling & summaries - Task watchers & notifications - Task dependencies

4. Procedures

Core Models: Procedure, Process, ProcessVersion, ProcedureLog, ProcedureApprovalRequest

Features: - Business process documentation - Multi-level approval workflows - Process versioning - Execution logging & analytics - Role-based procedure assignment - Checklist support

5. OKR (Objectives & Key Results)

Core Models: Objective, KeyResult, MasterGoal, KeyResultLog

Features: - Company-wide objectives - Department/individual key results - Progress tracking & logging - Period-based planning - Cascade objectives (company → department → individual)

6. Vacation Management

Core Models: VacationDay, VacationType, VacationPlanner, UserVacationDay, VacationApproval

Features: - Vacation request & approval workflow - Annual leave balance tracking - Vacation types (paid leave, sick leave, etc.) - Team vacation planning - Manager approval hierarchy - Vacation excuse documentation

7. Asset Management

Core Models: AssetManagementItem, AssetManagement, AssetManagementTemplate

Features: - Equipment & asset tracking - Asset assignment to employees - Maintenance schedules - Asset categories & templates - Depreciation tracking - Custom fields per asset type

8. AI Module

Core Models: AiAgent, AiModel, AiThread, AiPrompt, AiLog

Features: - OpenAI GPT integration - Custom AI agents with specific roles - Conversation threading - Prompt templates - Pinecone vector embeddings - AI usage logging & analytics

Shared/Core Models

Polymorphic Universal Models

Model	Purpose	Applies To
Comment	Commenting system	Tasks, Deals, Meetings, etc.
Tag	Color-coded tagging	Any taggable entity
NotificationLog	In-app notifications	All users
ModelHistory	Audit trail	All entities with HasOperations trait
CustomField	Dynamic fields	Deals, Organizations, Persons, Assets
CustomFieldValue	Field values	Polymorphic storage

Notification Channels (3-tier)

NotificationLog - In-app notifications with WebSocket real-time delivery
CronjobMail - Queued email notifications (batch sending)
Firebase Push - Mobile & browser push notifications

Authentication & Permissions

Authentication

Primary: Laravel Sanctum (token-based API authentication)
Session: Stateless API (no server-side sessions)
Tokens: Personal access tokens per user

Permission System

CRITICAL: Role ≠ Permission

Role = Job Position (e.g., “Software Engineer”, “Sales Manager”)
Right = Permission (e.g., ADMIN_CRM, EMPLOYEE_PROCEDURE)

Scope Levels: - 0 - NONE (no access) - 1 - OWN (only self) - 2 - DEPARTMENT_DOWN (own department + subordinates) - 3 - ALL (instance-wide access)

Special Rights: - MASTER_ADMIN - Entrepreneur/System Owner (unrestricted access)

Database Architecture

Scale

Tables: 368 migrations = ~370+ database tables
Indexing: Extensive indexes on instance_id, foreign keys, frequently queried columns
Soft Deletes: All primary models use soft deletes (never hard delete)

Key Patterns

Multi-Tenancy: Every table has instance_id for tenant isolation
Polymorphic Relationships: Extensive use for universal features
Pivot Tables: Many-to-many relationships with extra attributes (e.g., user_right with scope)
Hierarchical Data: Self-referencing tables (Department parent/child, User manager/subordinates)

API Design

RESTful Endpoints

Format: JSON request/response
Authentication: Bearer token (Sanctum)
Versioning: Not versioned (single version)
Route File: /routes/api.php (~1,775 lines)

Request/Response Patterns

Request: json { "Authorization": "Bearer {token}", "Content-Type": "application/json" }

Success Response: json { "success": true, "data": {...}, "message": "Operation successful" }

Error Response: json { "success": false, "message": "Error description", "errors": {...} }

Real-Time Features

WebSocket Integration

Package: beyondcode/laravel-websockets
Purpose: Real-time notifications, live updates
Events: Task assignments, deal updates, notifications, etc.

Firebase Push

Purpose: Mobile & browser push notifications
Token Storage: users.firebase_token
Channels: Mobile iOS/Android, Web browser

Internationalization

Supported Languages

de - German
en - English
es - Spanish
it - Italian
ro - Romanian

Translation System

Location: resources/lang/{locale}/
Usage: __('general.message_key')
Coverage: All user-facing messages, notifications, emails

Development Workflow

Environment

Local Development: Laravel Sail (Docker)
Package Manager: Composer (PHP), npm (frontend assets)
Code Style: PSR-12 standard
IDE Helpers: barryvdh/laravel-ide-helper

Testing

Framework: PHPUnit
Coverage: Unit tests, feature tests
Factories: Comprehensive model factories

Build Process

Assets: Laravel Mix (webpack wrapper)
Frontend: Blade templates (minimal, mainly for PDF exports)
Production Build: npm run production

Security Features

Data Protection

Multi-Tenancy: Strict instance isolation
Soft Deletes: Audit-friendly (no data loss)
Audit Trail: ModelHistory tracks all changes
Authorization: Form Request authorization checks

Input Validation

Form Requests: Dedicated validation classes per endpoint
Sanitization: XSS protection via Laravel
SQL Injection: Eloquent ORM prevents SQL injection

Performance Optimizations

Caching

Driver: Redis
Strategy: Cache user rights, custom fields, frequently accessed data
Tags: Cache tagging for targeted invalidation

Queue System

Driver: Redis (queue)
Jobs: Email sending, notification dispatch, heavy computations
Horizons: Not detected (manual queue workers)

Search

Engine: Meilisearch (via Laravel Scout)
Index: Global search across users, tasks, deals, organizations
Searchable Models: User, Task, Deal, Organization, Person, etc.

File Storage

Cloud Storage

Provider: AWS S3
Driver: League Flysystem
File Types: Documents, images, avatars, attachments

Storage Organization

Avatars: avatars/{user_id}/
Documents: documents/{entity_type}/{entity_id}/
Exports: exports/temp/

Integrations

Payment Processing

Provider: Stripe
Features: One-time payments, subscriptions
Package: cartalyst/stripe-laravel

SMS Notifications

Provider: Android SMS Gateway
Purpose: SMS-based notifications, 2FA

Email System

Queue: CronjobMail model (batch sending)
Templates: Blade-based email templates
Tracking: Email send status, delivery confirmation

Deployment Considerations

Server Requirements

PHP: 8.2+
MySQL: 5.7+ or 8.0+
Redis: Latest stable
Extensions: GD/Imagick, OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON

Queue Workers

Required background workers: - Email queue worker - Notification dispatcher - Scheduled task runner (cron)

Cron Jobs

Laravel scheduler runs: - Document expiry notifications - Batch email sending - Data cleanup tasks - Report generation

Existing Module Documentation

Comprehensive module documentation available in /docs-old/:

Shared Models: User, Department, Role, Custom Fields, Notifications, Polymorphic Models
Modules: HR, CRM, Projects/Tasks, Procedures, OKR, Vacation, Asset Management, AI

Total existing documentation: 13 files (~604 KB)

Document Generated: 2025-10-16 Workflow: BMAD document-project v1.2.0 Scan Level: Exhaustive (intelligent inventory)