# Signage Management System - Task Descriptions

## Project Overview

**Title:** Digital Signage Management Platform
**Description:** A comprehensive web-based application for managing digital signage displays, advertisements, and advertising partnerships. The system facilitates the relationship between display owners, advertisers, and advertising partners to manage and deliver digital content across multiple display locations.

---

## Core Modules & Features

### 1. User Management & Authentication

#### 1.1 User Registration & Login
**Title:** User Authentication System
**Description:** Implement secure user registration, login, and role-based access control for different user types (Display Owners, Advertising Partners, Advertisers, and Administrators). The system uses Laravel's built-in authentication with custom middleware for role verification.

**Key Components:**
- Multi-role user registration
- Secure login with session management
- Password reset functionality
- Email verification
- Role-based dashboard redirection

**Files:** `app/Http/Controllers/AuthController.php`, `app/Http/Controllers/Auth/*`

---

### 2. Display Owner Management

#### 2.1 Display Owner CRUD Operations
**Title:** Display Owner Management Module
**Description:** Enable administrators to create, read, update, and delete display owner accounts. Display owners are entities that own physical display locations where advertisements will be shown.

**Key Features:**
- Create new display owner profiles
- Edit display owner information
- View all display owners in a listing
- Delete display owner accounts
- Assign users to display owner accounts

**Files:** `app/Http/Controllers/DisplayOwnerController.php`, `app/Models/DisplayOwner.php`

#### 2.2 Display Owner User Management
**Title:** Display Owner User Assignment
**Description:** Manage the relationship between users and display owner accounts. Allow multiple users to be associated with a single display owner entity for collaborative management.

**Files:** `app/Models/DisplayOwnerUser.php`

---

### 3. Display Location Management

#### 3.1 Location CRUD Operations
**Title:** Display Location Management
**Description:** Manage physical display locations where digital signage screens are installed. Each location is associated with a display owner and contains metadata about the display setup.

**Key Features:**
- Add new display locations with geographic information
- Edit location details (address, description, specifications)
- View all locations in a centralized dashboard
- Associate locations with display owners
- Track location status (active/inactive)

**Files:** `app/Http/Controllers/DisplayLocationController.php`, `app/Models/DisplayLocation.php`

---

### 4. Advertising Partner Management

#### 4.1 Advertising Partner Operations
**Title:** Advertising Partner Management Module
**Description:** Manage advertising partner accounts who act as intermediaries between advertisers and display owners. Partners can manage multiple advertisers and coordinate advertising campaigns.

**Key Features:**
- Create and manage advertising partner profiles
- Edit partner information and credentials
- View partner listings and details
- Assign users to partner accounts
- Track partner performance and activity

**Files:** `app/Http/Controllers/AdvertisingPartnerController.php`, `app/Models/AdvertisingPartner.php`

#### 4.2 Advertising Partner User Management
**Title:** Advertising Partner User CRUD Operations (Admin)
**Description:** Complete CRUD (Create, Read, Update, Delete) functionality for managing users associated with advertising partner accounts. Administrators can create, view, edit, activate, deactivate, and send invitations to advertising partner users. All operations are restricted to admin users only (display owners are not allowed access).

**Key Features:**

**1. List/Read Operations:**
- View all users associated with a specific advertising partner
- Filter users by status: Active, Pending, or Inactive
- Paginated listing (10 users per page)
- Display user counts for each status category (pending, active, inactive)
- Access via: `/advertisingpartners/users/{partner_uuid}` or `/advertisingpartners/users/{partner_uuid}/{status}`

**2. Create Operations:**
- Create new advertising partner users with the following fields:
  - First Name (required)
  - Last Name (required)
  - Email (required, must be unique)
  - Phone Number (optional)
  - Password (optional - can be set immediately or via invitation)
- Two user creation modes:
  - **Direct Password Setup:** Admin sets password immediately, user account is activated
  - **Invitation Mode:** Admin sends invitation email, user sets password via activation link
