# System & UI/UX Design Specification - Task Management

## 1. Executive Summary & Design Philosophy

The **Task Management** is designed with a modern, high-density, real-time user experience that bridges productivity tooling with responsive reactive components. Built on **Tailwind CSS**, **Livewire 4**, and **Alpine.js**, the user interface provides instant state hydration, zero page reload transitions, and clear visual hierarchy optimized for fast decision-making.

---

## 2. UI/UX Design System & Theme Tokens

### 2.1 Color Palette & Visual Foundations
- **Background Canvas**: Deep Slate (`#090d16` to `#0f172a`), creating a distraction-free dark interface that reduces eye fatigue during extended planning sessions.
- **Surface & Cards**: Semi-transparent Slate (`rgba(30, 41, 59, 0.7)`), elevated with subtle 1px border borders (`rgba(255, 255, 255, 0.08)`) and soft ambient shadows.
- **Brand & Accent Colors**:
  - Primary Accent: **Vibrant Indigo / Crimson Red** (`#4f46e5` / `#ef4444`) for primary actions, active navigation items, and attention triggers.
  - Success State: **Emerald** (`#10b981`) for completed tasks, 0-extension deliveries, and positive indicators.
  - Warning State: **Amber** (`#f59e0b`) for pending reviews, upcoming deadlines, and 1st-extension tasks.
  - Danger / Urgent State: **Rose** (`#f43f5e`) for overdue deadlines, 2+ extensions, and critical errors.
- **Typography**: Clean sans-serif system stack (`system-ui`, `-apple-system`, `BlinkMacSystemFont`, `Inter`, `Segoe UI`) with strict typographic scaling (`xs`, `sm`, `base`, `lg`, `xl`, `2xl`).

### 2.2 Layout & Navigation Design
- **Collapsible Sidebar**:
  - Displays dynamic tenant menus filtered by authenticated user role.
  - Features quick-glance user badge, notification alerts, and instant logout action.
- **Header Bar**:
  - Global Search bar with debounce filtering.
  - Real-time `NotificationBell` with unread count indicator and audio/desktop alerts.
  - User identity avatar and shortcut to Profile management.
- **Workspace Views (Three-Way Task Perspective)**:
  1. **Calendar View (`TaskCalendarView`)**: Interactive monthly grid displaying date-wise task blocks, day-level inspection popups, and overdue markers.
  2. **Kanban View (`TaskKanbanView`)**: Agile 4-column board (`Pending`, `In Progress`, `Review`, `Completed`) with interactive status transitions and priority badges.
  3. **List View (`TaskListView`)**: High-density table featuring column sorting, bulk actions, priority tags, and quick-access action drawers.

---

## 3. Entity-Relationship (ER) & Database Design

```mermaid
erDiagram
    USERS ||--o{ TASKS : "creates / assigned_to"
    USERS }o--|| DEPARTMENTS : "belongs to"
    USERS }o--o| CLASSES : "enrolled in"
    USERS }o--o| SUBJECTS : "specializes in"
    USERS ||--o{ ACTIVITY_LOGS : "triggers"
    USERS ||--o{ NOTIFICATIONS : "receives"

    TASKS ||--o{ TASK_SUBTASKS : "contains"
    TASKS ||--o{ TASK_COMMENTS : "has"
    TASKS }o--o| VIDEOS : "references"
    TASKS }o--|| DEPARTMENTS : "assigned to department"

    MENUS ||--o{ MENU_ROLES : "configured for"
    ROLES ||--o{ MENU_ROLES : "grants access to"

    USERS {
        uuid id PK
        string name
        string email UK
        string mobile_number UK
        string password
        uuid class_id FK
        bigint department_id FK
        bigint subject_id FK
        string profile_photo_path
        boolean is_active
        boolean must_change_password
        timestamp last_login_at
        string last_login_ip
        timestamps created_at_updated_at
    }

    TASKS {
        bigint id PK
        string title
        text description
        string status "pending, in_progress, review, completed, revision"
        string priority "low, medium, high, urgent"
        uuid created_by FK
        uuid assigned_to FK
        bigint department_id FK
        bigint video_id FK
        date start_date
        date due_date
        time reminder_time
        integer extension_count
        timestamp completed_at
        timestamps created_at_updated_at
    }

    TASK_SUBTASKS {
        bigint id PK
        bigint task_id FK
        uuid assigned_to FK
        string title
        boolean is_completed
        integer order
        timestamps created_at_updated_at
    }

    TASK_COMMENTS {
        bigint id PK
        bigint task_id FK
        uuid user_id FK
        text comment
        string attachment_path
        timestamps created_at_updated_at
    }

    DEPARTMENTS {
        bigint id PK
        string name UK
        string code
        text description
        boolean is_active
        timestamps created_at_updated_at
    }

    CLASSES {
        uuid id PK
        string name
        string section
        boolean is_active
        timestamps created_at_updated_at
    }

    SUBJECTS {
        bigint id PK
        string name
        string code
        bigint publisher_id FK
        boolean is_active
        timestamps created_at_updated_at
    }

    ACTIVITY_LOGS {
        bigint id PK
        string action
        string module
        uuid user_id FK
        string user_name
        json payload
        string loggable_type
        bigint loggable_id
        timestamps created_at_updated_at
    }

    SYSTEM_SETTINGS {
        bigint id PK
        string key UK
        text value
        string type
        timestamps created_at_updated_at
    }
```

