# MPIRIC CRM — Developer Reference

## Project Overview

**Name:** mpiric-crm (internally: Project-AI)
**Type:** Laravel 11 CRM + HRMS (Customer Relationship + Human Resource Management System)
**Built for:** Mpiric Software (akshit@mpiricsoftware.com)
**Database:** `mpiric_ai` (MySQL)
**Local URL:** `http://localhost:8000`

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend framework | Laravel 11, PHP 8.2+ |
| Auth | Jetstream 5.1 (teams), Sanctum 4.0 (API tokens), Passport 12.0 (OAuth2) |
| Authorization | Spatie Permission 6.9 (roles + permissions) |
| Frontend | Bootstrap 5.3.3, jQuery 3.7.1, Blade templates |
| Build | Vite 5.3.3 |
| Real-time UI | Livewire 3.0 |
| Tables | Yajra DataTables 11.0 (server-side) |
| Charts | ApexCharts, Chart.js, ConsoleTV Charts 6.7 |
| Email | Gmail SMTP + Webklex IMAP 6.2 (email-to-task/ticket) |
| Calendar | FullCalendar 6.1.14 |
| Rich text | Quill 1.3.7 |
| Notifications | SweetAlert2, Toastr |
| Date pickers | Flatpickr, Bootstrap DatePicker |
| File upload | Dropzone 5.9.3 |
| Drag-drop | SortableJS, JKanban |

---

## Local Dev Setup

```bash
composer install
cp .env.example .env
php artisan key:generate
yarn install
yarn build              # or: yarn dev (HMR)
php artisan migrate
php artisan serve
```

**Database:** Create `mpiric_ai` in MySQL, set credentials in `.env`.

---

## Project Architecture

### Directory Layout

```
app/
  Actions/            # Jetstream/Fortify actions (user creation, teams)
  Console/Commands/   # Artisan: CheckMailAndCreateTasks.php (IMAP polling)
  Helpers/            # Helpers.php (layout/theme config)
  Http/
    Controllers/      # 184 controller files
      api/            # Countries, states, cities API
      apps/           # Feature modules (Calendar, Chat, Kanban, Academy...)
      dashboard/      # Analytics + CRM dashboards
      Auth/           # Auth handlers
      [Core modules]  # See "Core Controllers" below
  Models/             # 40 model files
routes/
  web.php             # 900+ lines, all protected by auth middleware
  api.php             # Geographic data endpoints
database/
  migrations/         # 70+ migration files
resources/
  views/              # Blade templates
  menu/               # Menu configuration
public/
  uploads/            # User file uploads
  build/              # Compiled Vite assets
```

### Middleware & Guards

- All web routes require `auth` middleware
- Super Admin routes additionally require `role:Super Admin`
- API routes use `auth:sanctum`

---

## Core Controllers & Modules

### HR Module
| Controller | Responsibility |
|-----------|---------------|
| `EmployeeController` | Employee CRUD, family details, documents (Aadhar, PAN) |
| `AttendanceController` | Check-in/out, attendance records |
| `AttendanceReportController` | Attendance report generation |
| `TimeLogController` | Daily time tracking with IP address logging |
| `SalaryComponentController` | Salary component management (earnings/deductions) |
| `SalarySlipController` | Monthly salary slip generation and printing |
| `LeaveAccountingController` | Leave requests, approval workflow |
| `PolicyController` | Leave policies, holiday calendars |
| `GroupController` | Employee grouping with policy assignment |
| `BreakController` | Break time management |

### CRM Module
| Controller | Responsibility |
|-----------|---------------|
| `LeadController` | Lead CRUD, proposals, activity log, lead conversion |
| `LeadStatusController` | Lead status workflow definitions |
| `LeadSourceController` | Lead source (channel) definitions |
| `ProposalController` | Proposal management and printing |

### Recruitment Module
| Controller | Responsibility |
|-----------|---------------|
| `CandidateResumeController` | Resume CRUD, skills, interview status, reviews |
| `TechnologyController` | Skills/technology tags |

### Operations Module
| Controller | Responsibility |
|-----------|---------------|
| `taskmcontroller` | Tasks, Kanban board, email-based task creation |
| `TicketsController` | Support tickets, email-to-ticket, file attachments |
| `calendarcontroller` | Calendar events |

### Admin Module
| Controller | Responsibility |
|-----------|---------------|
| `adminController` | User management, role assignment |
| `companyController` | Multi-company configuration (GST, CIN) |
| `DepartmentController` | Department management |
| `SiteController` | Office/site locations |
| `smtpController` | SMTP configuration per company |
| `BackupController` | DB backup, cache clearing |

