# Project Memory - Key Decisions

## Last Updated: 2026-05-29

---

## Architecture Decisions

### 1. Single `<div>` wrapper instead of `<x-filament-panels::page>`
- **Date**: 2026-05-29
- **Context**: Livewire threw `MultipleRootElementsDetectedException` when blade had multiple root elements
- **Decision**: Wrap entire blade in a single `<div>` root element instead of using `<x-filament-panels::page>`
- **Rationale**: The chat workspace is a custom SPA that doesn't need Filament page wrapper; single div avoids Livewire error

### 2. Conversation reuse across ALL statuses
- **Date**: 2026-05-29
- **Context**: Incoming WhatsApp messages were creating duplicate conversations for the same contact
- **Decision**: Search for ANY existing conversation by contact_id (not just open ones); reopen if closed
- **Rationale**: Prevents duplicate conversations; reusing is more intuitive than creating new ones

### 3. unread_count as DB column (not calculated)
- **Date**: 2026-05-29
- **Context**: Need to track unread messages per conversation efficiently
- **Decision**: Store `unread_count` and `last_read_at` as database columns on `conversations` table
- **Rationale**: Avoids counting messages per-request; faster for listing and filtering

### 4. Role names aligned with Spatie
- **Date**: 2026-05-29
- **Context**: Frontend used `manager/support` but backend used Spatie `admin/supervisor/agent`
- **Decision**: Use `admin`, `supervisor`, `agent` everywhere (frontend PERMISSIONS object, policy, controller)
- **Rationale**: Consistency with Spatie Permission package; avoids role mapping bugs

### 5. Unified theme via separate CSS file
- **Date**: 2026-05-29
- **Context**: Need consistent design across all Filament screens without modifying each resource
- **Decision**: Created `public/css/unified-theme.css` loaded via renderHook in AdminPanelProvider
- **Rationale**: Easier to maintain than modifying each Filament resource; global changes in one file

### 6. Textarea with auto-grow for chat composer
- **Date**: 2026-05-29
- **Context**: Chat input was `<input type="text">` — single line only, can't write multi-line messages
- **Decision**: Changed to `<textarea rows="1">` with JS auto-grow (max 150px)
- **Rationale**: Matches WhatsApp Web behavior; supports multi-line with Enter=send, Shift+Enter=newline

### 7. Three-layer CSS architecture
- **Date**: 2026-05-29
- **Context**: Multiple CSS files serve different purposes
- **Decision**: Maintain 3 separate CSS files:
  - `crm-theme.css` — Filament admin panel overrides
  - `chat-workspace.css` — WhatsApp workspace specific styles
  - `unified-theme.css` — Consistent design across all Filament screens
- **Rationale**: Separation of concerns; workspace has unique WhatsApp design while admin screens share unified theme