# System Restrictions & Access Control Matrix - Task Management

## 1. Executive Summary & Security Philosophy

The **Task Management** implements a multi-layered security and restriction architecture governed by the Principle of Least Privilege (PoLP). Access boundaries are enforced simultaneously at three distinct levels:
1. **HTTP & Routing Level**: Middleware pipelines (`auth`, `must_change_password`, `role:superadmin`, `role:superadmin|admin`, `JwtAuthenticate`).
2. **Component & Controller Level**: Livewire component state guards, query scopes, and API authorization checks.
3. **Database & Query Scoping Level**: Multi-tenant departmental isolation and assignee constraints embedded into Eloquent queries.

---

## 2. Role-Based Access Control (RBAC) Matrix

The system defines **4 primary roles**:

| Feature / Module | Super Admin (`superadmin`) | Admin (`admin`) | Team Lead (`team lead`) | User (`user`) |
| :--- | :---: | :---: | :---: | :---: |
| **System Dashboard** | Full Global Access | Department Scoped | Department Scoped | Restricted (Redirects to Tasks) |
| **Task Viewing** | All Tasks | All Dept Tasks | Own Dept Tasks | Assigned Tasks Only |
| **Task Creation** | Allowed (Global) | Allowed (Global) | Allowed (Own Dept) | **Forbidden (403)** |
| **Task Reassignment** | Allowed | Allowed | Allowed (Own Dept) | **Forbidden (403)** |
| **Task Status Update** | Full Control | Full Control | Full Control | Allowed (Assigned Tasks) |
| **Task Revision Request** | Allowed | Allowed | Allowed | Allowed (Assigned Tasks) |
| **Task Approval** | Allowed | Allowed | Allowed | **Forbidden (403)** |
| **Task Deletion** | Allowed | Allowed | Restricted | **Forbidden (403)** |
| **Menu Management CRUD** | Full Control | Read Only / Configured | Read Only / Configured | **Forbidden (No Access)** |
| **User Management** | Full Control (All Users) | Can manage non-superadmins | Department Members Only | **Forbidden (403)** |
| **Superadmin User Inspection** | Allowed | **Hidden / Restricted** | **Hidden / Restricted** | **Forbidden (403)** |
| **Department Management** | Full Control | Full Control | Read Only | **Forbidden (403)** |
| **Class & Subject CRUD** | Full Control | Allowed | Read Only | **Forbidden (403)** |
| **Access Control (Roles/Perms)**| Full Control | **Forbidden** | **Forbidden** | **Forbidden (403)** |
| **Activity / Audit Log** | Full Raw Logs | **Restricted** | **Forbidden** | **Forbidden (403)** |
| **System Settings** | Full Control | **Forbidden** | **Forbidden** | **Forbidden (403)** |
| **Reports Access** | Global (All Filters) | Dept & Task Wise | Dept & Team Wise | Own Dept & Personal Metrics Only |
| **Interactive API Docs** | Full Access | Accessible | Accessible | Restricted Web / Read Only |

---

## 3. Module-Specific Restriction Rules

### 3.1 Menu Management Restrictions
- **Super Admin**: Has unrestricted permission to create (`POST /admin/menus`), update (`PUT /admin/menus/{id}`), delete (`DELETE /admin/menus/{id}`), reorder, and activate/deactivate menu links.
- **Admin & Team Lead**:
  - Cannot alter sidebar menu configurations directly.
  - Can only view and navigate menus explicitly enabled and authorized by the Super Admin in the `menu_roles` permission registry.
- **User Role**:
  - Zero access to menu management interfaces.
  - Sidebar is stripped of administrative navigation. Users can only see **Tasks** and **My Profile**.

### 3.2 Task Management & Lifecycle Restrictions
- **Task Visibility Scoping**:
  - `superadmin`: Views every task in the system without constraint.
  - `admin`: Views tasks across departments; superadmin-authored or sensitive audit records are masked.
  - `team lead`: Strictly constrained to tasks belonging to their assigned `department_id`.
  - `user`: Strictly constrained to tasks where `assigned_to == auth()->user()->id` or tasks where they are an active subtask participant.
- **Creation & Modification Restrictions**:
  - Standard `user` role cannot create new tasks, update core task descriptors (title, priority, due date), assign users, or delete tasks.
  - Historical task attributes (such as previous subjects or classes linked to completed tasks) are protected from accidental alteration.