---

## Database Schema — Key Tables

### Users & Auth
- `users` — id, name, email, password, company_id, site_id, department_id, status
- `teams` / `team_user` / `team_invitations` — Jetstream multi-tenancy
- `roles` / `permissions` / `model_has_roles` — Spatie RBAC
- `personal_access_tokens` — Sanctum
- `oauth_*` — Passport OAuth2 tables (5 tables)

### HR
- `employees` — Full profile: address, insurance, documents, salary, hire dates
- `departments`, `sites`, `groups` — Org structure
- `attendance`, `time_logs`, `breaks` — Time tracking
- `leaves`, `leaves_accountings` — Leave types + requests + approvals
- `salary_components`, `salary_component_histories`, `salary_slips` — Payroll
- `policies` — Leave policies with holiday lists
- `family_details` — Employee family records

### CRM
- `leads` — name, email, company, phone, lead_value, status_id, source_id
- `lead_status` — prospect, negotiation, won, lost, etc.
- `lead_source` — website, referral, cold call, etc.
- `lead_activities` — Activity log per lead
- `proposals`, `proposal_items` — Proposals with line items, discount, tax

### Recruitment
- `candidate_resumes` — skills, interview_status, review
- `technologies` — Skills/technology tags

### Support & Tasks
- `tasks`, `task_tags`, `tags` — Task management
- `tickets`, `ticket_files` — Support tickets with attachments
- `events` — Calendar events
- `timelines` — Generic activity timeline

### Admin / Config
- `companies` — Multi-company (GST, CIN, billing address)
- `smtp` — SMTP server configs per company
- `countries`, `states`, `cities` — Geographic data (API-served)

### Infrastructure
- `sessions`, `cache`, `jobs`, `failed_jobs` — Laravel infrastructure tables

---

## Roles & Permissions

Three main roles:
1. **Super Admin** — Full access, admin user management
2. **Admin** — Company-level management
3. **User** — Regular employee access

Permissions managed via Spatie; enforced via route middleware and `can()` checks in views.

---

## Email Integration (IMAP)

- **Command:** `php artisan emails:check-and-create-tasks`
- **Inbox:** Gmail IMAP (configured in `config/imap.php`)
- **Behavior:** Parses incoming emails, auto-creates Tickets or Tasks
- **Attachments:** Email files attached to created tickets
- **Scheduling:** Should be run via scheduler in `app/Console/Kernel.php`

---

## API Endpoints

```
GET /api/user                          # Authenticated user (Sanctum)
GET /api/countries                     # All countries
GET /api/states?countryId={id}         # States for a country
GET /api/cities?stateId={id}           # Cities for a state
```

---

## Frontend Conventions

- Templates use **Bootstrap 5** grid and components
- **Materialize** theme from vendor package
- SCSS/CSS compiled via Vite → `/public/build/`
- Blade `@section('content')` for page content
- Modals use Bootstrap + SweetAlert2
- DataTables initialized with server-side processing
- Form validation via jQuery Validate or HTML5
- Select2 for searchable dropdowns
- Flatpickr / Bootstrap DatePicker for dates
- `resources/menu/` — sidebar menu config

---

## Key Configuration Files

| File | Purpose |
|------|---------|
| `config/app.php` | App name, debug, locale, providers |
| `config/auth.php` | Guards (web, api) |
| `config/permission.php` | Spatie permission settings |
| `config/imap.php` | Gmail IMAP for email parsing |
| `config/mail.php` | Gmail SMTP sending |
| `config/passport.php` | OAuth2 token expiry |
| `config/jetstream.php` | Team features toggle |
| `config/custom.php` | Theme/layout customization |
| `config/variables.php` | Template variables |
| `.env` | DB credentials, mail, IMAP, app keys |

---

## Running Commands

```bash
# Start local server
php artisan serve

# Compile assets (production)
yarn build

# Compile assets (dev with HMR)
yarn dev

# Run migrations
php artisan migrate

# Clear all caches
php artisan optimize:clear

# Process email inbox → tasks/tickets
php artisan emails:check-and-create-tasks

# Open tinker REPL
php artisan tinker
```

---

## Code Statistics

- **Models:** 40
- **Controllers:** 184 (core + template/UI examples)
- **Migrations:** 70+
- **Blade views:** 200+
- **Web routes:** ~150 registered routes
- **Config files:** 19