# Organizational Management API Documentation

## Overview

The Organizational Management API provides comprehensive CRUD operations for managing organizational structure including Units, Branches, Sub Branches, and Users. This API supports hierarchical relationships and tree structures for efficient organizational management.

## Base URL
```
/api/organizational
```

## Authentication
All endpoints require authentication via JWT token in the Authorization header:
```
Authorization: Bearer <jwt_token>
```

## Response Format
All responses follow this standard format:
```json
{
  "status": "success|error",
  "message": "Description of the operation",
  "data": {}, // Response data (for success)
  "error": "Error message" // Error details (for errors)
}
```

---

## 📁 UNIT MANAGEMENT

### Get All Units
**GET** `/units`

Retrieve all units with optional filtering and search capabilities.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search term for name, code, or description |
| `parent_id` | string | No | Filter by parent ID (use "null" for root units) |
| `is_active` | string | No | Filter by active status ("true", "false", or empty) |

#### Example Request
```bash
GET /api/organizational/units?search=engineering&parent_id=null&is_active=true
```

#### Example Response
```json
{
  "status": "success",
  "message": "Units retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Engineering Unit",
      "code": "ENG",
      "description": "Engineering and technical operations",
      "parent_id": null,
      "parent_name": null,
      "is_active": true,
      "created_by": 1,
      "created_by_name": "Admin User",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "children": []
    }
  ]
}
```

### Get Unit Tree Structure
**GET** `/units/tree`

Retrieve units in hierarchical tree structure.

#### Example Response
```json
{
  "status": "success",
  "message": "Unit tree retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Engineering Unit",
      "code": "ENG",
      "description": "Engineering and technical operations",
      "parent_id": null,
      "parent_name": null,
      "is_active": true,
      "created_by": 1,
      "created_by_name": "Admin User",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "children": [
        {
          "id": 2,
          "name": "Software Engineering",
          "code": "SE",
          "description": "Software development team",
          "parent_id": 1,
          "parent_name": "Engineering Unit",
          "is_active": true,
          "created_by": 1,
          "created_by_name": "Admin User",
          "created_at": "2024-01-15T11:00:00.000Z",
          "updated_at": "2024-01-15T11:00:00.000Z",
          "children": []
        }
      ]
    }
  ]
}
```

### Get Unit Statistics
**GET** `/units/statistics`

Retrieve statistical information about units.

#### Example Response
```json
{
  "status": "success",
  "message": "Unit statistics retrieved successfully",
  "data": {
    "total_units": 25,
    "root_units": 5,
    "child_units": 20,
    "active_units": 23,
    "inactive_units": 2
  }
}
```

### Get Unit by ID
**GET** `/units/:id`

Retrieve a specific unit by its ID.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Unit ID |

#### Example Response
```json
{
  "status": "success",
  "message": "Unit retrieved successfully",
  "data": {
    "id": 1,
    "name": "Engineering Unit",
    "code": "ENG",
    "description": "Engineering and technical operations",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "children": []
  }
}
```

### Create New Unit
**POST** `/units`

Create a new unit in the organizational structure.

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unit name (2-100 characters) |
| `code` | string | Yes | Unit code (2-20 characters, uppercase) |
| `description` | string | No | Unit description (max 500 characters) |
| `parent_id` | integer | No | Parent unit ID |

#### Example Request
```json
{
  "name": "Marketing Unit",
  "code": "MKT",
  "description": "Marketing and communications department",
  "parent_id": null
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Unit created successfully",
  "data": {
    "id": 3,
    "name": "Marketing Unit",
    "code": "MKT",
    "description": "Marketing and communications department",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T12:00:00.000Z",
    "updated_at": "2024-01-15T12:00:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "Unit name is required"
    },
    {
      "field": "code",
      "message": "Unit code must contain only uppercase letters, numbers, underscores, and hyphens"
    }
  ]
}
```

```json
{
  "status": "error",
  "message": "Error creating unit",
  "error": "Duplicate entry 'MKT' for key 'code'"
}
```

### Update Unit
**PUT** `/units/:id`