- Automatically generates unique user UUID
- Creates relationship in `advertising_partner_users` pivot table
- Sends invitation email if invitation option is selected
- Access via: `GET /advertisingpartners/users/{partner_uuid}/create`
- Store via: `POST /advertisingpartners/users/{partner_uuid}/store`

**3. Update/Edit Operations:**
- Edit existing advertising partner user information:
  - First Name (required)
  - Last Name (required)
  - Email (required, must be unique, excluding current user)
  - Phone Number (optional)
- Email uniqueness validation excludes the current user being edited
- Access via: `GET /advertisingpartners/{partner_uuid}/users/{user_uuid}/edit`
- Update via: `POST /advertisingpartners/{partner_uuid}/users/{user_uuid}/update`

**4. Delete/Deactivate Operations:**
- Soft delete functionality (users are not permanently removed)
- Two operation types:
  - **Deactivate:** Soft delete user and advertising partner relationship
  - **Activate:** Restore previously deactivated user and relationship
- Uses Laravel SoftDeletes on both `users` and `advertising_partner_users` tables
- Access via: `POST /advertisingpartners/users/destroy` (AJAX)

**5. Additional Features:**
- **Send Invitation:** Resend account activation invitation email to pending users
  - Generates new unique invitation key
  - Sends email with activation link
  - Access via: `POST /advertisingpartners/users/sendinvitation` (AJAX)
- **Email Validation:** Real-time email uniqueness check via AJAX
  - Validates email doesn't exist in system (excluding current user if editing)
  - Access via: `POST /checkuseremailexists` (AJAX)

**User Status Management:**
- **Pending (-1):** User created but not yet activated (no password set or invitation not accepted)
- **Active (1):** User has set password and account is verified
- **Inactive:** User has been soft deleted (deleted_at timestamp set)

**Security & Access Control:**
- All operations require authentication (`auth` middleware)
- All operations restricted to admin users only (`disallowDisplayOwner()` check)
- Display owner users are explicitly blocked from accessing these features
- CSRF protection on all POST routes
- Input validation on all forms

**Routes:**
```php
GET  /advertisingpartners/users/{key}                    // List users (default: active)
GET  /advertisingpartners/users/{key}/{status}           // List users by status
GET  /advertisingpartners/users/{key}/create             // Create form
POST /advertisingpartners/users/{key}/store             // Store new user
GET  /advertisingpartners/{key}/users/{userkey}/edit    // Edit form
POST /advertisingpartners/{key}/users/{userkey}/update  // Update user
POST /advertisingpartners/users/destroy                 // Activate/Deactivate user
POST /advertisingpartners/users/sendinvitation          // Send invitation email
POST /checkuseremailexists                              // Email validation
```

**Files:** 
- `app/Http/Controllers/AdvertisingPartnerController.php` (methods: `users`, `createUser`, `storeUser`, `editUser`, `updateUser`, `destroyUser`, `sendInvitation`, `checkUserEmailExists`)
- `app/Models/AdvertisingPartnerUser.php`
- `app/Models/User.php`
- `app/Models/AdvertisingPartner.php` (getUsers method)
- `resources/views/advertisingpartners/users.blade.php`
- `resources/views/advertisingpartners/createuser.blade.php`
- `resources/views/advertisingpartners/edituser.blade.php`

---

### 5. Advertiser Management

#### 5.1 Advertiser CRUD Operations
**Title:** Advertiser Account Management
**Description:** Manage advertiser accounts that represent businesses or individuals who want to display advertisements on the digital signage network.

**Key Features:**
- Create advertiser profiles with business information
- Edit advertiser details and contact information
- View advertiser listings
- Associate advertisers with advertising partners
- Track advertiser campaigns and spending

**Files:** `app/Http/Controllers/AdvertiserController.php`, `app/Models/Advertiser.php`

---

### 6. Advertisement Management

#### 6.1 Advertisement Creation & Management
**Title:** Advertisement Content Management
**Description:** Complete system for creating, uploading, and managing advertisement content including images, videos, and scheduling information.

**Key Features:**
- Upload advertisement media (images, videos)
- Set advertisement duration and scheduling
- Assign advertisements to specific display locations
- Manage advertisement status (pending, approved, active, expired)
- Preview advertisements before publishing
- Track advertisement performance

