# BJI OMS Organizational Structure & Permissions

## Overview

The BJI OMS (Bangladesh Jatiyo Isha Organization Management System) has been configured with a comprehensive organizational hierarchy and role-based permission system based on Bangladeshi administrative divisions.

## Organizational Hierarchy

The system follows a 5-level hierarchical structure:

```
Central (National Level)
├── Divisions (Dhaka, Chittagong, Khulna, etc.)
│   ├── Cities (Dhaka City, Narayanganj, Chittagong, etc.)
│   │   ├── Thanas (Administrative blocks: Gulshan, Banani, Dhanmondi, etc.)
│   │   │   ├── Wards (Geographic areas with numbers: Ward 1, 2, 3, etc.)
│   │   │   │   └── Units (Community/operational units)
```

### Current Structure Example

**Dhaka Division:**
- **Dhaka City**
  - **Gulshan Thana**
    - Ward 1 → Gulshan Unity Hub
    - Ward 2 → Gulshan District Center
    - Ward 3 → Gulshan Community Unit
  - **Banani Thana**
    - Ward 1 → Banani Primary Unit
    - Ward 2 → Banani Secondary Unit
  - **Dhanmondi Thana**
    - Ward 1 → Dhanmondi Education Hub
    - Ward 2 → Dhanmondi Social Unit
- **Narayanganj City**
  - **Narayanganj Sadar Thana**
    - Ward 1 → Narayanganj Central Unit
    - Ward 2 → Narayanganj East Unit

**Chittagong Division:**
- **Chittagong City**
  - **Chawkbazar Thana**
    - Ward 1 → Chawkbazar Unit Alpha
    - Ward 2 → Chawkbazar Unit Beta
  - **Halishahar Thana**
    - Ward 1 → Halishahar Main Unit

**Khulna Division:**
- **Khulna City**
  - **Khulna Sadar Thana**
    - Ward 1 → Khulna Central Unit

## Role-Based Access Control

### Permission Categories

#### 1. **Users Management**
- `create` - Create new users
- `read` - View user information
- `update` - Modify user details
- `delete` - Remove users

#### 2. **Activities Management**
- `create` - Create activities
- `read` - View activities
- `update` - Modify activities
- `delete` - Remove activities

#### 3. **Reports Management**
- `create` - Create reports
- `read` - View reports
- `update` - Modify reports
- `delete` - Remove reports

#### 4. **Organization Management**
- `read` - View organizational data
- `update` - Modify organizational data

### Role Permissions by Level

| Role Level | Create Users | Manage Users | Create Activities | Create Reports | Delete Activities | Delete Reports |
|-----------|--------------|--------------|-------------------|---------------|-----------------|----|
| **Central Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **City Manager** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Thana Officer** | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| **Ward Coordinator** | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ |
| **Unit Member** | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |

## Demo Users & Login Credentials

### 1. Central Admin
- **Email:** `central@bjioms.com`
- **Password:** `central@bjioms.com`
- **Organization:** BJI OMS Central
- **Permissions:** Full access - can create users at all levels, manage all activities and reports
- **Can Create Users:** Yes

### 2. City Manager
- **Email:** `city@bjioms.com`
- **Password:** `city@bjioms.com`
- **Organization:** Division/City level
- **Permissions:** Can manage users within their city, create/update activities and reports
- **Can Create Users:** Yes

### 3. Thana Officer
- **Email:** `thana@bjioms.com`
- **Password:** `thana@bjioms.com`
- **Organization:** Thana level
- **Permissions:** Can create wards/units, manage activities and reports (cannot delete)
- **Can Create Users:** Yes

### 4. Ward Coordinator
- **Email:** `ward@bjioms.com`
- **Password:** `ward@bjioms.com`
- **Organization:** Ward level
- **Permissions:** Can create and view activities, view reports
- **Can Create Users:** No

### 5. Unit Member
- **Email:** `unit@bjioms.com`
- **Password:** `unit@bjioms.com`
- **Organization:** Unit level
- **Permissions:** Can only view and create activities
- **Can Create Users:** No

## Key Features

### 1. Hierarchical User Creation
- **Central Admin** can create users at any level with appropriate roles
- Each admin level can only create users within their jurisdiction
- Created users maintain parent-child relationships for audit trails

### 2. Activity Management
- Activities are created at specific organizational levels
- Each activity is tracked with creation date, creator, and organization
- Activity categories: training, event, meeting (extensible)

### 3. Permission Enforcement
- Role-based permissions are enforced at the API level
- Users can only access data within their organizational scope
- Permissions are granular (resource + action based)

### 4. Audit Trail
- All user creation is tracked with `createdBy` field
- Timestamps on all records for audit compliance
- Organizational hierarchy provides clear chain of command

## Database Schema

### Core Tables

```
Organizations
├── id (PK)
├── name
├── type (CENTRAL, CITY, THANA, WARD, UNIT)
├── division, city, thana, wardNumber, unitName
├── parentId (FK to Organizations)
└── timestamps

Roles
├── id (PK)
├── name
├── description
├── organizationId (FK)
└── timestamps

Permissions
├── id (PK)
├── name, description
├── resource, action
└── timestamps

Users
├── id (PK)
├── email, mobile, password
├── name, isActive
├── roleId (FK)
├── organizationId (FK)
├── canCreateUsers
├── createdByUserId (FK)
└── timestamps
```

## API Endpoints

### Seeding the Database

**Endpoint:** `POST /seed`

**Description:** Initializes the database with all organizational structure and demo users

**Response:**
```json
{
  "success": true,
  "message": "Database seeded successfully"
}
```

**Note:** This endpoint should be protected in production.

## How to Use

### 1. Initial Setup
```bash
# The system will automatically create the schema when the API starts
# Because TypeORM has synchronize: true in development

# To seed data:
curl -X POST http://localhost:3001/seed
```

### 2. Testing Different Roles

1. Login with `central@bjioms.com` to test full admin access
2. Login with `city@bjioms.com` to test city-level operations
3. Login with `thana@bjioms.com` to test thana-level operations
4. Login with `ward@bjioms.com` to test ward-level operations
5. Login with `unit@bjioms.com` to test unit-level operations

### 3. Creating New Users

**Central Admin** can create new users via API with proper roles assigned.

## Future Enhancements

1. **Custom Organizational Structure** - Admins can create additional divisions/cities
2. **Dynamic Permission Assignment** - Create custom roles with selected permissions
3. **Two-Factor Authentication** - Enhanced security for admin accounts
4. **Activity Approvals** - Multi-level approval workflow
5. **Reports Dashboard** - Organizational performance metrics
6. **Bulk User Import** - CSV-based user creation
7. **User Deactivation** - Soft delete functionality

## Notes

- All passwords are hashed using bcryptjs before storage
- Email addresses are unique across the system
- Mobile numbers are unique within the system
- The organizational hierarchy is immutable once created (parent cannot be changed)
- Permissions are evaluated at request time based on user's role

## Support

For questions or issues regarding the organizational structure and permissions:
1. Check this documentation
2. Review the database schema in `/bjiapp/src/common/entities/index.ts`
3. Review seed data service in `/bjiapp/src/common/services/seed-data.service.ts`