Update an existing unit.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Unit ID |

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Unit name (2-100 characters) |
| `code` | string | No | Unit code (2-20 characters, uppercase) |
| `description` | string | No | Unit description (max 500 characters) |
| `parent_id` | integer | No | Parent unit ID |
| `is_active` | boolean | No | Active status |

#### Example Request
```json
{
  "name": "Updated Marketing Unit",
  "description": "Updated marketing and communications department",
  "is_active": true
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Unit updated successfully",
  "data": {
    "id": 3,
    "name": "Updated Marketing Unit",
    "code": "MKT",
    "description": "Updated marketing and communications department",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T12:00:00.000Z",
    "updated_at": "2024-01-15T12:30:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Unit not found"
}
```

```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "Unit name must be between 2 and 100 characters"
    }
  ]
}
```

### Delete Unit
**DELETE** `/units/:id`

Delete a unit from the organizational structure.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Unit ID |

#### Example Response
```json
{
  "status": "success",
  "message": "Unit deleted successfully"
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Unit not found"
}
```

```json
{
  "status": "error",
  "message": "Error deleting unit",
  "error": "Cannot delete unit with existing branches"
}
```

#### Important Notes
- **Cascade Deletion**: Deleting a unit will also delete all associated branches and sub-branches
- **User References**: Users assigned to this unit will need to be reassigned before deletion
- **Soft Delete**: Consider using the update endpoint to set `is_active: false` instead of hard deletion

---

## 🌿 BRANCH MANAGEMENT

### Get All Branches
**GET** `/branches`

Retrieve all branches with optional filtering.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search term for name, code, or description |
| `unit_id` | integer | No | Filter by unit ID |
| `parent_id` | string | No | Filter by parent ID (use "null" for root branches) |
| `is_active` | string | No | Filter by active status |

#### Example Request
```bash
GET /api/organizational/branches?unit_id=1&is_active=true
```

### Get Branch Tree Structure
**GET** `/branches/tree`

Retrieve branches in hierarchical tree structure.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `unit_id` | integer | No | Filter by unit ID |

### Get Branch Statistics
**GET** `/branches/statistics`

Retrieve statistical information about branches.

### Get Branch by ID
**GET** `/branches/:id`

Retrieve a specific branch by its ID.

### Create New Branch
**POST** `/branches`

Create a new branch.

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Branch name (2-100 characters) |
| `code` | string | Yes | Branch code (2-20 characters, uppercase) |
| `description` | string | No | Branch description (max 500 characters) |
| `unit_id` | integer | Yes | Parent unit ID |
| `parent_id` | integer | No | Parent branch ID |

#### Example Request
```json
{
  "name": "Frontend Development",
  "code": "FE",
  "description": "Frontend development team",
  "unit_id": 1,
  "parent_id": null
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Branch created successfully",
  "data": {
    "id": 12,
    "name": "Frontend Development",
    "code": "FE",
    "description": "Frontend development team",
    "unit_id": 1,
    "unit_name": "Naval Headquarters",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T13:00:00.000Z",
    "updated_at": "2024-01-15T13:00:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "unit_id",
      "message": "Unit ID must be a positive integer"
    },
    {
      "field": "code",
      "message": "Branch code must contain only uppercase letters, numbers, underscores, and hyphens"
    }
  ]
}
```

```json
{
  "status": "error",
  "message": "Error creating branch",
  "error": "Foreign key constraint fails: unit_id does not exist"
}
```

### Update Branch
**PUT** `/branches/:id`

Update an existing branch.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Branch ID |

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Branch name (2-100 characters) |
| `code` | string | No | Branch code (2-20 characters, uppercase) |
| `description` | string | No | Branch description (max 500 characters) |
| `unit_id` | integer | No | Parent unit ID |
| `parent_id` | integer | No | Parent branch ID |
| `is_active` | boolean | No | Active status |

#### Example Request
```json
{
  "name": "Updated Frontend Development",
  "description": "Updated frontend development team",
  "is_active": true
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Branch updated successfully",
  "data": {
    "id": 12,
    "name": "Updated Frontend Development",
    "code": "FE",
    "description": "Updated frontend development team",
    "unit_id": 1,
    "unit_name": "Naval Headquarters",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T13:00:00.000Z",
    "updated_at": "2024-01-15T13:30:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Branch not found"
}
```

