Flux Report Workflow

1. Executive Summary

Purpose

The Flux Report is a monthly-close analytical tool for Finance controllers and revenue analysts. It identifies period-over-period revenue variances by comparing the current fiscal period's posted transactions against the prior month (Month-over-Month, MoM) and the same period one fiscal year earlier (Year-to-Date Year-over-Year, YTD YoY). The report flags material changes by department, client, and deal so teams can explain significant movements before the close package is finalized.

A snapshot system lets teams capture the report at each stage of the close cycle (pre-review, morning-of, final) and compare snapshots side-by-side to track how results evolved across close iterations.

Scope

Covered:

• Department summary view — MoM and YTD YoY variance by department with threshold flags
• Client drill-down — client-level MoM variance nested under each department
• Deal drill-down — top contributing deals nested under each client
• Historical 24-month grid — time-series revenue per period enabling trend and seasonality analysis
• Variance comments — operator-authored explanations for material variances, with carry-over for YTD comments
• Snapshots — point-in-time captures of the full report (ARM Preview, ARM Morning, ARM Final, Custom)
• Snapshot comparison — side-by-side analysis of two or more snapshots from the same fiscal period
• GL posting status panel — count of unposted, posted, failed, and excluded transactions for the period

Not covered (documented separately):

• AR Aging collections reporting — see AR Aging Workflow
• GL transaction posting — see Accounting Jobs
• Accounting data model for fiscal_period, flux_report_snapshot — see Accounting Data Model

Key Objectives

• Surface material MoM and YTD YoY revenue variances before month-end close, organized by department and client.
• Enable Finance teams to document the business driver behind each material change.
• Preserve an auditable record of close-stage results via named snapshots.
• Support iterative close review by comparing snapshots across ARM stages.

---

2. Process Overview

flowchart TD
    A[Finance team opens Flux Report] --> B[Select fiscal period and filters\nEntity, Department, Client]
    B --> C[Run report — live query against transaction table]
    C --> D[Department Summary view loads]
    D --> E[Review MoM and YTD YoY variances\nThreshold flags highlight material changes]
    E --> F{Department flagged?}
    F -->|Yes| G[Expand department → Client drill-down]
    G --> H[Expand client → Deal drill-down\nTop deals contributing to variance]
    H --> I[Add variance comment\nexplaining business driver]
    F -->|No| J[Move to next department]
    D --> K[Switch to 24-Month Historical Grid\nfor trend and seasonality review]
    D --> L[Check GL Posting Status panel\nunposted / failed transaction counts]
    L --> M{All transactions posted?}
    M -->|No| N[Coordinate with Accounting team\nto resolve unposted / failed transactions]
    M -->|Yes| O[Take Snapshot]
    O --> P[Name snapshot: ARM_PREVIEW / MORNING / FINAL / CUSTOM]
    P --> Q[Snapshot saved — full report state captured as JSONB]
    Q --> R{Compare needed?}
    R -->|Yes| S[Open Snapshot Comparison tab\nSelect 2+ snapshots to compare]
    S --> T[Side-by-side analysis\nof variance changes across close iterations]
    R -->|No| U[Close cycle complete for this period]

Walkthrough

1. Select period and filters — The Finance team opens /flux-report, selects the fiscal period (month + year), and optionally filters by entity, department, or client to scope the analysis.

2. Review department summary — The default view shows one row per department with: current period revenue, prior month revenue, MoM dollar and percentage change, YTD revenue, YTD YoY change, and threshold flags. Rows where the absolute variance exceeds the material threshold (default $500k or 10%) are flagged for mandatory explanation.

3. Drill into clients and deals — Clicking a department row expands it to show the department's clients, each with their own MoM variance. Clicking a client row expands it to show the top contributing deals, letting the analyst trace the variance to a specific booking.

4. Add variance comments — For any flagged or notable line, the analyst types a variance comment explaining the business driver (e.g., "Large touring deal closed in current period," "Client pricing renegotiation in prior period"). YTD variance comments carry forward automatically to the next period's report so context is preserved across months without re-entry.

