# Reports, business plans and variance

> How monthly forecast figures become quarterly and annual statements, how report rows are calculated, how business plan drafts are filled, and how plan and actual figures are compared. This page gives the formulas, what each symbol means, when they hold and a worked example.

How monthly forecast figures become quarterly and annual statements, how report rows are calculated, how business
plan drafts are filled, and how plan and actual figures are compared. This page gives the formulas, what each
symbol means, when they hold and a worked example.

**How to read this page.** Each formula is shown on its own line, followed by its symbols, the conditions under
which it holds, what it says in plain words and a short example. Implementation details for developers close the
page.

## Cadence aggregation

Monthly figures are grouped into `monthly`, `quarterly` (fiscal quarters, key `FY-Qn`) or `annual` (fiscal years)
periods using `fiscalYearStartMonth`. How a line is combined depends on what kind of figure it is (its catalogue
`kind` in `calc/lines.py`):

$$\begin{gathered} \text{flow: } X_Q = \sum_{t \in Q} X_t \\[8pt] \text{opening: } X_Q = X_{\text{first}(Q)} \\[8pt] \text{stock: } X_Q = X_{\text{last}(Q)} \\[8pt] \text{ratio: } X_Q = \frac{\sum_{t \in Q} \text{num}_t}{\sum_{t \in Q} \text{den}_t} \end{gathered}$$

| Symbol | Meaning |
| --- | --- |
| $Q$ | A period: a fiscal quarter or year |
| flow | Something that happens during a month, such as revenue or costs |
| opening | A balance at the start of a month, such as opening cash |
| stock | A balance at the end of a month, such as ending cash or customers |
| ratio | A ratio of two other lines, such as gross margin |

**In plain words.** Revenue of a quarter is the revenue of its three months added up; cash at the end of a quarter
is the cash at the end of its last month. A ratio is never averaged: it is recalculated from the quarter's totals.

**Valid when.** Always. Months without a value are skipped in sums. `info` lines take the last month. Ratios are
rounded to 6 decimals and are null when the denominator is 0. Aggregation works on the rounded monthly series stored
in the run.

**Example.** Revenue of 10,000, 12,000 and 14,000 with gross profit of 7,000, 9,000 and 11,000 gives quarterly
revenue of 36,000 and a quarterly gross margin of $27{,}000 / 36{,}000 = 75\,\%$, not the average of the three
monthly margins (74.5 %).

## Statement and KPI templates

Starter templates live in `packages/contracts/templates/starter/*.json` and are installed as system templates (`tenant_id` null) by `ReportService.installStarterTemplates`. A tenant's own template with the same key takes precedence (`ReportService.resolve`).

| templateKey | kind | lang | default cadence | validations |
|---|---|---|---|---|
| `management-pnl` | statement | en | monthly | has_revenue, negative_cash, required_inputs_present |
| `cash-flow-runway` | statement | en | monthly | has_revenue, negative_cash |
| `balance-sheet-simplified` | statement | en | quarterly | balance_check |
| `de-operational-planning` | statement | de | annual | has_revenue, negative_cash |
| `startup-investor-financial-plan` | statement | en | annual (quarterly/annual only) | has_revenue, negative_cash |
| `kpi-controlling-dashboard` | kpi | en | monthly | has_revenue, negative_cash |
| `saas-operating-model` | kpi | en | monthly | has_revenue, negative_cash |
| `investor-business-plan-en` / `-es` | business_plan | en / es | annual only | none |
| `startup-business-plan-universal` | business_plan | en | annual only | profile_fields |

Rendering (`render.render_report`):

- Cadence must be in the template's `cadences`, else error.
- Each row is a header/text row (no values), a `ref` to a canonical line key, or a `formula` over earlier row ids
  or line keys: $\operatorname{sum}(a, b, \dots) = a + b + \dots$, $\operatorname{sub}(a, b, \dots) = a - b - \dots$
  (the first minus the rest), $\operatorname{neg}(a) = -a$ and $\operatorname{ratio}(a, b) = a / b$ (6 decimals,
  null when $b$ is 0 or null). Missing operands count as 0. Referencing a row defined later raises an error; an
  unknown `ref` yields nulls and a warning.
- `sign: -1` negates displayed values; `hideIfZero` drops rows that are all 0/null.
- Validations: `balance_check` warns if any `abs(bs.check) > 0.05`; `negative_cash` if any `cash.ending < 0`; `has_revenue` if no month has revenue > 0; `required_inputs_present` if listed line keys are absent. `profile_fields` is accepted by the schema but not evaluated yet; missing profile facts surface as placeholders instead (below). Forecast warnings are appended.
- Output includes lineage: run id, scenario, model version, engine version, input hash, calculated-at.
- The template's `currency` only changes the displayed currency code; no FX conversion is applied.

The control plane records each JSON render or export in `report_runs` (template version, forecast run, cadence, format).

## Business-plan drafts

`business_plan.render_business_plan` fills section `body` Markdown with a small token language (no code execution):