```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "unit_id",
      "message": "Unit ID must be a positive integer"
    }
  ]
}
```

### Delete Branch
**DELETE** `/branches/:id`

Delete a branch.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Branch ID |

#### Example Response
```json
{
  "status": "success",
  "message": "Branch deleted successfully"
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Branch not found"
}
```

```json
{
  "status": "error",
  "message": "Error deleting branch",
  "error": "Cannot delete branch with existing sub-branches"
}
```

#### Important Notes
- **Cascade Deletion**: Deleting a branch will also delete all associated sub-branches
- **User References**: Users assigned to this branch will need to be reassigned before deletion
- **Soft Delete**: Consider using the update endpoint to set `is_active: false` instead of hard deletion

---

## 🌱 SUB BRANCH MANAGEMENT

### Get All Sub Branches
**GET** `/sub-branches`

Retrieve all sub branches with optional filtering.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search term for name, code, or description |
| `branch_id` | integer | No | Filter by branch ID |
| `parent_id` | string | No | Filter by parent ID (use "null" for root sub branches) |
| `is_active` | string | No | Filter by active status |

### Get Sub Branch Tree Structure
**GET** `/sub-branches/tree`

Retrieve sub branches in hierarchical tree structure.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `branch_id` | integer | No | Filter by branch ID |

### Get Sub Branch Statistics
**GET** `/sub-branches/statistics`

Retrieve statistical information about sub branches.

### Get Sub Branch by ID
**GET** `/sub-branches/:id`

Retrieve a specific sub branch by its ID.

### Create New Sub Branch
**POST** `/sub-branches`

Create a new sub branch.

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Sub branch name (2-100 characters) |
| `code` | string | Yes | Sub branch code (2-20 characters, uppercase) |
| `description` | string | No | Sub branch description (max 500 characters) |
| `branch_id` | integer | Yes | Parent branch ID |
| `parent_id` | integer | No | Parent sub branch ID |

#### Example Request
```json
{
  "name": "React Development",
  "code": "REACT",
  "description": "React.js development team",
  "branch_id": 1,
  "parent_id": null
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Sub branch created successfully",
  "data": {
    "id": 15,
    "name": "React Development",
    "code": "REACT",
    "description": "React.js development team",
    "branch_id": 1,
    "branch_name": "CNS Sectt",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T14:00:00.000Z",
    "updated_at": "2024-01-15T14:00:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "branch_id",
      "message": "Branch ID must be a positive integer"
    },
    {
      "field": "code",
      "message": "Sub branch code must contain only uppercase letters, numbers, underscores, and hyphens"
    }
  ]
}
```

```json
{
  "status": "error",
  "message": "Error creating sub branch",
  "error": "Foreign key constraint fails: branch_id does not exist"
}
```

### Update Sub Branch
**PUT** `/sub-branches/:id`

Update an existing sub branch.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Sub branch ID |

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Sub branch name (2-100 characters) |
| `code` | string | No | Sub branch code (2-20 characters, uppercase) |
| `description` | string | No | Sub branch description (max 500 characters) |
| `branch_id` | integer | No | Parent branch ID |
| `parent_id` | integer | No | Parent sub branch ID |
| `is_active` | boolean | No | Active status |

#### Example Request
```json
{
  "name": "Updated React Development",
  "description": "Updated React.js development team",
  "is_active": true
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "Sub branch updated successfully",
  "data": {
    "id": 15,
    "name": "Updated React Development",
    "code": "REACT",
    "description": "Updated React.js development team",
    "branch_id": 1,
    "branch_name": "CNS Sectt",
    "parent_id": null,
    "parent_name": null,
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T14:00:00.000Z",
    "updated_at": "2024-01-15T14:30:00.000Z",
    "children": []
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Sub branch not found"
}
```

```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "branch_id",
      "message": "Branch ID must be a positive integer"
    }
  ]
}
```

### Delete Sub Branch
**DELETE** `/sub-branches/:id`

