# BJI OMS - Application Knowledge Base & Requirements

> [!IMPORTANT]
> **SYSTEM INSTRUCTIONS FOR AGENTS:**
> 1. **Context Loading**: Before starting any task or analysis, read this entire document.
> 2. **Analysis Commands**: If the user asks to "analyze requirements of [X]", use the Quick Reference in Section 2 to find the relevant logic.
> 3. **Logic Adherence**: All new features and modifications must strictly follow the Organizational Hierarchy (Section 3) and Aggregation Logic (Section 5).
> 4. **No Assumptions**: Do not assume generic organizational patterns. Follow the Unit → Ward → Thana → District hierarchy defined here.

---

This document serves as the primary source of truth for the **BJI Organization Management System (BJI OMS)**. It provides context for AI agents to understand the application's structure, hierarchy, and reporting logic.

## 1. Project Overview
BJI OMS is a comprehensive management and reporting system designed to track organizational activities, financial data (Baitulmal), and individual progress across a multi-level hierarchy.

- **Backend**: NestJS, PostgreSQL, TypeORM (and Prisma for schema management).
- **Frontend**: Next.js, React, Tailwind CSS (Vanilla CSS for custom styles).
- **Primary Entities**: Organizations, Users, Reports, Plannings.

## 2. Quick Reference for Analysis
Use these anchors when responding to analysis requests:
- **"analyze requirements of report"**: See Section 4B (Comprehensive Report) and Section 5 (Aggregation Logic).
- **"analyze requirements of organization"**: See Section 3 (Organizational Hierarchy).
- **"analyze requirements of personal report"**: See Section 4A (Personal Report).
- **"analyze requirements of users"**: See Section 5 (User Roles & Access Control).

---

## 3. Organizational Hierarchy
The system operates on a strict parent-child relationship. Data flow and access control are dictated by this hierarchy.

### Hierarchy Levels (Lowest to Highest)
1.  **Unit**: The foundation. All raw data starts here.
2.  **Ward**: Composed of multiple Units.
3.  **Thana**: Composed of multiple Wards (and sometimes direct Units).
4.  **District/City**: Composed of multiple Thanas.
5.  **Central**: The top-level authority.

**Key Rule**: Users assigned to a specific organization level can only manage data for that organization and its descendants.

---

## 4. Reporting System
The core of the application is the reporting engine, which is split into two main types:

### A. Personal Report (Daily/Monthly)
Tracks individual member activities:
- **Spiritual**: Quran Study, Hadith Read, Literature.
- **Dawah**: Contact with Dawah targets, Workers, and Members.
- **Social**: Social Work, Family Meetings, Professional Help.
- **Logistics**: Org Work Hours, Safar (Travel), Report Keeping.

### B. Comprehensive Report (Monthly Organizational)
A monthly summary for an organization.
- **For Units**: Manually entered by the Unit leadership.
- **For Higher Levels (Ward, Thana, etc.)**: Automatically aggregated from all descendant **Units**.
- **Adjustments**: Higher-level leaders can add "adjustments" or "remarks" that merge with the aggregated unit data.

#### Key Data Sections in Reports:
- `manpower`: Current numbers of members, activists, etc.
- `dawah`: Activities related to reaching new people.
- `finance / baitulmal`: Collection and expenditure tracking.
- `socialWork`: Public service activities.
- `programs`: Meetings, training sessions, and events.

---

## 5. Business Logic & Rules

### Data Aggregation
- When a report is requested for a "Ward", the system fetches all reports from its child "Units" for the specific year/month and sums their values.
- Recursive aggregation is used for higher levels (Thana, District) to ensure all underlying Unit data is included.

### User Roles & Permissions
- Permissions are tied to **Positions** within an **Organization**.
- **Admin**: Can create organizations and assign positions.
- **Executive**: Can view and edit reports for their level and below.

### Financial Rules (Baitulmal)
- Tracks various funds: `zakat`, `fitra`, `iftar`, `election_fund`, `shahid_fund`, etc.
- **Nisab**: Financial eligibility/threshold tracking for certain funds.

---

## 6. Implementation Patterns
- **JSON Fields**: Many report sections use JSONB in PostgreSQL to store flexible, schema-less data for specific modules (e.g., `unitDawat`, `socialWork`).
- **Entity Structure**: `Organization` has `parent_id` and `organization_level_id`.
- **Slug System**: Organizations and Positions use slugs for URL routing and identification.

---

## 7. Frontend Architecture (bjiweb)
The frontend is a Next.js application that communicates with the NestJS backend.

### Key UI Patterns
- **Modals**: Extensive use of modals for data entry in reporting and planning (e.g., `SocialWorkModal`, `BaitulmalModal`).
- **Accordions**: Reports are often displayed in segmented sections using accordions (e.g., `ReportAccordionSection.tsx`).
- **Dynamic Forms**: Forms are often generated or managed via centralized clients (e.g., `PlanningReportingClient.tsx`).
- **Printing**: Specialized templates (like `Template.ts`) are used for generating printable HTML/PDF reports with precise formatting.

### Component Structure
- `bjiweb/src/components/Reporting`: Components for viewing and editing reports.
- `bjiweb/src/components/Organization`: Components for managing the organizational tree and assignments.

---

## 8. How to Use This Document
When asked to "analyze requirements" or "perform a task" related to a specific module (e.g., "Report" or "User Management"), the AI Agent should:
1.  **Reference this file** to understand the entity relationships.
2.  **Verify the Hierarchy level** involved (Unit vs. Ward/Thana).
3.  **Confirm the Data Structure** (e.g., if it involves a JSON section in the Comprehensive Report).
4.  **Check Aggregation Rules** before modifying reporting logic.
5.  **Review Frontend Patterns** if the task involves UI changes (Modals, Accordions).

---
*Last Updated: 2026-05-09*