# BJI OMS - Quick Reference Guide

## Quick Start - Test the Organizational Structure

### 1. Seed the Database
```bash
curl -X POST http://localhost:3001/seed
```

### 2. Login Credentials for Testing

| Role | Email | Password | Access Level |
|------|-------|----------|--------------|
| Central Admin | central@bjioms.com | central@bjioms.com | National |
| Central Zone Manager | dhaka_zone@bjioms.com | dhaka_zone@bjioms.com | Zone |
| City Manager | city_dhaka@bjioms.com | city_dhaka@bjioms.com | City |
| Thana Officer | thana_gulshan@bjioms.com | thana_gulshan@bjioms.com | Thana |
| Ward Coordinator | ward_1@bjioms.com | ward_1@bjioms.com | Ward |
| Unit Member | unit@bjioms.com | unit@bjioms.com | Unit |

## Organizational Structure Overview

```
BJI OMS Central (Admin: central@bjioms.com)
├── Dhaka Zone (Manager: dhaka_zone@bjioms.com)
│   ├── Dhaka City (Officer: city_dhaka@bjioms.com)
│   │   ├── Khilgaon Thana (Officer: thana_khilgaon@bjioms.com)
│   │   │   ├── 3 West (Coordinator: ward_1@bjioms.com)
│   │   │   │   └── Khilgaon Unity Hub (Member: unit@bjioms.com)
│   │   │   ├── Bhuiyan Para (Coordinator: ward_2@bjioms.com)
│   │   │   │   └── Khilgaon Unity Hub (Member: unit@bjioms.com)
│   │   │   └── 4 South (Coordinator: ward_3@bjioms.com)
│   │   │       └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │   ├── Banani Thana (Officer: thana_banani@bjioms.com)
│   │   │   ├── Ward 1 (Coordinator: ward_1@bjioms.com)
│   │   │   │   └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │   │   ├── Ward 2 (Coordinator: ward_2@bjioms.com)
│   │   │   │   └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │   │   └── Ward 3 (Coordinator: ward_3@bjioms.com)
│   │   │       └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │   └── Dhanmondi Thana (Officer: thana_dhanmondi@bjioms.com)
│   │       ├── Ward 1 (Coordinator: ward_1@bjioms.com)
│   │       │   └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │       ├── Ward 2 (Coordinator: ward_2@bjioms.com)
│   │       │   └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   │       └── Ward 3 (Coordinator: ward_3@bjioms.com)
│   │           └── Gulshan Unity Hub (Member: unit@bjioms.com)
│   └── Mymensingh Zone (Manager: mymensingh_zone@bjioms.com)
│       ├── Tangail City (Officer: tangail_city@bjioms.com)
│       └── Mymensingh City (Officer: mymensingh_city@bjioms.com)
└── Khulna Zone (Manager: khulna_zone@bjioms.com)
    └── Khulna City
        └── Khulna Sadar Thana
```

## User Permissions Matrix

### By Organization Level

**Central Level**
- ✅ Create users at any level
- ✅ Manage all users
- ✅ Create/read/update/delete activities
- ✅ Create/read/update/delete reports

**Division/City Level**
- ✅ Create users within their division
- ✅ Manage city activities
- ✅ Create/read/update/delete activities
- ✅ Create/read/update/delete reports

**Thana Level**
- ✅ Create wards/units
- ✅ Create/read/update activities (no delete)
- ✅ Create/read/update reports (no delete)

**Ward Level**
- ✅ Create activities
- ✅ Read reports
- ❌ Cannot create other users

**Unit Level**
- ✅ Create activities
- ✅ Read activities
- ❌ Cannot create users
- ❌ Cannot access reports

## Database Tables Created

1. **organizations** - Organizational hierarchy (5-level structure)
2. **roles** - Role definitions per organization
3. **permissions** - Fine-grained permissions (resource + action)
4. **users** - User accounts with roles and organizations
5. **personal_reports** - User-specific reports

## Key Fields

### Organizations Table
- `type`: CENTRAL, CITY, THANA, WARD, UNIT
- `parentId`: Parent organization reference
- `wardNumber`: Numeric identifier for wards
- `division`: Bangladeshi administrative division
- `city`: City name
- `thana`: Administrative block name
- `unitName`: Unit designation

### Users Table
- `canCreateUsers`: Boolean flag for user creation permission
- `roleId`: User's assigned role
- `organizationId`: User's organizational unit
- `createdByUserId`: Admin who created this user

## Testing Scenarios

### Scenario 1: Central Admin Creates City Manager
1. Login as central@bjioms.com
2. Use user creation endpoint with City Manager role
3. Assign to Dhaka Division organization
4. Verify access at city level

### Scenario 2: Thana Officer Creates Activity
1. Login as thana@bjioms.com
2. Create activity via API
3. Activity linked to Gulshan Thana
4. Verify city manager and admin can see it

### Scenario 3: Permission Denial
1. Login as ward@bjioms.com
2. Try to create user - request denied
3. Try to delete activity - request denied
4. Verify only create/read allowed

## API Response Codes

- `200` - Success
- `201` - Created
- `400` - Bad request
- `401` - Unauthorized
- `403` - Forbidden (permission denied)
- `404` - Not found
- `409` - Conflict (duplicate email/phone)
- `500` - Server error

## Important Notes

1. **Email Format:** All demo emails follow pattern: `level@bjioms.com`
2. **Unique Constraints:**
   - Email is globally unique
   - Mobile number is globally unique
   - Organization names are unique
3. **Hierarchical Integrity:**
   - Parent-child relationships are maintained
   - Deleting parent organization cascades to children
   - Users maintain audit trail via createdBy

## Troubleshooting

### Seed Fails
- Ensure database is running on localhost:5432
- Check DATABASE_URL in .env
- Verify PostgreSQL is accessible

### Users Can't Login
- Verify email/password from ORGANIZATIONAL_STRUCTURE.md
- Check user exists in users table
- Ensure account is active (isActive = true)

### Permission Denied on Valid Action
- Check user's role permissions
- Verify role assigned to user
- Check organization hierarchy

## Production Considerations

- [ ] Change all demo passwords
- [ ] Disable the `/seed` endpoint
- [ ] Enable authentication for all endpoints
- [ ] Set `synchronize: false` in TypeORM config
- [ ] Implement proper error handling
- [ ] Add audit logging
- [ ] Set up backups
- [ ] Enable HTTPS
- [ ] Implement rate limiting