> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HR Reports hub

> The HR Reports hub is the single place to pull people-and-pay data out of Hitaji 360 — who was paid what, how to pay it across the banks, how much PAYE…

The HR Reports hub is the single place to pull people-and-pay data out of Hitaji 360 — who was paid what, how to pay it across the banks, how much PAYE has been withheld, where leave balances stand, and so on. Each report runs against the data for the **business you currently have selected**, so the numbers you see always belong to that one business's employees and payroll.

Reports here are read-only "run and view" screens: you pick a date range (or a year), press **Run**, read the table, and — on the reports that support it — export the result to CSV. Nothing you do on a report changes any record.

**You'll find this at:** `/hr/reports`

> 📷 *Screenshot: HR Reports hub — the grid of report cards, with three "Open" cards and the rest carrying a "Coming soon" badge — to be added.*

***

## Before you start

* **Which business am I in?** Every report is scoped to the business in the business switcher at the top of the app. The server enforces this: even if an old link carries a `businessId`, the report only ever returns the data for the business your session is actually attached to, so you cannot accidentally widen a report to another business's payroll. If a report comes back empty, first check you are in the right business.
* **You need read access to HR.** The hub and most reports open for anyone with HR read permission (see [Permissions](#permissions) below).
* **Payroll reports need payroll data.** The pay-related reports (Salary Register, Bank Remittance, Income Tax, Provident Fund) read from **submitted payslips**. If payroll has not been run and submitted for the window you pick, the report will be empty even though the configuration is correct.

***

## What's on the hub

The hub lays out nine report cards. Three are **fully built screens** you can open today; the rest show a **"Coming soon"** badge with an **"API ready"** button — the data is computed by the backend but the dedicated screen is still being finished.

| Report                    | Status on the hub                                                         | Where it lives                       |
| ------------------------- | ------------------------------------------------------------------------- | ------------------------------------ |
| Salary Register           | Open                                                                      | `/hr/reports/salary-register`        |
| Bank Remittance           | Open                                                                      | `/hr/reports/bank-remittance`        |
| Income Tax Computation    | Open                                                                      | `/hr/reports/income-tax-computation` |
| Leave Balance             | "Coming soon" badge — **but a working screen actually exists** (see note) | `/hr/reports/leave-balance`          |
| Leave Ledger              | "Coming soon" badge — **but a working screen actually exists** (see note) | `/hr/reports/leave-ledger`           |
| Employee Advance Summary  | "Coming soon" (API ready, no screen)                                      | *deferred*                           |
| Employee Exits            | "Coming soon" (API ready, no screen)                                      | *deferred*                           |
| Employee Birthdays        | "Coming soon" (API ready, no screen)                                      | *deferred*                           |
| Provident Fund Deductions | "Coming soon" (API ready, no screen)                                      | *deferred*                           |

> ⚠️ **Current state — Leave Balance & Leave Ledger:** the hub cards for these two still show a **"Coming soon"** badge and a disabled button, yet working report screens **do** exist at `/hr/reports/leave-balance` and `/hr/reports/leave-ledger` (they are reachable from the [Leave reports](/hr/user/leave/leave-reports) page). The badge is out of date and is flagged for the team. Until the hub is corrected, reach these two through the Leave area rather than from this hub.

> ⚠️ **Current state — the four "API ready" reports** (Advance Summary, Employee Exits, Employee Birthdays, Provident Fund Deductions): the backend endpoints under `/api/hr/reports/...` are live and return data, but the on-screen pages were deliberately deferred. Their cards are not clickable. They are listed below for completeness so you know what is coming.

***

## The three live reports

### Salary Register

**You'll find this at:** `/hr/reports/salary-register`

A per-employee list of what each person earned and was deducted over a date range, drawn from their **payslips**. This is the report you reach for when someone asks "show me everyone's gross, deductions and net for last month."

> 📷 *Screenshot: Salary Register with the filter bar and an expanded employee row showing earnings/deductions — to be added.*

**Filters**

| Filter                       | Notes                                                                                                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **From date / To date**      | The pay window. Defaults to the current calendar month (first to last day).                                                                                                     |
| **Business**                 | Shown read-only — it always uses your active business.                                                                                                                          |
| **Department / Cost centre** | An optional free-text box that filters the rows already on screen (it matches against department or designation). This is a client-side convenience filter, not a server query. |

**Columns:** Employee (name + number), Department (+ designation), Days (payment days), Gross, Deductions, Net. Each row **expands** to show the full **earnings** and **deductions** component breakdown. A **Totals** row at the bottom sums gross, deductions and net across all employees shown.

**Export:** **Export CSV** downloads the visible rows (employee number, name, department, designation, payment days, base salary, gross, deductions, net).

### Bank Remittance

**You'll find this at:** `/hr/reports/bank-remittance`

The list you hand to (or upload to) the bank to actually pay salaries. It takes the **submitted payslips** for a pay window and groups them by the employee's **bank account**, so you can see exactly how much goes to each bank, plus a separate list of employees who have **no bank details on file** so payroll can chase them before the run.

> 📷 *Screenshot: Bank Remittance grouped by bank, with the "unbanked employees" card — to be added.*

**Filters:** From date / To date (defaults to the current month) and the read-only active Business.

**What you get:** payslips **grouped by bank**, each group showing the bank name, account number and per-employee net-pay rows with a group total; an **unbanked employees** card; and overall totals (banked vs unbanked slip counts and net pay). Bank name, branch, account name/number, SWIFT and currency come straight off each employee's saved bank details.

### Income Tax Computation

**You'll find this at:** `/hr/reports/income-tax-computation`

A PAYE position per active contract: how much income tax has been **withheld so far this fiscal year** and a **projection for the full year** based on the average monthly PAYE to date. Useful for year-end tax planning and for spotting under/over-withholding before the financial year closes.

> 📷 *Screenshot: Income Tax Computation table with the fiscal-year filter — to be added.*

**Filters**

| Filter                       | Notes                                                                                                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fiscal year (start year)** | Enter the *start* year. The Ugandan fiscal year runs **July → June**, so entering `2026` means Jul 2026 → Jun 2027 (the form spells this out under the field). |
| **As of (optional)**         | Cut the year-to-date figures at a chosen date. Leave it blank to use the latest data.                                                                          |
| **Business**                 | Read-only active business.                                                                                                                                     |

**Columns:** Employee (number + name), Fiscal Year, Months Done, Months Left, Taxable YTD, PAYE Withheld YTD, Avg Monthly PAYE, Projected Full-Year PAYE — plus a totals row. **Export CSV** is available.

***

## The "API ready" reports (no screen yet)

These four are computed by the backend (`/api/hr/reports/...`) but have **no clickable page** on the hub. They are documented here so you know what each will show once its screen ships.

* **Employee Advance Summary** — per requestor, how much has been **disbursed, deducted and is still outstanding** as of a chosen date. (Today, see staff advances in the [Employee loans](/hr/user/payroll/employee-loans) area.)
* **Employee Exits** — terminations within a date window, with each person's **years of service**.
* **Employee Birthdays** — employees whose birthday falls in a chosen month / day window.
* **Provident Fund Deductions** — an annual roll-up of **NSSF / PF / Pension** contributions per contract, for a fiscal year (optionally filtered to specific contribution kinds).

***

## HR reports here vs payroll reports

This hub carries the **HR-side** reports (salary register, bank remittance, income tax, leave, advances, exits, birthdays, provident fund). The deeper **payroll-run reports** — those tied to a specific payroll run and its statutory schedules — live in the Payroll area, not here.

* Pay-window analytics and the bank file → **this hub**.
* Payroll-run summaries, statutory schedules (PAYE / NSSF / LST), and remittance reports → **Payroll reports** (see Related).

***

## Permissions

| Action                                                          | Permission          |
| --------------------------------------------------------------- | ------------------- |
| Open the HR Reports hub                                         | `hr:read`           |
| Open Salary Register / Bank Remittance / Income Tax Computation | `hr-employees:read` |
| Open Leave Balance / Leave Ledger                               | `hr:read`           |

The backend report endpoints sit under `/api/hr/reports/`. Note the three pay reports are gated in the app on the finer `hr-employees:read` slug, while the leave report screens use the coarse `hr:read` — so a role with HR read but **not** employee read can reach the hub and the leave reports but will be blocked from opening the three pay reports.

***

## Related

* [Leave reports (balance & ledger)](/hr/user/leave/leave-reports) — the leave-balance and leave-ledger screens reached from the Leave area
* [Payroll reports](/hr/user/payroll/reports) — payroll-run summaries and statutory schedules
* [Payslips](/hr/user/payroll/payslips) — the source records behind the salary, bank and tax reports
* [Statutory remittances (PAYE, NSSF, LST)](/hr/user/payroll/statutory-remittances)
* [Employee loans & advances](/hr/user/payroll/employee-loans) — source for the Advance Summary report
* [HR settings](/hr/user/settings/hr-settings) — per-tenant HR configuration