# Recommended Final Screen Structure

## Audit Session - 2026-05-29 11:38:13 +03:00

## Recommended Screens

| Screen | Purpose | Main Content | Main Actions | Allowed Roles | Required APIs | Current Status | Next Phase Work |
|---|---|---|---|---|---|---|---|
| Dashboard | Operational overview and quick access | KPI cards, active workload, queue count, recent activity | Open conversations, jump to queue/reports | Admin, Supervisor, Employee with scoped data | `/api/workspace/data`, reports summary API | Exists as custom chat workspace, mixed dashboard/chat | Split dashboard summary from chat workflow or clearly keep it as workspace. |
| Conversations | Main WhatsApp chat inbox | Scoped chat list, active chat, messages, details | Reply, mark read, close, transfer if allowed | Admin all, Supervisor team, Employee assigned only | `/api/conversations`, `/api/conversations/{id}`, `/messages`, `/mark-read`, `/close`, `/transfer` | Exists in both dashboard and Filament table | Choose primary UX; connect table/detail/chat into one coherent flow. |
| Waiting List | Unassigned/pending intake queue | Pending/unassigned conversations by priority/time | Assign to self/team member, transfer, escalate | Admin, Supervisor; Employee only if self-pick is allowed | New waiting-list API or `/api/conversations?status=pending` plus assignment API | Only filtered conversation table; no real intake routing | Implement real pending/unassigned status and assignment rules. |
| Contacts | Customer/contact directory | WhatsApp ID, name, assigned/dedicated agent, conversation history | View, edit metadata, set dedicated agent | Admin; Supervisor team contacts; Employee assigned contacts read-only | Contact list/detail APIs, conversation history | Exists as admin Filament resource | Align supervisor/employee access; wire dedicated agent into routing. |
| Assignment Log | Audit trail | Conversation, old/new assignee, assigned by, reason, timestamps | Filter/export/view linked conversation | Admin all, Supervisor team, Employee none or own audit only | Assignment list API/resource | Exists, but agent permission gap | Fix scoping and add export/filter clarity. |
| Team / Employees | Employee and team management | Employees, roles, teams, supervisors, active status, WABA phone IDs | Create/edit/deactivate employee, assign role/team/supervisor | Admin full; Supervisor team read-only or limited management | User/team APIs/resources | Users and Teams exist separately; confusing sidebar | Create one clear Employees screen and optional Teams subpage. |
| Reports | Business analytics | Conversation volume, response time, assignment load, employee/team performance | Filter by date/team/employee, export | Admin global, Supervisor team | New reports APIs | Missing; current link opens Webhook Events | Build actual report page; move Webhook Events to diagnostics. |
| Permissions | Role/permission management | Role matrix: screens/actions/data scopes | Edit role permissions if customizable | Admin | Roles/permissions APIs or Spatie resources | Missing; link opens Users | Decide fixed roles vs customizable permissions; implement accordingly. |
| Settings | System and WhatsApp settings | WhatsApp credentials status, default phone ID, routing rules, notification settings | Update routing/config, test credentials | Admin | Settings/config APIs | Missing; link opens Users | Create real settings page or remove from sidebar until ready. |

## Recommended Navigation Model

| Section | Screens |
|---|---|
| Workspace | Dashboard, Conversations, Waiting List |
| Customers | Contacts |
| Operations | Assignment Log, Reports |
| Administration | Team / Employees, Permissions, Settings |
| Diagnostics | Webhook Events, Horizon if needed |

## Recommended Role Access Matrix

| Screen | Admin | Supervisor | Employee |
|---|---|---|---|
| Dashboard | All data | Team data | Own data |
| Conversations | All conversations | Team conversations | Assigned conversations |
| Waiting List | All queue | Team queue | Optional own/self-pick only |
| Contacts | All contacts | Team contacts | Contacts for assigned conversations |
| Assignment Log | All assignments | Team assignments | No, or own conversation audit only |
| Team / Employees | Full CRUD | Team read-only or limited management | No |
| Reports | Global reports | Team reports | No or own productivity only |
| Permissions | Full | No | No |
| Settings | Full | No | No |

## Implementation Order for Phase 2

| Order | Work Item | Reason |
|---:|---|---|
| 1 | Fix test database isolation | Prevent more data loss during verification. |
| 2 | Freeze and correct route/screen map | Avoid implementing features against misleading sidebar targets. |
| 3 | Fix navigation shell | Users need consistent navigation before deeper workflows. |
| 4 | Fix permission gaps | Prevent data leakage before expanding screens. |
| 5 | Clarify employee creation and role assignment | Directly addresses current employee-management confusion. |
| 6 | Implement Waiting List rules | Needed for WhatsApp triage workflow. |
| 7 | Create real Reports, Permissions, Settings pages | Replace placeholder aliases. |
| 8 | Optimize navigation and polling | Performance fixes are safer after screen structure is stable. |