# ERP Financial Management Suite (EFMS) — Implementation Plan

## Architecture Context

This suite is built as new Django apps inside the **Horilla ERP** codebase (Django 5.2, MySQL 8, Python 3.12).

Key conventions observed in the codebase:
- **Models** extend `HorillaModel` (from `base`) for multi-tenant company-scoped filtering via `HorillaCompanyManager`
- **Views** mix FBVs and CBVs using `horilla_views` framework (`HorillaListView`, `HorillaFormView`)
- **HTMX** is used throughout for partial updates — no separate SPA
- **Permissions** are enforced via `accessibility` app decorators + `manager_can_enter`
- **Audit logs** use `simple_history` (`HorillaAuditLog`) on every model
- **Signals** handle state transitions and notifications
- **APScheduler** handles background/scheduled jobs
- **URL naming**: `{model}-list`, `create-{model}`, `update-{model}`, `delete-{model}`
- **Templates**: per-app under `{app}/templates/`, CBV templates under `cbv/{model}/`
- New apps must be added to `INSTALLED_APPS` in `horilla/settings.py`

---

## Module Breakdown

### MODULE 1 — Budget Management (`budget` app)
**Status:** 🔄 In Progress (current session)

**Scope:**
- Budget hierarchy: Budget Head → Sub-Head → Item (with unique codes)
- Allocation management by period (Annual / Quarterly / Monthly / Weekly)
- Tracked amounts: Allocated, Committed, Approved, Disbursed, Balance (real-time)
- Budget overrun handling: over-budget requests, variance display, approver notifications
- Bulk upload via Excel/CSV
- Department-based budgets

**Models:**
- `BudgetHead` — top-level budget category
- `BudgetSubHead` — second-level, FK to BudgetHead
- `BudgetItem` — leaf item, FK to BudgetSubHead; holds the allocated amounts
- `BudgetAllocation` — period-specific allocation record for a BudgetItem
- `BudgetTransaction` — records committed/approved/disbursed amounts against an allocation

**Key UI screens:**
- Budget structure management (Head / Sub-Head / Item CRUD)
- Allocation dashboard (real-time balance per item/period)
- Bulk upload screen

---

### MODULE 2 — Expense Management (`expense` app)
**Status:** 📋 Planned

**Scope:**
- Expense request submission (with document attachments)
- Budget code selection (Head → Sub-Head → Item)
- Full status lifecycle: Draft → Pending → Approved → Rejected → KIV → Resubmitted → Disbursed → Closed
- KIV (Kept In View) workflow: reason, revisit date, recall

**Models:**
- `ExpenseRequest` — main request with FK to BudgetItem
- `ExpenseDocument` — supporting attachments
- `ExpenseStatusLog` — immutable state history
- `KIVRecord` — stores KIV reason and revisit date

---

### MODULE 3 — Approval Workflow Engine (`approvals` app / integrated into expense & budget)
**Status:** 📋 Planned

**Scope:**
- Configurable approval chain: Applicant → HOD → Director → MD/Chairman → Accountant → Disbursement
- Threshold-based routing (HOD ≤ limit1, Director ≤ limit2, MD = unlimited)
- Approval stage tracking with comments
- Immutable audit logs per approval action
- Notifications at each stage

**Models:**
- `ApprovalWorkflow` — named workflow (e.g., "Expense Approval")
- `ApprovalStage` — each step in a workflow with approver role and threshold
- `ApprovalInstance` — a running approval process for a specific request
- `ApprovalAction` — each approve/reject/comment event (immutable)

---

### MODULE 4 — Income & Revenue Management (`revenue` app)
**Status:** 📋 Planned

**Scope:**
- Revenue hierarchy: Revenue Head → Sub-Head → Item (with revenue codes)
- Revenue recording and categorization
- Department-based tracking
- Budget-revenue alignment: every revenue item maps to a budget item
- Revenue dashboards and reports

**Models:**
- `RevenueHead`, `RevenueSubHead`, `RevenueItem`
- `RevenueRecord` — actual revenue entry with FK to RevenueItem
- `BudgetRevenueMapping` — links RevenueItem ↔ BudgetItem

---

### MODULE 5 — Payroll & Salary Structure (extends `payroll` app)
**Status:** 📋 Planned

**Scope (extends existing payroll app):**
- Salary structure templates with Grade Level → Step → Income Components
- Auto step progression (user-defined duration, default 12 months)
- Bulk grade/step movement tool
- Statutory schemes: Pension (PFA), NHF, NHIS/HMO, Cooperatives, Unions, Life Assurance
- Employee payroll setup: assign structure + grade + step + schemes + bank
- Full computation engine: gross, deductions, PAYE tax, net
- Multi-stage salary approval: Payroll Master → Chief Accountant → CEO → Execute Payment
- Bank payment integration hook

**New models (alongside existing payroll models):**
- `SalaryStructure`, `GradeLevel`, `Step`, `IncomeComponent`, `GradeStepValue`
- `PensionFundAdministrator`, `CooperativeSociety`, `UnionBody`, `HealthScheme`
- `EmployeePayrollSetup` (extends existing Contract)
- `EmployeeSchemeEnrollment`
- `PayrollRun`, `PayrollApproval`

---

## Session Progress

| Session | Work Done |
|---------|-----------|
| Session 1 (2026-06-22) | Repo setup, .venv (Python 3.12), PyMySQL swap, architecture study, planning doc, Module 1 implementation |