Delete a sub branch.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Sub branch ID |

#### Example Response
```json
{
  "status": "success",
  "message": "Sub branch deleted successfully"
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Sub branch not found"
}
```

```json
{
  "status": "error",
  "message": "Error deleting sub branch",
  "error": "Cannot delete sub branch with existing users"
}
```

#### Important Notes
- **User References**: Users assigned to this sub branch will need to be reassigned before deletion
- **Soft Delete**: Consider using the update endpoint to set `is_active: false` instead of hard deletion
- **Designation References**: Designations assigned to this sub branch will need to be reassigned before deletion

---

## 👥 USER MANAGEMENT

### Get All Users
**GET** `/users`

Retrieve all users with optional filtering.

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search term for name, email, or service number |
| `unit_id` | integer | No | Filter by unit ID |
| `branch_id` | integer | No | Filter by branch ID |
| `sub_branch_id` | integer | No | Filter by sub branch ID |
| `role_id` | integer | No | Filter by role ID |
| `is_active` | string | No | Filter by active status |

#### Example Request
```bash
GET /api/organizational/users?unit_id=1&role_id=3&is_active=true
```

### Get User Statistics
**GET** `/users/statistics`

Retrieve statistical information about users.

#### Example Response
```json
{
  "status": "success",
  "message": "User statistics retrieved successfully",
  "data": {
    "total_users": 150,
    "active_users": 145,
    "inactive_users": 5,
    "admin_users": 3,
    "manager_users": 12,
    "regular_users": 135
  }
}
```

### Get User by ID
**GET** `/users/:id`

Retrieve a specific user by their ID.

### Create New User
**POST** `/users`

Create a new user in the organizational structure.

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | User full name (2-100 characters) |
| `email` | string | Yes | User email address |
| `service_no` | string | No | Service number (3-20 characters) |
| `rank_id` | integer | No | User rank ID |
| `unit_id` | integer | No | Unit ID |
| `branch_id` | integer | No | Branch ID |
| `sub_branch_id` | integer | No | Sub branch ID |
| `department_id` | integer | No | Department ID |
| `designation_id` | integer | No | Designation ID |
| `phone` | string | No | Phone number |
| `mobile` | string | No | Mobile number |
| `alternative_mobile` | string | No | Alternative mobile number |
| `role_id` | integer | No | User role ID (default: 3) |
| `password` | string | No | User password (min 6 characters) |

#### Example Request
```json
{
  "name": "John Doe",
  "email": "john.doe@company.com",
  "service_no": "EMP001",
  "rank_id": 1,
  "unit_id": 1,
  "branch_id": 1,
  "sub_branch_id": 1,
  "department_id": 1,
  "designation_id": 1,
  "phone": "+1234567890",
  "mobile": "+1234567890",
  "role_id": 3,
  "password": "securepassword123"
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "id": 15,
    "name": "John Doe",
    "email": "john.doe@company.com",
    "service_no": "EMP001",
    "rank_id": 1,
    "rank_name": "Manager",
    "unit_id": 1,
    "unit_name": "Engineering Unit",
    "branch_id": 1,
    "branch_name": "Frontend Development",
    "sub_branch_id": 1,
    "sub_branch_name": "React Development",
    "department_id": 1,
    "department_name": "IT Department",
    "designation_id": 1,
    "designation_name": "Senior Developer",
    "phone": "+1234567890",
    "mobile": "+1234567890",
    "alternative_mobile": null,
    "role_id": 3,
    "role_name": "User",
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T14:00:00.000Z",
    "updated_at": "2024-01-15T14:00:00.000Z"
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "User name is required"
    },
    {
      "field": "email",
      "message": "Email must be a valid email address"
    },
    {
      "field": "password",
      "message": "Password must be at least 6 characters long"
    }
  ]
}
```

```json
{
  "status": "error",
  "message": "Error creating user",
  "error": "Duplicate entry 'john.doe@company.com' for key 'email'"
}
```

```json
{
  "status": "error",
  "message": "Error creating user",
  "error": "Foreign key constraint fails: unit_id does not exist"
}
```

