# Organizational Flow Diagram (Zilla Level & HQ Level)


This document explains the hierarchical workflow from Zilla level to HQ level, including the relationship between IC and Wings, and the escalation/reporting process.

---

## Zilla Level Flow

Field operations at the district (Zilla) level follow a structured chain of command:

FS ↔ FO ↔ AD ↔ JD/DD

### Roles at Zilla Level

* **FS — Field Staff**: Primary ground-level personnel who collect information and carry out field tasks.
* **JFO — Junior Field Officer**: Assists the FO, sometimes integrated within the FO role depending on structure.
* **FO — Field Officer**: Supervises field staff and reports to AD.
* **AD — Assistant Director**: Mid-level supervisor responsible for operational oversight.
* **DD — Deputy Director / JD — Joint Director**: Higher-level officers at Zilla level who manage ADs and coordinate with IC.

---

## IC (Incident Controller / In-Charge)

The **IC** acts as a pivotal connection between Zilla-level officers and HQ. IC is considered equivalent to a Wing at HQ.

### Important Notes:

* **IC and Wing are equivalent units.**
* Tasks and reports flow from Zilla → IC → Wing (HQ).
* Normally, **IC interacts directly with Wings** for escalation, reporting, or management.

---

## HQ Level Flow

Headquarters operates at a higher administrative structure:

Desk ↔ Sub‑Section ↔ Section ↔ Director

### Roles at HQ Level

* **Desk**: Basic operational unit handling incoming cases, updates, and routing.
* **Sub‑Section**: Supervises multiple desks.
* **Section**: Managed by senior officers, monitors multiple sub‑sections.
* **Dir — Director**: Final authority for the section; reports to DG.
* **DG — Director General**: Top authority in the hierarchy.

---

## System Interaction Between Zilla and HQ

### Normal Communication Flow

Zilla Officers → IC → Wing (HQ)

### Exception Case (Special Assignment)

If **DG or Director assigns any task directly to FS or lower-level officers**, then:

* That officer (FS, JFO, FO, AD, etc.) will receive **direct access** to the incident/task.
* They must report back up the chain as assigned.

---

## Complete Entity List

| Abbreviation | Full Form |
| ------------ | -------------------- |
| FS | Field Staff |
| JFO | Junior Field Officer |
| FO | Field Officer |
| AD | Assistant Director |
| DD | Deputy Director |
| JD | Joint Director |
| ADD | Additional Director |
| Dir | Director |
| DG | Director General |

---

# Incident Sharing Rules - Hierarchy-Based Access Control

## Overview

This document explains the sharing eligibility rules for incidents based on organizational hierarchy and zone/wing membership. The system uses a hierarchical model where users can share incidents with others based on their position in the organization.

---

## Hierarchy Levels

| Role | Level | Description |
|------|-------|-------------|
| **Director** | 1 | Top authority |
| **DG (Director General)** | 2 | Second highest authority |
| **Wing Head** | 3 | Manages wings at HQ level |
| **Zonal Incharge** | 4 | Manages zones, can cross-zone share |
| **Zonal Commander** | 5 | Commands within a zone |
| **Field Rep** | 6 | Field-level personnel (lowest) |

**Note:** Lower level number = Higher authority

---

## Sharing Rules by Role

### 1. Director (Level 1) and DG (Level 2)

**Can share with:** Everyone

- No restrictions
- Can share with all hierarchy levels
- Can share across all zones and wings
- Sharing reason: `"hierarchy"`

**Code Logic:**

if current_level == 1 or current_level == 2:
    return "hierarchy"  # Can see everyone

---

### 2. Wing Head (Level 3)

**Can share with:**
1. DG and Director (levels 1-2)
2. Other Wing Heads (level 3)
3. Users in their wing's zones (any level, if they belong to zones in the same wing)

**Restrictions:**
- Cannot share with users outside their wing's zones
- Cannot share with users in different wings

**Code Logic:**

elif current_level == 3:
    # Can see DG and Director
    if target_level <= 2 or target_level == 3:
        return "hierarchy"
    # Can see users in their wing's zones
    elif target_zones and current_wings and target_wings:
        if current_wings & target_wings:  # Same wing
            return "hierarchy"

**Example:**
- Wing Head in `wing-intelligence` can share with:
- All Directors and DGs
- Other Wing Heads
- Any user in zones that belong to `wing-intelligence`

---

### 3. Zonal Incharge (Level 4)

**Can share with:**
1. Wing Head and above (levels 1-3) in the same wing
2. Users in the same zone (any level)
3. Other Zonal Incharges (cross-zone sharing, if `can_cross_zone_share = True`)

**Restrictions:**
- Cannot share with users in different zones (unless cross-zone sharing is enabled)
- Cannot share with users in different wings (except higher levels)

**Code Logic:**

elif current_level == 4:
    # Can see Wing Head and above in same wing
    if target_level <= 3 and current_wings & target_wings or current_zones & target_zones:
        return "hierarchy"
    # Can cross-zone share with other incharges
    elif can_cross_zone and target_level == 4:
        return "cross_zone"

**Example:**
- Zonal Incharge in `zone-1` and `wing-intelligence` can share with:
- Directors, DGs, Wing Heads in `wing-intelligence`
- All users in `zone-1` (any level)
- Other Zonal Incharges in different zones (if cross-zone enabled)

---

### 4. Zonal Commander (Level 5)

**Can share with:**
1. Zonal Incharge and above (levels 1-4) in the same zone
2. Field Reps (level 6) in the same zone

**Restrictions:**
- Must be in the same zone
- Cannot share with users in different zones
- Cannot share with other Commanders (same level)

**Code Logic:**

