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

# Financial Analytics & Dashboards — Admin Guide

> Module: FA (Finance & Accounting) Feature: FA-16 Audience: Finance Admins (fa.analytics.configure permission) Last Updated: 2026-02-13

**Module:** FA (Finance & Accounting)\
**Feature:** FA-16\
**Audience:** Finance Admins (`fa.analytics.configure` permission)\
**Last Updated:** 2026-02-13

***

## Overview

This guide covers how to configure and manage the Financial Analytics module, including KPI definitions, dashboard widgets, and variance thresholds.

***

## Configuring KPI Definitions

KPI definitions are stored in the `fa_kpi_definitions` table and control what metrics appear on the KPIs page.

### Creating a KPI

Each KPI requires:

| Field                 | Description                                                            | Example                  |
| --------------------- | ---------------------------------------------------------------------- | ------------------------ |
| `kpi_code`            | Unique code within your org                                            | `DSO`                    |
| `kpi_name`            | Display name                                                           | `Days Sales Outstanding` |
| `category`            | One of: liquidity, profitability, efficiency, leverage, growth, custom | `efficiency`             |
| `formula`             | Database function name to calculate the value                          | `fa_calculate_dso`       |
| `unit`                | Display unit (days, ratio, percentage, currency)                       | `days`                   |
| `target_value`        | Organization's goal value                                              | `30`                     |
| `threshold_warning`   | Value that triggers yellow status                                      | `45`                     |
| `threshold_critical`  | Value that triggers red status                                         | `60`                     |
| `threshold_direction` | How to interpret thresholds                                            | `lower_is_better`        |

### Threshold Direction

| Direction          | Warning Trigger                         | Critical Trigger             |
| ------------------ | --------------------------------------- | ---------------------------- |
| `higher_is_better` | Value drops below warning               | Value drops below critical   |
| `lower_is_better`  | Value rises above warning               | Value rises above critical   |
| `target_is_best`   | Value deviates from target by warning % | Value deviates by critical % |

### Built-in Calculation Functions

| Function                     | Parameters                           | Returns                  |
| ---------------------------- | ------------------------------------ | ------------------------ |
| `fa_calculate_dso`           | `(org_id, period_start, period_end)` | Days Sales Outstanding   |
| `fa_calculate_dpo`           | `(org_id, period_start, period_end)` | Days Payable Outstanding |
| `fa_calculate_current_ratio` | `(org_id, period_id)`                | Current Ratio            |

***

## Dashboard Widget Management

Widgets are stored in `fa_dashboard_widgets` and control the dashboard layout.

### Widget Types

| Type              | Description                             |
| ----------------- | --------------------------------------- |
| `kpi_card`        | Single KPI value with trend             |
| `trend_chart`     | Revenue/expense trend line chart        |
| `variance_table`  | Budget vs. actual table                 |
| `cash_position`   | Cash and bank balances                  |
| `revenue_summary` | Revenue breakdown                       |
| `expense_summary` | Expense breakdown                       |
| `custom`          | Custom configuration via `config` JSONB |

### Layout

Widgets use a 12-column grid system:

* `position_x` / `position_y`: Grid position (0-based)
* `width` / `height`: Size in grid units (1-12)

***

## Variance Threshold Configuration

The variance significance threshold is set in **FA Module Settings**:

* **Setting:** `variance_threshold_percent`
* **Default:** 10%
* **Range:** 1–100%
* **Effect:** Variances exceeding this percentage are flagged as "significant" on the Variance Analysis page

To change: Navigate to `/fa/settings` and update the "Variance Threshold %" field.

***

## Permission Setup

Assign these permissions to roles via the Permissions admin page:

| Permission                   | Purpose                                 | Recommended Roles                       |
| ---------------------------- | --------------------------------------- | --------------------------------------- |
| `fa.dashboard.view`          | View financial dashboard                | finance\_admin, finance\_staff, manager |
| `fa.analytics.kpis.view`     | View KPIs                               | finance\_admin, finance\_staff          |
| `fa.analytics.trends.view`   | View trend analysis                     | finance\_admin, finance\_staff          |
| `fa.analytics.variance.view` | View variance analysis                  | finance\_admin, finance\_staff          |
| `fa.analytics.configure`     | Create/edit KPI definitions and widgets | finance\_admin                          |

***

## KPI History (Audit)

The `fa_kpi_history` table is **append-only** — records cannot be updated or deleted. This ensures a complete audit trail of all KPI calculations over time. Each entry records:

* The calculated value at that point in time
* The previous value for trend comparison
* The status (normal/warning/critical) at calculation time

***

## Related Documentation

* [FA-16 User Guide](./financial-analytics-user-guide.md) — End-user documentation
* [FA Module Settings](../../specs/fa/specs/FA-01-chart-of-accounts.md) — General FA configuration