Create one feature folder with name - Manage Roles & Manage Users
In Manage Roles - There will be 4 roles - Super Admin, IT Team, Delivery Management, Department user
Super admin users will have and see all functions
IT Team users will see only - Dashboard, Company, Notifications, manage profile (Just these 4 options)
Delivery Management users will see only - Dashboard, delivery management, notifications, manage profile  (Just these 4 options)
Department Users will see only - Dashboard, orders, notifications, manage profile  (Just these 4 options)

Master admin can add edit delete the users in any department...

And notifications, dashboard and details will be visible as per user... (Also create 4 mock users as per - master admin, it team, delivery management, department users - 4 different phone numbers with otp login)

ARCHITECTURE MUST FOLLOW = UI → Hook → Service → Adapter → API Client
Never skip a layer. Never reverse.

ADAPTER RULES:
A1: Only layer that calls apiClient. Never call apiClient from any other layer.
A2: Strip undefined before sending. Keep null (means "clear this value").
A3: Request → toSnakeCase(). Any File|Blob field → FormData not JSON.stringify.
A4: Response → toCamelCase().
A5: List response → PaginatedResponseDTO. Remap: current_page→page, per_page→perPage, keep total.
A6: Single/mutation response → ApiResponseDTO.
A7: Status 204 → return { success: true, message: '', data: null } without parsing body.
A8: Catch ALL errors → convert → throw ApiErrorDTO. Never throw raw.

SERVICE RULES:
S1: Calls adapter only. Never call apiClient directly.
S2: Return typed DTOs only. Never raw response wrapper.
S3: Only implement methods for endpoints in THIS module's contract.ts.
S4: Re-throw ApiErrorDTO. Never swallow.
S5: Services must remain stateless and pure. No localStorage, cookies, router, toast, caching, or UI logic.

HOOK RULES:
H1: Calls service only. Never call adapter or apiClient directly.
H2: State: data, loading (init true), error, refetch.
H3: After mutation success → refetch relevant list + toast.success(result.message)
H4: On error → toast.error(error.message) + setError(). Never re-throw.
H5: Toasts fire in hook only. Never in Page or Service.
H6: No optimistic updates unless explicitly commented.
H7: NEXT_PUBLIC_USE_MOCK=true → dynamic import mock inside conditional → return mock → skip service.
H8: Hooks orchestrate state only. No business logic, response transformation, sorting, filtering, mapping, or data shaping inside hooks.

PAGE RULES:
P1: Calls hook only. Never call service, adapter, or apiClient directly.
P2: Sub-components receive typed DTOs as props. Never the raw hook object.
P3: Always handle: loading → skeleton | error → message | empty → empty state.
P4: Never import service / adapter / apiClient.

DTO RULES:
All DTOs live in one file: features/{module}/dtos/{module}.dto.ts
D1: All fields camelCase. No snake_case ever.
D2: Request DTOs: no id, createdAt, updatedAt, no UI-only fields.
D3: field: type = required · field?: type = optional · field: type|null = nullable (null clears value on backend)
D4: All IDs: string (UUID). All dates: string (ISO 8601).
D5: Status types: union type defined per module inside its own DTO file. Values must match contract.ts enum array exactly.
D6: Request DTOs: FK IDs only (userId: string). No nested objects. ResponseDTO may nest only if API always returns it.
D7: Names: {Entity}ResponseDTO · {Entity}CreateRequestDTO · {Entity}UpdateRequestDTO · {Entity}FilterRequestDTO
D8: ResponseDTO always has id: string, createdAt: string, updatedAt: string.
D9: FilterRequestDTO: page? perPage? search? sortBy?: keyof {Entity}ResponseDTO sortOrder?: 'asc'|'desc' · {field}In?: string[] · {field}From?: string · {field}To?: string
D10: UpdateRequestDTO: every field listed explicitly. No Partial<T>, no Pick<T,K>.
D11: Child entities MUST include their direct parent foreign key in CreateRequestDTO (e.g., courseId, chapterId, userId).
D12: Enum union types must always be derived from readonly const arrays.