### Update User
**PUT** `/users/:id`

Update an existing user.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | User ID |

#### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | User full name (2-100 characters) |
| `email` | string | No | User email address |
| `service_no` | string | No | Service number (3-20 characters) |
| `rank_id` | integer | No | User rank ID |
| `unit_id` | integer | No | Unit ID |
| `branch_id` | integer | No | Branch ID |
| `sub_branch_id` | integer | No | Sub branch ID |
| `department_id` | integer | No | Department ID |
| `designation_id` | integer | No | Designation ID |
| `phone` | string | No | Phone number |
| `mobile` | string | No | Mobile number |
| `alternative_mobile` | string | No | Alternative mobile number |
| `role_id` | integer | No | User role ID |
| `is_active` | boolean | No | Active status |

#### Example Request
```json
{
  "name": "John Smith",
  "email": "john.smith@company.com",
  "phone": "+1234567891",
  "mobile": "+1234567891",
  "role_id": 2,
  "is_active": true
}
```

#### Example Response
```json
{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "id": 15,
    "name": "John Smith",
    "email": "john.smith@company.com",
    "service_no": "EMP001",
    "rank_id": 1,
    "rank_name": "Manager",
    "unit_id": 1,
    "unit_name": "Engineering Unit",
    "branch_id": 1,
    "branch_name": "Frontend Development",
    "sub_branch_id": 1,
    "sub_branch_name": "React Development",
    "department_id": 1,
    "department_name": "IT Department",
    "designation_id": 1,
    "designation_name": "Senior Developer",
    "phone": "+1234567891",
    "mobile": "+1234567891",
    "alternative_mobile": null,
    "role_id": 2,
    "role_name": "Admin",
    "is_active": true,
    "created_by": 1,
    "created_by_name": "Admin User",
    "created_at": "2024-01-15T14:00:00.000Z",
    "updated_at": "2024-01-15T15:00:00.000Z"
  }
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "User not found"
}
```

```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Email must be a valid email address"
    },
    {
      "field": "role_id",
      "message": "Role ID must be a positive integer"
    }
  ]
}
```

```json
{
  "status": "error",
  "message": "Error updating user",
  "error": "Duplicate entry 'john.smith@company.com' for key 'email'"
}
```

### Delete User
**DELETE** `/users/:id`

Delete a user from the organizational structure.

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | User ID |

#### Example Response
```json
{
  "status": "success",
  "message": "User deleted successfully"
}
```

#### Error Responses
```json
{
  "status": "error",
  "message": "User not found"
}
```

```json
{
  "status": "error",
  "message": "Error deleting user",
  "error": "Cannot delete user with active sessions"
}
```

#### Important Notes
- **Soft Delete**: Users are soft deleted by setting `is_active: false` instead of hard deletion
- **Data Integrity**: User data is preserved for audit and reporting purposes
- **Sessions**: Active user sessions should be terminated before deletion
- **References**: Consider reassigning any user-specific data before deletion

---

## 🔒 PERMISSIONS & AUTHORIZATION

### Required Permissions

| Operation | Required Role | Description |
|-----------|---------------|-------------|
| **View Operations** | User+ | All authenticated users can view organizational data |
| **Create Operations** | Manager+ | Managers and above can create new organizational units |
| **Update Operations** | Manager+ | Managers and above can update organizational data |
| **Delete Operations** | Admin+ | Only admins can delete organizational units |

### Role Hierarchy
1. **Super Admin** - Full access to all operations
2. **Admin** - Can manage all organizational units and users
3. **Manager** - Can manage units, branches, sub branches, and users within their scope
4. **User** - Can only view organizational data

---

## 📊 VALIDATION RULES

### Unit Validation
- **Name**: 2-100 characters, alphanumeric with spaces, hyphens, underscores, ampersands, periods, and parentheses
- **Code**: 2-20 characters, uppercase letters, numbers, underscores, and hyphens only
- **Description**: Maximum 500 characters
- **Parent ID**: Must be a valid existing unit ID or null