- **Revision & Approval State Machine**:
  - Users can submit work for review (`status = 'review'`) and submit revision feedback.
  - Final task sign-off and approval (`POST /tasks/{id}/approve` or `status = 'completed'`) requires `superadmin`, `admin`, or `team lead` authorization.

### 3.3 Dashboard Restrictions
- **Super Admin**: Sees global statistics across all departments, total active users, system completion ratios, and server load indicators.
- **Admin & Team Lead**: Dashboard metrics are partitioned by department. Admin cannot view superadmin performance figures.
- **User**: Direct access to `/dashboard` or `/` automatically redirects to `/tasks`. When personal summaries are rendered, users only see:
  - Personal assigned task count
  - Personal pending, in-progress, and review status breakdowns
  - Previous task summary and completion count

### 3.4 Reports & Analytics Restrictions
- **Super Admin**: Full multi-dimensional analytics:
  - Department-wise, task-wise, employee-wise, monthly, and weekly analytics.
  - Advanced cross-filtering by role, department, and custom user sets.
- **Admin & Team Lead**:
  - Department-wise and task-wise reporting within permitted departments.
  - Superadmin accounts and tasks are completely excluded from calculations and tables to prevent privilege leakage.
- **User Role**:
  - Strictly restricted from organizational cross-department analytics.
  - Can only view their own departmental metrics and personal productivity metrics:
    * Days to complete tasks
    * Personal timeline events
    * Task review ratio and revision frequency
    * Extension count indicators

---

## 4. Task State Machine & Color-Coded Extension Rules

To prevent workflow bottlenecks and enforce accountability, task extensions are governed by deterministic lifecycle rules:

```mermaid
stateDiagram-v2
    [*] --> Pending: Created (Admin / Lead)
    Pending --> InProgress: Assignee Starts Work
    InProgress --> Review: Assignee Submits for Review
    
    Review --> RevisionRequested: Reviewer Requests Changes
    RevisionRequested --> InProgress: Extension Incremented (+1)
    
    Review --> Completed: Approved by Admin / Lead
    Completed --> [*]
```

### Color-Coded Extension Rules:
When tasks are reviewed or completed, their visual badge and audit state reflects the number of revision extensions granted:
1. **0 Extensions (On Time)**:
   - **Badge**: `Green` (`bg-emerald-500/10 text-emerald-400 border-emerald-500/20`)
   - **Significance**: Task completed within original timeline without revision penalty.
2. **1st Extension (Moderate Delay)**:
   - **Badge**: `Yellow` (`bg-amber-500/10 text-amber-400 border-amber-500/20`)
   - **Significance**: Single revision required; flagged for monitoring.
3. **2+ Extensions (Critical Delay)**:
   - **Badge**: `Red` (`bg-rose-500/10 text-rose-400 border-rose-500/20`)
   - **Significance**: Excessive revisions; flagged in employee performance and bottleneck reports.

---

## 5. Workload Scheduling & Date Conflict Restrictions

The system prevents assignee fatigue and schedule overlapping through automated conflict detection:
1. **Date Capacity Limit**:
   - Assignees cannot be assigned concurrent critical tasks that exceed their daily capacity.
2. **Workload Check Endpoint (`/api/tasks/workload` & `/api/tasks/user-workload/{userId}`)**:
   - Before scheduling, managers can inspect assignee calendar density.
   - If an assignee is already booked for the target start and due dates, the system prompts with conflict warnings.

---

## 6. Authentication, Account & Session Restrictions

1. **Mandatory First-Time Password Change (`must_change_password`)**:
   - Newly created accounts have `must_change_password = true`.
   - The `must_change_password` middleware intercepts all requests to `/dashboard`, `/tasks`, and other routes, forcing redirect to `/force-change-password` until the user sets a secure credential.
2. **Deactivated Account Lockout (`is_active = false`)**:
   - If an administrator deactivates a user:
     - Web sessions are terminated immediately.
     - Login attempts return `HTTP 403 Forbidden: Your account has been deactivated.`
     - Subsequent `/api/fresh-token` requests for the user are rejected.
3. **Stateless API Security Restrictions**:
   - Bearer token must be an `access` token. Passing a `refresh` token as a Bearer authorization header returns `HTTP 401 Unauthorized`.
   - Access tokens strictly expire after **86400 seconds (24 hours)**. Expired tokens cannot invoke endpoints and must be refreshed via `/api/fresh-token`.
   - Single-use Refresh Token Rotation (RTR): After the 30-second concurrency grace window, reused refresh tokens are treated as potential replay attacks.