- `{{ path }}` or `{{ path | filter }}`; filters: `currency`, `currency_k`, `percent`, `months`, `number`, `number1`, `month`, `date`, `text`. Currency is formatted with 0 decimals; `de`/`es` swap separators.
- `{{ table:name }}` for `annual_pnl`, `pricing`, `hiring`, `funding`, `costs` (first fiscal year, ranked), `unit_economics`, `scenario_assumptions`, `key_assumptions`.
- Paths resolve against: `company` (primary legal entity), `profile` (`business_profiles.data`), `scenario`, `run`, `summary` and `unit` (snake_case field names of the run summary), `products`, `plans`, `hires`, `funding` (upcoming non-cancelled included events from the as-of month), `year1..year5`, `lastYear`.
- Missing value or empty table: a visible placeholder `**[PLACEHOLDER: <name> — not provided yet]**` (localised) is written and listed in `placeholders`. Exceptions: a null `summary.cash_out_month*` renders "beyond the N-month horizon" and a null `summary.break_even_month` renders "not within the forecast horizon".
- Every figure from `summary`, `unit`, `funding`, `hires`, `year*`, `lastYear` and every table is listed in `grounding` with source `forecast_run:<runId or input hash prefix>`.

The control plane stores the draft in `business_plan_drafts` with `generated_markdown` (engine output) and `markdown` (user-editable; `edited` = they differ). Only drafts can be edited; approval requires the `approve` permission and writes an `approvals` row.

## Plan-vs-actual variance

`ControllingService.variance` chooses the basis and calls engine `POST /v1/variance` (`compare.variance`).

Basis (`ControllingService.basis`):

| Input | Default |
|---|---|
| Plan run | explicit id, else the plan-baseline run, else the latest run of the primary scenario |
| Forecast run | explicit id, else the latest run of the primary scenario |
| Through month | explicit, else the latest month with an actual record, else the previous calendar month |

Actuals (`RecordService.actuals`):

- `finance_records` with `classification = 'actual'`, not archived, status not `void`/`draft`, in base currency (`amount_base`).
- Line mapping (`actualLine`): invoice to `revenue`; expense category `payroll` to `opex.headcount`; COGS categories to `cogs.<category>`; everything else to `opex.<category>`.
- Invoices with a multi-month service period are spread evenly over its months (2 dp, remainder in the last month); everything else lands in the month of `record_date`.
- Payments (not archived) on the same set of records give `cash.collections` (incoming) and `cash.outflows` (outgoing), converted with the record's `fx_rate_to_base`.

Calculation (`compare.variance`):

- Only plan periods up to the through month are used. `cogs` and `opex` actuals are the sum of their detail lines; `gross_profit = revenue - cogs`, `operating_result = gross_profit - opex`.
- A month without any actual record has no actuals (null, not zero), and a note lists those months. A month with records but none for a cost line counts that line as 0.
- Default rows: `revenue`, `cogs`, `gross_profit`, `opex`, `operating_result`, any detail cost lines present in actuals, and the cash lines if present.
- There are no materiality thresholds; every non-zero variance is flagged favorable or unfavorable.

### Variance per cell

$$\begin{gathered} \Delta = A - B \\[8pt] \Delta\% = \frac{\Delta}{\lvert B \rvert} \\[8pt] \text{favorable} = \begin{cases} \Delta > 0 & \text{revenue and profit lines} \\ \Delta < 0 & \text{cost lines} \end{cases} \end{gathered}$$

| Symbol | Meaning | Unit |
| --- | --- | --- |
| $A$ | Actual amount for the line and month | currency |
| $B$ | The base it is compared with: the plan (or the forecast) | currency |
| $\Delta$ | Variance: how far the actual is from the base (`variance`) | currency |
| $\Delta\%$ | Variance as a share of the base (`variance_pct`) | share |

**In plain words.** The variance is actual minus plan. Above plan is good for revenue and profit and bad for costs,
so the favorable flag (`favorableVsPlan`) looks at the kind of line. Dividing by the absolute value of the plan
keeps the sign of the percentage the same as the sign of the variance, even when the plan is a loss.

**Valid when.** Both values exist. The percentage is null when the plan is 0 or missing (there is no meaningful
percentage of nothing); the flag is null when the variance is 0 or missing. Cost lines are `cogs*`, `opex*` and
`cash.outflows`. Amounts are rounded to 2 decimals, percentages to 6. The same is calculated against the forecast.

**Example.** Planned revenue €50,000, actual €45,000: $\Delta = -5{,}000$ and $\Delta\% = -10\,\%$, unfavorable.
Planned operating result −€20,000, actual −€15,000: $\Delta = +5{,}000$ and $\Delta\% = 5{,}000 / 20{,}000 = +25\,\%$,
favorable. Planned marketing €8,000, actual €9,000: $\Delta = +1{,}000$, unfavorable because it is a cost.

Drill-down (`ControllingService.drilldown`) returns the matching records, plan values from the plan run, related input entities and overrides from the run's input snapshot, and the run's lineage. Records cannot be created or changed in a locked fiscal period (`RecordService.assertPeriodOpen`).

## For developers

Sources: `apps/finance-engine/src/finance_engine/calc/aggregate.py`, `reports/render.py`, `reports/business_plan.py`, `models/templates.py`, `calc/compare.py` (`variance`), and in the control plane `reports/Reports.kt`, `controlling/Controlling.kt`, `records/Records.kt` (`actuals`, `actualLine`). Keep this page in sync with any change there.