### Branch Validation
- **Name**: 2-100 characters, alphanumeric with spaces, hyphens, underscores, ampersands, periods, and parentheses
- **Code**: 2-20 characters, uppercase letters, numbers, underscores, and hyphens only
- **Description**: Maximum 500 characters
- **Unit ID**: Must be a valid existing unit ID
- **Parent ID**: Must be a valid existing branch ID or null

### Sub Branch Validation
- **Name**: 2-100 characters, alphanumeric with spaces, hyphens, underscores, ampersands, periods, and parentheses
- **Code**: 2-20 characters, uppercase letters, numbers, underscores, and hyphens only
- **Description**: Maximum 500 characters
- **Branch ID**: Must be a valid existing branch ID
- **Parent ID**: Must be a valid existing sub branch ID or null

### User Validation
- **Name**: 2-100 characters, letters, spaces, hyphens, apostrophes, and periods only
- **Email**: Valid email format, will be normalized
- **Service Number**: 3-20 characters, uppercase letters, numbers, underscores, and hyphens only
- **Phone Numbers**: 7-15 digits with optional country code and formatting
- **Mobile Numbers**: 10-15 digits with optional country code and formatting
- **Password**: Minimum 6 characters (if provided)

---

## 🚨 ERROR HANDLING

### Common Error Responses

#### 400 Bad Request
```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "Unit name is required"
    }
  ]
}
```

#### 401 Unauthorized
```json
{
  "status": "error",
  "message": "Authentication required"
}
```

#### 403 Forbidden
```json
{
  "status": "error",
  "message": "Insufficient permissions"
}
```

#### 404 Not Found
```json
{
  "status": "error",
  "message": "Unit not found"
}
```

#### 500 Internal Server Error
```json
{
  "status": "error",
  "message": "Error creating unit",
  "error": "Database connection failed"
}
```

---

## 📝 USAGE EXAMPLES

### Creating a Complete Organizational Structure

1. **Create Root Unit**
```bash
POST /api/organizational/units
{
  "name": "Engineering Division",
  "code": "ENG",
  "description": "Engineering and technical operations"
}
```

2. **Create Branch under Unit**
```bash
POST /api/organizational/branches
{
  "name": "Software Development",
  "code": "SD",
  "description": "Software development team",
  "unit_id": 1
}
```

3. **Create Sub Branch under Branch**
```bash
POST /api/organizational/sub-branches
{
  "name": "Frontend Team",
  "code": "FE",
  "description": "Frontend development team",
  "branch_id": 1
}
```

4. **Create User in Organizational Structure**
```bash
POST /api/organizational/users
{
  "name": "Jane Smith",
  "email": "jane.smith@company.com",
  "service_no": "EMP002",
  "unit_id": 1,
  "branch_id": 1,
  "sub_branch_id": 1,
  "role_id": 3
}
```

### Retrieving Hierarchical Data

1. **Get Complete Unit Tree**
```bash
GET /api/organizational/units/tree
```

2. **Get Branches for Specific Unit**
```bash
GET /api/organizational/branches/tree?unit_id=1
```

3. **Get Sub Branches for Specific Branch**
```bash
GET /api/organizational/sub-branches/tree?branch_id=1
```

### Filtering and Searching

1. **Search Units**
```bash
GET /api/organizational/units?search=engineering
```

2. **Filter Active Branches**
```bash
GET /api/organizational/branches?is_active=true
```

3. **Get Users by Unit**
```bash
GET /api/organizational/users?unit_id=1&is_active=true
```

---

## 🔧 TECHNICAL NOTES

### Database Relationships
- **Units** can have parent-child relationships (self-referencing)
- **Branches** belong to Units and can have parent-child relationships
- **Sub Branches** belong to Branches and can have parent-child relationships
- **Users** can be assigned to Units, Branches, and Sub Branches

### Performance Considerations
- All endpoints support pagination through query parameters
- Tree structures are optimized for efficient retrieval
- Search functionality uses database indexes for fast queries
- Statistics endpoints provide aggregated data without full table scans

### Security Features
- All endpoints require JWT authentication
- Role-based access control for different operations
- Input validation prevents SQL injection and XSS attacks
- Rate limiting prevents abuse