ERROR CHAIN:
Adapter → catch HTTP error → throw ApiErrorDTO
Service → catch ApiErrorDTO → re-throw
Hook    → catch ApiErrorDTO → toast.error() + setError()
Page    → reads hook state only

FOLDER STRUCTURE:
app/{module}/page.tsx                ← "use client" MUST be first line
app/{module}/[id]/page.tsx           ← ONLY if scope includes /:id

features/{module}/
  components/
  hooks/
  services/
  adapters/{module}.adapter.ts
  dtos/{module}.dto.ts               ← all DTOs in one file
  mocks/{module}.mock.ts
  contract.ts                        ← standalone, not imported anywhere in frontend

NEVER RECREATE — ALWAYS IMPORT
import { PaginatedResponseDTO, ApiResponseDTO, ApiErrorDTO } from '@/shared/common';
import { toCamelCase, toSnakeCase } from '@/shared/mappers';
// Never recreate: lib/apiClient.ts | shared/common.ts | shared/mappers.ts
// These already exist in the project. Import only.

CONTRACT FILE — features/{module}/contract.ts
Written now for the frontend. Used later by AI to generate the Laravel backend.
export const {Entity}Endpoints = {
// Include ONLY endpoints required by page scope (user-facing or user-managed CRUD)

list: { method: 'GET', path: '/entities', auth: false, defaultPerPage: 15 },
detail: { method: 'GET', path: '/entities/:id', auth: false },

create: { method: 'POST', path: '/entities', auth: true },
update: { method: 'PUT', path: '/entities/:id', auth: true },
delete: { method: 'DELETE', path: '/entities/:id', auth: true },

// Optional action endpoint (apply/book/etc.) — include only if needed
action: { method: 'POST', path: '/entities/:id/action', auth: true },
} as const;

Include create/update/delete ONLY if the given page scope supports user-managed CRUD. Otherwise, restrict to list/detail/action only.

export const {Entity}Validation = {
  // field names MUST match {Entity}CreateRequestDTO field names exactly
  fieldName: {
    required?: boolean   // → Laravel 'required' / 'sometimes'
    min?: number         // → Laravel 'min:N'
    max?: number         // → Laravel 'max:N'
    enum?: string[]      // → Laravel 'in:a,b,c' + enum column. Must match union type in DTO exactly.
    nullable?: boolean   // → Laravel 'nullable' + ->nullable()
    decimals?: boolean   // → decimal column (use with format:'number')
    format?: 'string' | 'email' | 'number' | 'boolean' | 'file' | 'uuid' | 'date'
  }
} as const;

export const {Entity}SoftDelete = false;

contract.ts is the backend source of truth for future Laravel generation.
DTO enums, validation, nullable fields, filters, and endpoint scopes must always stay synchronized with contract.ts.

// Only include endpoints this module actually uses.
// Validation SHOULD match CreateRequestDTO (best effort, not enforced).
// Not imported anywhere in the frontend.


MOCK FILE — features/{module}/mocks/{module}.mock.ts

import { PaginatedResponseDTO } from '@/shared/common';
import { {Entity}ResponseDTO } from '../dtos/{module}.dto';

export const mock{Entity}List: PaginatedResponseDTO<{Entity}ResponseDTO> = {
  data: [{ /* all required fields present. nullable fields = null, never omitted */ }],
  meta: { page: 1, perPage: 15, total: 1 },
};
export const mock{Entity}: {Entity}ResponseDTO = mock{Entity}List.data[0];

// ✅ inside hook — conditional dynamic import only
if (process.env.NEXT_PUBLIC_USE_MOCK === 'true') {
  const { mock{Entity}List } = await import('../mocks/{module}.mock');
  setData(mock{Entity}List); return;
}
// ❌ never top-level import of mock file anywhere

MISC
Auth: tokens in lib/apiClient.ts interceptors only. No other file reads auth.
TypeScript: strict: true. No any. Explicit return types on all async functions.

OUTPUT
1. Issues found (file · rule violated)
2. List of All fixed files