elif current_level == 5:
    # Can see Incharge and above in same zone
    if (
        target_level <= 4
        and current_zones & target_zones
        or target_level == 6
        and current_zones & target_zones
    ):
        return "hierarchy"

**Example:**
- Zonal Commander in `zone-1` can share with:
- Zonal Incharge in `zone-1`
- Wing Head, Director, DG (if they're in `zone-1`)
- Field Reps in `zone-1`
- Cannot share with users in `zone-2`, `zone-3`, etc.

---

### 5. Field Rep (Level 6)

**Can share with:**
1. Zonal Commander (level 5) in the same zone
2. Zonal Incharge (level 4) in the same zone

**Restrictions:**
- Must be in the same zone
- Cannot share with other Field Reps (same level)
- Cannot share with users in different zones
- Cannot share with higher levels outside their zone

**Code Logic:**

elif current_level == 6:
    # Can see Commander and Incharge in same zone
    if target_level in [4, 5] and current_zones & target_zones:
        return "hierarchy"

**Example:**
- Field Rep in `zone-1` can share with:
- Zonal Commander in `zone-1`
- Zonal Incharge in `zone-1`
- Cannot share with:
- Other Field Reps
- Users in `zone-2`, `zone-3`, etc.
- Wing Head, Director, DG (unless they're in `zone-1`)

---

## Sharing Eligibility Matrix

| Your Role | Level | Can Share With | Zone/Wing Requirement |
|-----------|-------|----------------|----------------------|
| **Director** | 1 | All levels | No restriction |
| **DG** | 2 | All levels | No restriction |
| **Wing Head** | 3 | Levels 1-3, users in wing's zones | Same wing |
| **Zonal Incharge** | 4 | Levels 1-4 (same wing), all in same zone, other Incharges (cross-zone) | Same zone or same wing (for higher levels) |
| **Zonal Commander** | 5 | Levels 1-4, 6 (in same zone) | Same zone only |
| **Field Rep** | 6 | Levels 4-5 (in same zone) | Same zone only |

---

## Key Concepts

### 1. Zone Overlap (`current_zones & target_zones`)
- Users must share at least one zone to be eligible
- Example: If you're in `zone-1` and target is in `zone-1`, you can share
- If you're in `zone-1` and target is in `zone-2`, you cannot share (unless you're Director/DG)

### 2. Wing Overlap (`current_wings & target_wings`)
- Users must share at least one wing to be eligible
- Example: If you're in `wing-intelligence` and target is in `wing-intelligence`, you can share
- Used for Wing Head and Zonal Incharge sharing rules

### 3. Cross-Zone Sharing (`can_cross_zone_share`)
- Only Zonal Incharge (level 4) can cross-zone share
- Must have `can_cross_zone_share = True` in their profile
- Allows sharing with other Zonal Incharges in different zones
- Sharing reason: `"cross_zone"`

### 4. Hierarchy Direction
- Generally, sharing flows upward (lower levels share with higher levels)
- Director and DG can share with everyone (bidirectional)
- Same-level sharing is restricted (except Director/DG and cross-zone Incharges)

---

## Sharing Reasons

The system returns different sharing reasons:

- `"hierarchy"` - Standard hierarchy-based sharing (most common)
- `"cross_zone"` - Cross-zone sharing between Zonal Incharges
- `"incident_shared"` - User already has access to the incident (from incident context)
- `None` - Cannot share (user is filtered out)

---

## Flow Diagram

Director/DG (1-2)
    ↓ (can share with everyone)
Wing Head (3)
    ↓ (can share with same wing)
Zonal Incharge (4)
    ↓ (can share with same zone or cross-zone)
Zonal Commander (5)
    ↓ (can share with same zone)
Field Rep (6)
    ↓ (can only share upward)

---

## Examples

### Example 1: Field Rep Sharing
- **You:** Field Rep (level 6) in `zone-1`
- **Can share with:**
- Zonal Commander (level 5) in `zone-1` ✓
- Zonal Incharge (level 4) in `zone-1` ✓
- **Cannot share with:**
- Field Rep in `zone-1` ✗ (same level)
- Zonal Commander in `zone-2` ✗ (different zone)
- Wing Head ✗ (not in same zone)

### Example 2: Zonal Incharge Sharing
- **You:** Zonal Incharge (level 4) in `zone-1`, `wing-intelligence`
- **Can share with:**
- Director, DG, Wing Head in `wing-intelligence` ✓
- All users in `zone-1` (any level) ✓
- Other Zonal Incharges in different zones (if cross-zone enabled) ✓
- **Cannot share with:**
- Users in `zone-2` (unless cross-zone) ✗
- Users in `wing-operation` (unless higher level) ✗

### Example 3: Director Sharing
- **You:** Director (level 1)
- **Can share with:** Everyone (all levels, all zones, all wings) ✓

---

## Implementation Notes

1. **No Hierarchy Level = No Sharing**
- If a user has no `hierarchy_level`, they cannot be shared with
- The function returns `None` immediately

2. **Zone/Wing Matching**
- Uses set intersection (`&`) to check for overlap
- Users can belong to multiple zones/wings
- Sharing is allowed if there's any overlap

3. **Level Comparison**
- Uses numeric comparison (`<=`, `in`)
- Lower number = Higher authority
- Level 1 (Director) is highest, Level 6 (Field Rep) is lowest

---

## Summary

The sharing system enforces:
- **Hierarchical access control** - Users can share with their supervisors and peers in their organizational unit
- **Zone-based restrictions** - Most sharing requires zone overlap
- **Wing-based restrictions** - Higher-level sharing considers wing membership
- **Upward flow** - Lower levels share with higher levels
- **Top-level access** - Director and DG have unrestricted access

This ensures incidents are shared according to organizational structure and maintains proper access control boundaries.