# Project Memory - Project Overview

## Last Updated: 2026-05-29 (Phase 4 — Final UI + Real-time + Advanced Complete)

---

## Project: WhatsApp Chat Manager CRM

### Tech Stack
- **Backend**: Laravel 11 (PHP 8.2.29)
- **Admin Panel**: Filament 3.3
- **Database**: SQLite
- **Frontend**: Livewire + Custom SPA (chat-workspace.blade.php)
- **Queue**: database driver (requires `php artisan queue:work --queue=webhooks,default`)
- **Language**: Arabic RTL

### Architecture
- Dashboard page (`Dashboard.php`) renders custom view `filament.pages.chat-workspace`
- Chat workspace is a full SPA: hides Filament sidebar/topbar, renders its own UI
- Three CSS layers:
  1. `crm-theme.css` — Filament admin panel overrides
  2. `chat-workspace.css` — WhatsApp workspace specific styles (1239 lines)
  3. `unified-theme.css` — Consistent design for all Filament screens (800+ lines)

### Key Models
- `Conversation` — Has `unread_count`, `last_read_at`; `system()` for bypassing AssignedScope
- `Contact` — WhatsApp contacts with phone numbers
- `Message` — Chat messages (incoming/outgoing)
- `Assignment` — Agent-to-conversation assignments
- `Team` — Agent teams for supervisor management
- `WebhookEvent` — Incoming WhatsApp webhook payloads

### Roles (Spatie Permission)
- `admin` — Full access to everything
- `supervisor` — Access to team conversations only
- `agent` — Access to own conversations only

### API Endpoints
- `GET /api/chat-workspace` — Workspace data (role-filtered)
- `POST /api/conversations/{id}/messages` — Send message
- `POST /api/conversations/{id}/transfer` — Transfer conversation
- `POST /api/conversations/{id}/close` — Close conversation
- `POST /api/conversations/{id}/mark-read` — Mark as read
- `POST /api/webhooks/whatsapp` — WhatsApp webhook receiver

### Critical Environment
- PHP must be `C:\php82\php.exe` (8.2.29) — XAMPP's PHP 8.1 causes fatal errors
- Queue worker must be running for WhatsApp webhooks
- APP_URL set to ngrok: `https://moved-glider-renewed.ngrok-free.app`
- `WHATSAPP_APP_SECRET` not configured — webhook verification will fail
- Real-time: Run `php artisan reverb:start` for WebSocket; falls back to 15s polling
- Broadcasting: `BROADCAST_CONNECTION=reverb` configured with Reverb

### Server
- Local: http://127.0.0.1:8000
- Public: https://moved-glider-renewed.ngrok-free.app

### File Map
| Path | Purpose |
|------|---------|
| `resources/views/filament/pages/chat-workspace.blade.php` | Main SPA view (906 lines, HTML+CSS+JS, polls at 15s with visibility pause) |
| `public/css/chat-workspace.css` | WhatsApp workspace styles |
| `public/css/unified-theme.css` | Unified Filament design |
| `public/css/crm-theme.css` | Filament admin overrides |
| `app/Http/Controllers/ChatWorkspaceController.php` | Role-filtered API data |
| `app/Http/Controllers/ConversationController.php` | Conversation CRUD + transfer + markAsRead |
| `app/Jobs/ProcessIncomingMessageJob.php` | Incoming message processing (dedup) |
| `app/Policies/ConversationPolicy.php` | Role-based authorization |
| `app/Models/Conversation.php` | Conversation model with scopes |
| `app/Providers/Filament/AdminPanelProvider.php` | Panel config, loads 3 CSS files |
| `routes/api.php` | All API routes (19 total) |
| `app/Filament/Resources/AutoReplyResource.php` | Auto Replies admin CRUD |
| `app/Http/Controllers/MediaController.php` | Media upload/show/download |
| `app/Http/Controllers/SearchController.php` | Message search (role-scoped) |
| `app/Http/Controllers/ExportController.php` | CSV export (conversations, performance) |
| `app/Models/MediaAttachment.php` | Media attachment model |
| `app/Models/AutoReply.php` | Auto reply rule model |
| `app/Models/ActivityTimeline.php` | Activity timeline model |