### Data Integrity
- Foreign key constraints ensure referential integrity
- Soft deletes preserve data relationships
- Validation prevents orphaned records
- Audit trails track all changes

---

## 📞 SUPPORT

For technical support or questions about this API:

1. Check the error messages for specific validation issues
2. Verify authentication tokens are valid and not expired
3. Ensure required fields are provided in requests
4. Check database connectivity if experiencing server errors

For additional help, refer to the main API documentation or contact the development team.

---

## 🎯 COMPLETE CRUD OPERATIONS SUMMARY

### 🏢 **Units Management**
- ✅ **CREATE**: `POST /units` - Add new organizational units
- ✅ **READ**: `GET /units` - List all units with filtering
- ✅ **READ**: `GET /units/:id` - Get specific unit details
- ✅ **READ**: `GET /units/tree` - Get hierarchical unit structure
- ✅ **READ**: `GET /units/statistics` - Get unit statistics
- ✅ **UPDATE**: `PUT /units/:id` - Update unit information
- ✅ **DELETE**: `DELETE /units/:id` - Remove units (with cascade)

### 🌿 **Branches Management**
- ✅ **CREATE**: `POST /branches` - Add new branches under units
- ✅ **READ**: `GET /branches` - List all branches with filtering
- ✅ **READ**: `GET /branches/:id` - Get specific branch details
- ✅ **READ**: `GET /branches/tree` - Get hierarchical branch structure
- ✅ **READ**: `GET /branches/statistics` - Get branch statistics
- ✅ **UPDATE**: `PUT /branches/:id` - Update branch information
- ✅ **DELETE**: `DELETE /branches/:id` - Remove branches (with cascade)

### 🌱 **Sub Branches Management**
- ✅ **CREATE**: `POST /sub-branches` - Add new sub branches under branches
- ✅ **READ**: `GET /sub-branches` - List all sub branches with filtering
- ✅ **READ**: `GET /sub-branches/:id` - Get specific sub branch details
- ✅ **READ**: `GET /sub-branches/tree` - Get hierarchical sub branch structure
- ✅ **READ**: `GET /sub-branches/statistics` - Get sub branch statistics
- ✅ **UPDATE**: `PUT /sub-branches/:id` - Update sub branch information
- ✅ **DELETE**: `DELETE /sub-branches/:id` - Remove sub branches

### 👥 **Users Management**
- ✅ **CREATE**: `POST /users` - Add new users to organizational structure
- ✅ **READ**: `GET /users` - List all users with filtering
- ✅ **READ**: `GET /users/:id` - Get specific user details
- ✅ **READ**: `GET /users/statistics` - Get user statistics
- ✅ **UPDATE**: `PUT /users/:id` - Update user information
- ✅ **DELETE**: `DELETE /users/:id` - Soft delete users

### 🔧 **Key Features Implemented**

#### **Database Schema Updates**
- ✅ Added `code` fields to all organizational tables (units, branches, sub_branches)
- ✅ Added `parent_id` fields for hierarchical relationships
- ✅ Added `created_by` fields for audit tracking
- ✅ Added proper indexes and foreign key constraints
- ✅ Updated sample data with realistic organizational structure

#### **API Enhancements**
- ✅ Complete CRUD operations for all entities
- ✅ Comprehensive error handling and validation
- ✅ Detailed request/response documentation
- ✅ Role-based access control
- ✅ Hierarchical tree structure support
- ✅ Statistics and reporting endpoints

#### **Documentation Improvements**
- ✅ Detailed request/response examples
- ✅ Error response documentation
- ✅ Validation rules and constraints
- ✅ Permission and authorization details
- ✅ Important notes and best practices

### 🚀 **Ready for Production**

The Organizational Management API is now fully documented and ready for production use with:
- **Complete CRUD Operations** for all organizational entities
- **Hierarchical Structure Support** with parent-child relationships
- **Role-Based Access Control** with proper permissions
- **Comprehensive Error Handling** with detailed error messages
- **Full Documentation** with examples and best practices
- **Database Schema** updated with all required fields
- **Sample Data** for testing and development

All endpoints are functional and properly documented! 🎉