5. Review the 24-month historical grid — Switching to the historical tab shows revenue per period across 24 months, enabling the team to identify seasonal patterns and confirm whether the current period's variance is anomalous or expected.

6. Check GL posting status — A status panel at the top of the report shows the count of unposted, posted, failed, and excluded transactions for the selected period. If there are unposted or failed transactions, the report may be incomplete and the accounting team must resolve them before the final snapshot is taken.

7. Take a snapshot — When the close-stage review is complete, the analyst clicks "Take Snapshot," assigns a type (ARM_PREVIEW, ARM_MORNING, ARM_FINAL, or CUSTOM), and optionally customizes the label. The system captures the full report result — all three data tiers, threshold settings, period labels, and variance comments — as immutable JSONB in flux_report_snapshot.

8. Compare snapshots — In the comparison tab, the analyst selects two or more snapshots from the same fiscal period and loads them side-by-side to see how department and client results evolved across the close cycle. This supports quality control and final sign-off.

---

3. Business Rules

3.1 Data Source Is Posted Transactions

Business rule: The Flux Report reads from the transaction table (the CP subledger) filtered to rows with gl_status_cd in a posted or pending-post state for the selected fiscal period. Unposted transactions are excluded from variance calculations. If significant unposted or failed transactions exist for the period, the report will show incomplete results.

Foundation reference: Accounting Data Model — transaction

Workflow context: The GL Posting Status panel at the top of the report shows transaction counts by status so users can assess completeness before taking a final snapshot.

---

3.2 Material Variance Threshold Is Configurable

Business rule: Variances are flagged as material when the absolute MoM dollar change exceeds a configured dollar threshold (default $500k) OR the percentage change exceeds a configured percentage threshold (default 10%). Both thresholds are user-adjustable per session. Only rows meeting either threshold are required to have variance comments before the close is finalized.

---

3.3 YTD Variance Comments Carry Forward

Business rule: Variance comments attached to YTD (Year-to-Date Year-over-Year) variance lines carry forward automatically to the next fiscal period's report. They are marked "carried over from prior period" so readers can distinguish current-period annotations from inherited context. This preserves analytical continuity for ongoing trends without requiring re-entry each month.

Foundation reference: Accounting Data Model — flux_variance_comment

---

3.4 Snapshots Are Immutable

Business rule: Once a snapshot is taken, its snapshot_data_json is never modified. The snapshot represents the report's exact state at the moment of capture. If the analyst takes a new snapshot of the same type for the same period, the prior snapshot's status_cd is set to SUPERSEDED and the new one becomes ACTIVE. Superseded snapshots remain available for comparison.

Foundation reference: Accounting Data Model — flux_report_snapshot

---

3.5 Snapshots Are Self-Contained

Business rule: Snapshots store the complete report result — all three data tiers (departments, clients, deals), period labels, threshold settings, and variance comments — as JSONB. Comparisons between snapshots do not re-run queries; they read the stored JSONB. This ensures that snapshot comparisons are stable even if underlying transaction data changes after the snapshot was taken.

---

4. Key User Actions

4.1 Run Report

Steps:

1. Select fiscal period, entity, and optional filters.
2. Click "Run." Live query executes against transaction table.
3. Department summary loads. Review threshold flags.

---

4.2 Drill Down to Client and Deal

Steps:

1. Click a department row — expands to show client list.
2. Click a client row — expands to show top contributing deals.
3. Review the deal contributing most to the client's MoM variance.

---

4.3 Add Variance Comment

Steps:

1. Click the comment icon on any department, client, or deal row.
2. Type the variance explanation.
3. Save. Comment stored in flux_variance_comment linked to the current snapshot (or saved to a draft state if no snapshot has been taken yet).

---

4.4 Take Snapshot

Preconditions:

• Report has been run for the target period.
• GL posting status shows an acceptable level of posted transactions.

Steps:

1. Click "Take Snapshot."
2. Select type: ARM_PREVIEW, ARM_MORNING, ARM_FINAL, or CUSTOM.
3. Optionally customize the label.
4. Confirm. Snapshot saved to flux_report_snapshot.

Postconditions:

• flux_report_snapshot row created with full report JSON.
• Prior snapshot of the same type for the same period set to SUPERSEDED.
• Snapshot appears in the Snapshot Panel list.

---

4.5 Compare Snapshots

Steps:

1. Open the Snapshot Comparison tab.
2. Select two or more snapshots from the same fiscal period using the snapshot selector.
3. Load comparison — selected snapshots' JSONB data loads side-by-side.
4. Review how department and client results changed across close iterations.

---

5. Permissions & Role-Based Access

Action	CASH_PROCESSOR	IT	Finance (Accounting)
Run report	—	Yes	Yes
Add / edit variance comments	—	Yes	Yes
Take snapshot	—	Yes	Yes
Compare snapshots	—	Yes	Yes
View report (read-only)	Yes	Yes	Yes

---

6. Integration Points

6.1 Upstream

Source	Data Provided
Accounting Jobs	Posted transaction rows for the selected fiscal period — the revenue figures driving all MoM/YoY calculations
Fiscal Period table	Period boundaries, labels, and open/closed status for the selected month
department_account_mapping	Maps departments to GL accounts for display grouping

6.2 Downstream

Consumer	Data Produced
Finance close package	Snapshots serve as the official record of revenue results at each close stage
Audit / compliance	flux_variance_comment records document the business justification for material variances

---

7. Functional Screen Requirements

7.1 Department Summary View

Route: /flux-report (default tab)

Column	Source	Description
Department	department.department_name	Revenue department
Current Period	Computed from transaction	Total revenue for selected fiscal period
Prior Month	Computed from transaction (period - 1)	Revenue in the immediately preceding period
MoM Change ($)	Current − Prior Month	Absolute dollar variance
MoM Change (%)	(Current − Prior) / Prior	Percentage variance
YTD Revenue	Computed (rolling 12 months to current period)	Year-to-date revenue
YTD YoY Change	YTD vs. prior-year same period	Year-over-year variance
Flag	Threshold check	Badge shown when MoM or YTD exceeds material threshold
Comment	flux_variance_comment.comment_text	Analyst annotation; pencil icon to edit

Client sub-rows (expanded): Client name, current period, prior month, MoM $ and %, new/dropped client flag.

Deal sub-rows (expanded): Deal name/reference, current period, prior month, MoM $.

---

7.2 24-Month Historical Grid

Route: /flux-report (Historical tab)

Displays one row per department (or client, if drilled in) with 24 columns — one per calendar month — showing posted revenue for that period. Enables trend and seasonality review.

---

7.3 GL Posting Status Panel

Shown at top of the report. Displays transaction counts for the selected period by gl_status_cd:

• Posted (P)
• Unposted (U)
• Failed (F)
• Excluded (X)

Warns the analyst if unposted or failed transaction counts are high before they take a final snapshot.

---

7.4 Snapshot Panel

Shows all flux_report_snapshot rows for the selected period, sorted by snapshot_dt descending.

Column	Source
Label	flux_report_snapshot.snapshot_label
Type	flux_report_snapshot.snapshot_type_cd badge
Captured	flux_report_snapshot.snapshot_dt
By	flux_report_snapshot.created_by
Status	flux_report_snapshot.status_cd (ACTIVE / SUPERSEDED)

---

8. Cross-References

Document	Relationship
Accounting Data Model	flux_report_snapshot, flux_variance_comment, fiscal_period, transaction, department_account_mapping — the data layer this workflow reads from and writes to
AR Aging Workflow	Related monthly-close report; AR Aging focuses on collections and open receivables while Flux Report focuses on posted revenue variance
Revenue Verification Workflow	Revenue verification confirms revenue item statuses before GL posting; Flux Report analyzes the posted results after close