**Files:** `app/Http/Controllers/AdvertisementController.php`, `app/Models/Advertisement.php`

#### 6.2 Image Cropping & Optimization
**Title:** Media Cropping & Processing
**Description:** Provide tools for cropping and optimizing advertisement media to fit various display dimensions and aspect ratios.

**Key Features:**
- Interactive image cropping interface
- Aspect ratio presets for common display sizes
- Image optimization for faster loading
- Batch processing capabilities

**Files:** `app/Http/Controllers/CropController.php`

---

## Technical Features

### 7. Core Functionality

#### 7.1 Custom Helper Functions
**Title:** Core Utility Functions
**Description:** Centralized helper functions for common operations across the application including file handling, date formatting, and data validation.

**Files:** `app/customclasses/Corefunctions.php`

#### 7.2 Middleware & Security
**Title:** Request Security & Validation
**Description:** Implement security middleware for CSRF protection, authentication verification, request validation, and session management.

**Files:** `app/Http/Middleware/*`

---

## Database Schema

### 8. Data Models

#### 8.1 Entity Relationships
**Title:** Database Architecture & Relationships
**Description:** Define and maintain relationships between core entities:

- **Users** → Can belong to Display Owners or Advertising Partners
- **Display Owners** → Have multiple Display Locations
- **Advertising Partners** → Manage multiple Advertisers
- **Advertisers** → Create multiple Advertisements
- **Advertisements** → Assigned to Display Locations
- **Display Locations** → Show multiple Advertisements

**Models:** User, DisplayOwner, DisplayLocation, AdvertisingPartner, Advertiser, Advertisement

---

## Future Enhancements

### 9. Planned Features

#### 9.1 Analytics & Reporting
**Title:** Advertisement Performance Analytics
**Description:** Implement comprehensive analytics dashboard showing:
- Advertisement view counts
- Display location performance metrics
- Revenue tracking and reporting
- Campaign effectiveness analysis

#### 9.2 Scheduling System
**Title:** Advanced Advertisement Scheduling
**Description:** Develop sophisticated scheduling system with:
- Time-based advertisement rotation
- Priority-based display queuing
- Seasonal campaign management
- Conflict resolution for overlapping schedules

#### 9.3 Billing & Payment Integration
**Title:** Integrated Payment Processing
**Description:** Add payment gateway integration for:
- Automated billing for advertisers
- Revenue sharing with display owners
- Partner commission tracking
- Invoice generation and management

#### 9.4 Mobile Application
**Title:** Mobile App for Display Management
**Description:** Create mobile applications for:
- Remote display monitoring
- Quick advertisement approvals
- Performance notifications
- On-the-go content management

#### 9.5 API Development
**Title:** RESTful API for Third-Party Integration
**Description:** Develop comprehensive API endpoints for:
- External system integration
- Mobile app data synchronization
- Partner portal access
- Automated content delivery

---

## Development Guidelines

### Code Standards
- Follow PSR-12 coding standards for PHP
- Use Laravel best practices and conventions
- Implement proper validation for all inputs
- Maintain comprehensive documentation
- Write unit tests for critical features

### Security Requirements
- Implement role-based access control (RBAC)
- Validate and sanitize all user inputs
- Use CSRF protection on all forms
- Encrypt sensitive data
- Regular security audits

### Performance Optimization
- Implement database query optimization
- Use Laravel caching mechanisms
- Optimize media file storage and delivery
- Implement lazy loading for large datasets
- Monitor application performance metrics

---

## Deployment Checklist

- [ ] Configure production environment variables
- [ ] Set up database with proper indexes
- [ ] Configure file storage (local/cloud)
- [ ] Set up email service for notifications
- [ ] Configure backup schedules
- [ ] Set up monitoring and logging
- [ ] Perform security audit
- [ ] Load testing and performance verification
- [ ] Documentation review
- [ ] User training materials preparation

---

**Document Version:** 1.0
**Last Updated:** January 2, 2026
**Maintained By:** Development Team