---

## 4. Component Hierarchy & Reactive Architecture

```mermaid
graph TD
    AppLayout["App Layout (resources/views/layouts/app.blade.php)"]
    Sidebar["Sidebar Component (views/components/sidebar.blade.php)"]
    Header["Navbar / NotificationBell (Livewire/NotificationBell.php)"]
    
    AppLayout --> Sidebar
    AppLayout --> Header
    AppLayout --> MainOutlet["Main Page Router Outlet"]

    MainOutlet --> TaskManager["TaskManager (Livewire/TaskManager.php)"]
    MainOutlet --> UserManager["UserManager (Livewire/UserManager.php)"]
    MainOutlet --> ReportManager["ReportManager (Livewire/ReportManager.php)"]
    MainOutlet --> DepartmentManager["DepartmentManager (Livewire/DepartmentManager.php)"]
    MainOutlet --> ClassManager["ClassManager (Livewire/ClassManager.php)"]
    MainOutlet --> AccessControlManager["AccessControlManager (Livewire/AccessControlManager.php)"]
    MainOutlet --> AuditLogManager["AuditLogManager (Livewire/AuditLogManager.php)"]
    MainOutlet --> SystemSettings["SystemSettings (Livewire/SystemSettings.php)"]

    TaskManager --> TaskCalendarView["TaskCalendarView (Monthly Grid)"]
    TaskManager --> TaskKanbanView["TaskKanbanView (4 Status Lanes)"]
    TaskManager --> TaskListView["TaskListView (Searchable Data Table)"]
    TaskManager --> TaskModal["Task Creation / Edit Modal (4-Person Subtasks)"]
    TaskManager --> TaskCommentDrawer["Task Comments & Discussion Drawer"]
    TaskManager --> TaskTimelineDrawer["Task Timeline & Audit Events Drawer"]
```

---

## 5. RESTful API Contract & Standardization

All REST endpoints follow a standardized, predictable JSON response envelope:

### 5.1 Success Response Schema
```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "responseMessage": "Operation completed successfully.",
  "data": { ... },
  "userDetails": { ... },
  "token": "eyJ0eXAiOiJKV1QiLC..."
}
```

### 5.2 Error Response Schema
```json
{
  "success": false,
  "message": "Validation failed for one or more fields.",
  "errors": {
    "mobile_number": ["The mobile number has already been taken."]
  }
}
```

### 5.3 HTTP Status Codes Standard:
- `200 OK`: Request succeeded with data payload.
- `201 Created`: Resource (task, comment, user) successfully created.
- `400 Bad Request`: Malformed payload or business logic constraint violation.
- `401 Unauthorized`: Missing, invalid, or expired JWT Bearer token.
- `403 Forbidden`: Authenticated user lacks required role/permission (e.g. `user` accessing admin APIs).
- `404 Not Found`: Target entity not found in database.
- `422 Unprocessable Entity`: Request validation failed.
- `500 Internal Server Error`: Unhandled server exception with sanitized public response.

---

## 6. Workflows & State Progression Diagrams

### 6.1 Task Creation & 4-Person Subtask Allocation
```mermaid
sequenceDiagram
    autonumber
    actor Creator as Admin / Team Lead
    participant TM as TaskManager (Livewire / API)
    participant DB as Relational Database
    participant Echo as Pusher WebSockets
    actor Workers as 4 Assigned Subtask Workers

    Creator->>TM: Fill Task Details + 4 Assignees + Video URL
    TM->>DB: Begin Database Transaction
    TM->>DB: Insert Task Record
    TM->>DB: Insert 4 TaskSubtask Records
    TM->>DB: Commit Transaction
    TM->>DB: Write ActivityLog Entry
    TM->>Echo: Broadcast TaskAssignedNotification to each assignee
    Echo-->>Workers: Real-time Alert & Notification Bell Badge Update
    TM-->>Creator: Flash Success & Render in Calendar/Kanban
```

### 6.2 Task Revision & Extension Increment Loop
```mermaid
sequenceDiagram
    autonumber
    actor Worker as Assignee / Worker
    participant System as Task Management
    actor Reviewer as Reviewer (Team Lead / Admin)

    Worker->>System: Submit Task for Review (status = 'review')
    System->>Reviewer: Send Review Ready Notification
    Reviewer->>System: Reject with Feedback (POST /tasks/{id}/revision)
    System->>System: Increment extension_count by 1
    System->>System: Set status = 'in_progress' or 'revision'
    System->>System: Update color badge (Yellow if 1st, Red if 2+)
    System->>Worker: Notify Revision Requested with Comments
    Worker->>System: Re-submit Revision
    Reviewer->>System: Approve Task (POST /tasks/{id}/approve)
    System->>System: Set status = 'completed', completed_at = now()
    System->>System: Update Final Report Metrics
```