Smart Helpdesk - Multi-Tenant SaaS Platform

Smart Helpdesk is a high-fidelity, modern SaaS Helpdesk and SLA Management system built with Laravel and custom Vanilla CSS (complete with dark-slate layouts, smooth gradients, status indicators, and responsive panels).

The platform supports multiple companies (tenants) sharing a single application database, with strict data isolation, role-based dashboards, queue-based inbound email simulation, database notifications, dynamic SLA compliance checks, and reports with graphical charts.

---

🚀 Key Modules & Features

1. Multi-Tenant Architecture (SaaS Concept)

• Data Isolation: Multiple companies use a single codebase and database. Strict isolation is implemented transparently using Laravel's Global Eloquent Scopes.
• Tenant Context Resolution: Automatically resolved via middleware based on either the URL slug (/{tenant_slug}/...) or the logged-in user's company profile.
• Auto-Provisioning: Super Admins can instantly register new tenants, which automatically sets up initial admin credentials and default priority SLA policies.

2. Role-Based Access Control (RBAC)

• Super Admin: Manage global tenant environments and view SaaS company lists.
• Tenant Admin: Manage ticket assignments, configure FAQs, update SLA targets, and inspect analytics dashboards.
• Support Agent: View assigned tickets (Critical priority sorted at the top), update ticket status, post external replies, and add internal notes (visible only to agents/admins).
• Customer: Create support tickets with file attachments, view ticket history, chat with agents, and search the self-service Knowledge Base.

3. Priority & SLA Management

• Dynamic Deadlines: Custom SLA response time limits calculated dynamically on ticket submission based on priority (Low: 24h, Medium: 8h, High: 2h, Critical: 1h).
• Breach Alarms: A background Artisan command (tickets:check-sla) audits active tickets, changes overdue ticket statuses to breached, and triggers database notification alerts.
• Visual Alerting: Critical tickets are highlighted at the top of the queue with custom pulsating indicators to grab support agents' attention.

4. Email Integration & Queueing

• Inbound Webhook: A POST endpoint /api/inbound-email processes incoming email payloads to auto-create tickets and register customers.
• Visual Simulator: An interactive simulator panel inside the Admin dashboard allows testing email arrival.
• Database Queues: Email parsing is offloaded to a queued background job (ProcessInboundEmail), demonstrating Laravel's database queue driver. Admins can trigger the queue worker once directly from the UI.

5. Analytical Reports & Charts

• Displays metrics for Total Tickets, Active Tickets, Resolved Tickets, and SLA Breaches.
• Integrates interactive charts via Chart.js:
  • Ticket distribution by priority (doughnut chart).
  • Support Agent performance comparing assigned vs. resolved counts (grouped bar chart).

6. REST API Development

• POST /api/inbound-email (Public webhook for email routing).
• POST /api/{tenant_slug}/tickets (Bearer Token-authenticated ticket creation for external integrations).

---

🛠️ Tech Stack

• Framework: Laravel 12+
• Database: MySQL (supported via PDO extension)
• Frontend Engine: Blade Templates & Vanilla JavaScript
• Styling: Vanilla CSS (Glassmorphism card styles, modern typography, responsive layout templates)
• Libraries: Chart.js (CDN)
• Testing: PHPUnit / Laravel HTTP Feature Tests

---

⚙️ Installation & Setup

Prerequisites

• PHP 8.2+
• Composer
• MySQL/MariaDB database (e.g., XAMPP local environment)

Step-by-Step Installation

1. Clone the Repository:

   git clone https://github.com/your-username/smart-helpdesk.git
   cd smart-helpdesk

2. Install Composer Dependencies:

   composer install

3. Configure Environment: Copy .env.example to .env and configure your database parameters:

   cp .env.example .env

   Modify the DB fields in .env to match your database server configuration:

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=smart_helpdesk
   DB_USERNAME=root
   DB_PASSWORD=

4. Generate Application Key:

   php artisan key:generate

5. Run Database Migrations & Seeders: Create a database named smart_helpdesk in MySQL, then run:

   php artisan migrate:fresh --seed

   This seeds default tenants (TechCorp Solutions, FinBank Corporation), pre-configured SLA policies, sample tickets, FAQs, and a set of test users.

6. Serve the Application:

   php artisan serve

   Open your browser and navigate to: http://127.0.0.1:8000

---

🧪 Running Automated Tests

The application includes feature tests covering tenant data isolation, role authorization, and SLA audit execution:

php artisan test

---

💡 Guided Demo Flow (How to Test)

1. Portal Directory (Landing Page): Open http://127.0.0.1:8000. Use the Demo Quick Switcher to log into different roles without entering passwords.
2. Submit a Ticket: Log in as Customer under TechCorp. Create a new ticket (e.g., Critical priority) and upload attachments.
3. Verify Dashboard Sorting: Log in as Agent A under TechCorp. Note the new ticket shows at the top with a red pulse alarm. A notification will appear in the top header.
4. Post Internal Notes: As an Agent, view the ticket. Post a reply with the Internal Note checkbox ticked. Log back in as the customer; they cannot see internal notes.
5. Update SLA Policy: As Admin under TechCorp, visit SLA Policies and adjust the target hours.
6. Trigger Email Simulator: As Admin, navigate to Email Simulator. Fill out the form simulating an email to support@techcorp.com. Submit it. Click Run Queue Worker to process the job in the database and see the ticket created.
7. SLA Breach Audit: Run the audit command in the console to identify overdue tickets and trigger team alerts:

   php artisan tickets:check-sla

8. Add a Tenant: Log in as Super Admin (admin@saas.com). Spin up a new tenant (e.g., Acme Corp). Log out and log in as the newly generated tenant admin (admin@acme.com / password: password) to see an isolated default workspace.