Chunks — 32. Reports

Booking Trend

# **Functional Requirements Document (FRD)**

## **Module: Reports – Booking Trend**

**Document Version:** 1.3  
**Created Date:** January 07, 2026  
**Last Updated:** July 10, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Booking Trend

### **Purpose**

The Booking Trend report enables agency owners to track booking and revenue progress across years as of a specific date. It provides an "as-of" year-over-year comparison of business performance, helping agencies understand growth patterns, pipeline health, sales efficiency, and booking velocity.

### **Business Goals**

*   Compare booking volumes and revenue across multiple years to identify growth or decline trends.
*   Provide insight into lead-to-booking conversion and average booking time to measure sales effectiveness.
*   Analyze performance by lead source to identify the most valuable marketing channels.
*   Visualize booking pace against the previous year to signal urgency or success.

### **Report Sections**

The report is divided into four sections, driven by two independent filter bars:

*   **YoY Snapshot** – Year-over-year comparison of bookings and revenue as of a selected date (driven by the top filter bar).
*   **Bookings & Leads Insights** – Total Leads, New Bookings, Conversion Rate, and Average Booking Time (driven by the Insights filter bar).
*   **Performance Breakdown** – Monthly leads versus bookings with source-level analysis.
*   **Pacing Chart** – Month-over-month booking comparison between the current year and the previous year.

### **Revenue & Tax Treatment**

*   All revenue figures in this report are shown **excluding sales tax** (e.g., $100 on a $110 gross invoice with $10 tax).
*   Displayed revenue is **not** reduced by the platform fee; the platform fee is accounted for in cost/profit reports, not here.
*   When an agency uses Stripe automatic tax, the tax portion is handled by Stripe and is not stored in the system; revenue figures therefore already reflect the tax-excluded amount.

### **Report Behavior**

*   **Read-only:** This report contains no action buttons. All booking and lead actions are handled in the Projects and Leads modules.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All booking and lead actions are handled in the Projects and Leads modules.

## **3\. User Flow**

3.1 The user navigates to the Reports module from the left sidebar by clicking "Reports."

*   The Reports menu item is located in the left navigation panel.

3.2 The system loads the Reports landing page displaying all report cards in a grid layout.

3.3 The user locates the "Booking Trend" report card and clicks "View >".

3.4 The system navigates to the Booking Trend report page and loads the report with default filters applied.

*   **YoY Snapshot** loads with the As-of Date defaulted to today.
*   **Bookings & Leads Insights** loads with the date range defaulted to "This Month" (current calendar month).

3.5 The system displays the report header with a back arrow, title "Booking Trend," the subtitle, and an "Export Report" button.

3.6 The system displays the **top filter bar** above the YoY Snapshot: All Events, All Services, All Service Areas, All Brands, and an As-of Date picker.

3.7 The system displays the **YoY Snapshot** table comparing the current year with prior and next years as of the selected date.

*   Columns: As of Date, Current Year (Projects / Revenue), Next Year (Projects / Revenue), YoY Change (projects % / revenue %).
*   A "Show More" control expands additional historical rows.

3.8 The user changes the **As-of Date** in the top bar.

*   The system recalculates the YoY Snapshot only; the Insights section and its metrics are unaffected.

3.9 The system displays the **Bookings & Leads Insights** section with its own filter bar: All Events, All Services, All Service Areas, All Brands, All Lead Sources, and a date range picker.

3.10 The system displays four metric cards: Total Leads, New Bookings, Conversion Rate, and Average Booking Time.

3.11 The user changes filters or the date range in the Insights bar.

*   The system recalculates the four Insights cards based on the Insights bar (including its date range).
*   The Performance Breakdown and Pacing Chart update for non-date filters only; their period remains fixed to the current year.

3.12 The system displays the **Performance Breakdown** chart (monthly Leads vs Bookings) and a source-level table.

*   Table columns: Source, Total Leads, Total Bookings, Conversion Rate, Average Booking Time, Total Value.

3.13 The system displays the **Pacing Chart** comparing bookings per month for the current year versus the previous year, with a "% vs last year" indicator.

3.14 The user clicks "Export Report."

*   The system generates an **XLSX** export of the report data (metrics and tables; charts excluded) and downloads it as "Booking\_Trend\_\[Date\].xlsx".

3.15 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** When an agency has no leads or bookings, the YoY Snapshot displays placeholder content, the four Insights cards display "0" / "0%" / "0 days", and the Performance Breakdown and Pacing Chart render with zero values or an empty-state message.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filter Structure (Two Independent Filter Bars)**

This report has **two separate filter bars**, each scoped to its own section:

**Top Filter Bar (YoY Snapshot):**

*   All Events, All Services, All Service Areas, All Brands, and an **As-of Date** picker.
*   Controls the YoY Snapshot only.

**Insights Filter Bar (Bookings & Leads Insights):**

*   All Events, All Services, All Service Areas, All Brands, All Lead Sources, and a **Date Range** picker.
*   Controls the four Insights cards (with its date range) and the non-date dimensions of the Performance Breakdown and Pacing Chart.

### **4.3 Filter Impact Matrix**

**Section / Element**

**Impacted by Filters**

**Impacted by Date**

**Fixed Period**

YoY Snapshot

Top bar (Events, Services, Service Areas, Brands)

Yes — As-of Date

—

Total Leads

Insights bar

Yes — Insights date range

—

New Bookings

Insights bar

Yes — Insights date range

—

Conversion Rate

Insights bar

Yes — Insights date range

—

Average Booking Time

Insights bar

Yes — Insights date range

—

Performance Breakdown

Insights bar (non-date)

**No**

Current year

Pacing Chart

Insights bar (non-date)

**No**

Current year

### **4.4 YoY Snapshot Logic**

This is an **"as-of" snapshot compared year over year**: versus the same calendar date last year, is the agency ahead or behind? It is measured **two different ways that must be read separately, never combined into a single number**.

**Bookings (as booked by this date):**

*   The number of projects already booked for each event-year, counted **as of** the selected date — a pace check on how full that year's calendar is by this point in time.
*   **Attribution by primary event date:** counting follows each project's **primary event**. The whole project counts in that event's year, even when its other events fall in different years.
    *   _Example:_ a project with an engagement shoot in 2025 and the wedding in 2026 counts entirely toward **2026**, because the wedding is the primary event.
*   **Multiple events:** because a project can contain multiple events, counts can be higher when the report is filtered by a service.
*   **Specific-event filter:** when the user filters to a **specific event**, attribution shifts from the primary event to the **selected event's date**, and only projects that contain the selected event are shown. _(Example: filtering the 2025 engagement + 2026 wedding project to "engagement shoot" counts that project toward_ **_2025_**_, the engagement's date, instead of 2026.)_
*   **Rationale for event-date attribution:** bookings are attributed by the project's primary event date (not payment date) so the year-over-year comparison remains accurate. If payment date were used, all bookings would fall into the year the payment was received, distorting the comparison across current and future years.

**Revenue (cash collected Jan 1 → as-of date):**

*   The cash actually collected between January 1 and the as-of date of that year, **regardless of which event-years those payments were for**.
*   This is **NOT** the value of the bookings shown alongside it. It captures price increases and payment-schedule changes that booking counts alone cannot reveal.
*   Revenue is shown **excluding sales tax**.

**Display:** The YoY Snapshot table shows, per year, the Bookings count and the Revenue figure, plus the YoY change percentage for each, computed against the same measure in the prior year.

**TBD (To-Be-Determined) Event Dates — YoY Snapshot only:**

*   Projects that are booked but whose **primary event date is TBD** cannot be attributed to any event-year, so they cannot be placed in any period and are **excluded from the YoY Snapshot booking counts** (and from every date-scoped element of this report).
*   They are surfaced in a separate **TBD info area** (never inside the snapshot totals): an info banner showing the **count of TBD projects** and their **combined estimated revenue** (booking value, excluding tax).
    *   _Example copy:_ "N booked project(s) have a to-be-decided (TBD) event date and can't be placed in this period, so they're not counted in the totals above. Their combined estimated revenue is $X. These figures will roll in automatically once each event date is set."
*   The TBD area **ignores the date filter** (otherwise TBD items would disappear whenever a period is selected) but **respects the non-date filters** (Brand, Event, Service, Service Area). If no filter matches, or there are no TBD projects, the TBD area is not shown.
*   "TBD" means **to be determined** (the event date is not yet set), not "not decided." Only the YoY Snapshot is affected; New Bookings, Performance Breakdown, and Pacing use the first-payment date (a real date) and are unaffected.

### **4.5 Bookings & Leads Insights Logic**

*   **Total Leads:** Count of new leads created within the Insights date range (and matching the Insights filters).
*   **New Bookings:** Count of new bookings confirmed within the Insights date range, counted on the **booked date**, which is the date the **first payment is made**.
*   **Conversion Rate:** New Bookings ÷ Total Leads for the selected range, expressed as a percentage. If Total Leads is 0, display "0%".
*   **Average Booking Time:** Average number of days between lead creation and booking confirmation for bookings in the selected range.

**Note:** The **New Bookings card** uses the first-payment (booked) date, whereas the **YoY Snapshot Bookings** column uses the project's primary event date. These are intentionally different measures serving different purposes (pace of confirmations vs. calendar fill by event-year).

### **4.6 Performance Breakdown Logic**

*   **Chart:** Monthly Leads vs Bookings for the **current year** (not affected by the date filter).
*   **Booking counts** in both the chart and the source table are counted on the **first-payment date** (the booked date).
*   **Source Table:** For each lead source, displays Total Leads, Total Bookings, Conversion Rate, Average Booking Time, and Total Value (revenue, excluding tax).
*   Responds to the Insights bar's non-date filters (Events, Services, Service Areas, Brands, Lead Sources).

### **4.7 Pacing Chart Logic**

*   Line chart comparing bookings per month for the **current year** versus the **previous year**.
*   **Bookings are counted on the first-payment date** (the booked date).
*   Displays a "% vs last year" indicator summarizing pace.
*   Fixed to the current year; not affected by the date filter. Responds to the Insights bar's non-date filters.

### **4.8 Export Logic**

*   "Export Report" generates an **XLSX** file containing the report's metrics and table data.
*   Charts and visual elements are excluded (data only).
*   Filename format: "Booking\_Trend\_\[Date\].xlsx".
*   The export reflects the currently applied filters.

### **4.9 Date Restrictions**

*   The As-of Date and Insights date range cannot be set to a future date, as bookings cannot be booked in the future.
*   The earliest selectable date is the agency creation date.

### **4.10 Impact**

*   Changing the **As-of Date** recalculates only the YoY Snapshot.
*   Changing the **Insights date range** recalculates only the four Insights cards.
*   Changing **non-date filters** in the Insights bar updates the four cards, the Performance Breakdown, and the Pacing Chart; the latter two remain scoped to the current year.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Top Filter Bar (YoY Snapshot)**

**Field**

**Type**

**Default**

**Options / Notes**

Events

Dropdown (single-select)

All Events

All Events + configured event types

Services

Dropdown (single-select)

All Services

All Services + configured services

Service Areas

Dropdown (single-select)

All Service Areas

All Service Areas + configured areas

Brands

Dropdown (single-select)

All Brands

All Brands + configured brands

As-of Date

Date picker

Today

Past dates only; earliest = agency creation date

### **5.2 Insights Filter Bar (Bookings & Leads Insights)**

**Field**

**Type**

**Default**

**Options / Notes**

Events

Dropdown (single-select)

All Events

All Events + configured event types

Services

Dropdown (single-select)

All Services

All Services + configured services

Service Areas

Dropdown (single-select)

All Service Areas

All Service Areas + configured areas

Brands

Dropdown (single-select)

All Brands

All Brands + configured brands

Lead Sources

Dropdown (single-select)

All Lead Sources

All Lead Sources + configured sources

Date Range

Date range picker

This Month

Preset options + Custom Range; future dates disabled

### **5.3 Metric Fields**

**Metric**

**Data Type**

**Description**

**Display Format**

Total Leads

Integer

New leads in the Insights range

Whole number (e.g., "1,284")

New Bookings

Integer

New bookings by first-payment date in range

Whole number (e.g., "347")

Conversion Rate

Percentage

New Bookings ÷ Total Leads

"X%" (e.g., "42.8%")

Average Booking Time

Duration

Avg days from lead to booking

"X days" (e.g., "18.5 days")

YoY Bookings

Integer

Projects by primary event-year, as of date

Whole number

YoY Revenue

Currency

Cash collected Jan 1 → as-of date, excl. tax

"$X" (e.g., "$220k")

YoY Change

Percentage

Change vs prior year (per measure)

"+X%" / "-X%"

Total Value (source)

Currency

Revenue by source, excl. tax

"$X.XX"

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates earlier than the agency creation date.
*   Percentage calculations guard against division by zero (display "0%").
*   All revenue fields exclude sales tax.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Project spanning multiple event-years:** The entire project counts toward the primary event's year (e.g., 2025 engagement + 2026 wedding → counts for 2026).
*   **Project with multiple events under a service filter:** Counts may increase when filtering by service because a project can contain multiple events.
*   **Revenue without matching bookings:** YoY Revenue reflects cash collected in the period regardless of the event-year, so it may not equal the value of the bookings displayed alongside it. This is expected.
*   **Agency younger than one year:** YoY comparisons and the Pacing Chart display available data only; prior-year values may be blank or zero.
*   **Auto Stripe tax agencies:** Tax is handled by Stripe and not stored; revenue already excludes tax.
*   **New Bookings vs YoY Bookings discrepancy:** The two measures can differ for the same period because one uses first-payment date and the other uses primary event date. This is intended.
*   **Specific-event filter overrides primary event:** Filtering to a specific event attributes a project by that event's date and shows only projects containing the selected event, which can move a project into a different year than its primary-event year.
*   **TBD event date (YoY Snapshot):** A booked project with a TBD primary event date is excluded from the snapshot counts and shown only in the separate TBD info area; it does not appear in any date-scoped card, chart, or row. The TBD area ignores the date filter but respects Brand/Event/Service/Service Area filters, and is hidden when nothing matches.
*   **Zero leads with bookings:** Conversion Rate displays "0%" to avoid division by zero.
*   **As-of Date set to Jan 1:** YoY Revenue window is effectively a single day (Jan 1) and may show minimal or zero cash collected.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access the report; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, and Export Report button.

### **8.2 Filters**

*   AC-004: The report presents two independent filter bars (top bar for YoY Snapshot; Insights bar for the four cards).
*   AC-005: As-of Date defaults to today; Insights date range defaults to This Month.
*   AC-006: Future dates and dates before agency creation are not selectable.
*   AC-007: Changing the As-of Date updates only the YoY Snapshot.
*   AC-008: Changing the Insights date range updates only the four Insights cards.

### **8.3 Filter Impact**

*   AC-009: YoY Snapshot responds to the top bar and As-of Date.
*   AC-010: Total Leads, New Bookings, Conversion Rate, and Average Booking Time respond to the Insights bar including its date range.
*   AC-011: Performance Breakdown and Pacing Chart respond to Insights non-date filters but remain fixed to the current year (not affected by date).

### **8.4 YoY Snapshot**

*   AC-012: Bookings are attributed by the project's primary event date.
*   AC-013: Filtering to a specific event attributes projects by that event's date and shows only projects containing the selected event.
*   AC-014: Revenue reflects cash collected between Jan 1 and the as-of date, excluding tax.
*   AC-015: Bookings and Revenue are displayed as separate measures, each with its own YoY change.
*   AC-016: Projects with a TBD primary event date are excluded from the snapshot counts and shown only in the separate TBD info area (banner with count + combined estimated revenue), which ignores the date filter but respects non-date filters and is hidden when nothing matches.

### **8.5 Insights & Charts**

*   AC-017: New Bookings are counted on the first-payment (booked) date.
*   AC-018: Performance Breakdown booking counts are counted on the first-payment date.
*   AC-019: Pacing Chart booking counts are counted on the first-payment date.
*   AC-020: Conversion Rate displays "0%" when Total Leads is 0.
*   AC-021: Performance Breakdown table shows Source, Total Leads, Total Bookings, Conversion Rate, Average Booking Time, and Total Value.
*   AC-022: Pacing Chart compares current-year vs previous-year bookings with a "% vs last year" indicator.

### **8.6 Revenue, Export & Read-Only**

*   AC-023: All revenue figures exclude sales tax and are not reduced by platform fees.
*   AC-024: Export generates an XLSX file (data only, charts excluded) named "Booking\_Trend\_\[Date\].xlsx".
*   AC-025: No action buttons appear anywhere in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Projects Module

Source of booking and event data

Bookings cannot be calculated

Internal Module

Leads Module

Source of lead data and sources

Leads and conversion metrics unavailable

Internal Module

Payments Module

Source of cash-collected data

YoY Revenue and booked-date unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

Configuration

Agency Settings

Agency creation date

Date restrictions may not work

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Booking Trend Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Booking Trend (Figma design reference)
*   Confirmed revenue, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Tab 12

### **Formulas Reference**

**Conversion Rate Formula:**

Conversion Rate = (New Bookings ÷ Total Leads) × 100

**Average Booking Time Formula:**

For each confirmed booking in date range:

Days to Book = Booking Confirmation Date − Lead Creation Date

Average Booking Time = Sum of all (Days to Book) ÷ Total Confirmed Bookings

**YoY Change Formula:**

YoY Change (Projects) = ((Current Year Projects − Previous Year Projects) ÷ Previous Year Projects) × 100

YoY Change (Revenue) = ((Current Year Revenue − Previous Year Revenue) ÷ Previous Year Revenue) × 100

**Total Value by Source Formula:**

Total Value = Sum of all booking revenue values where Lead Source = \[Selected Source\]

Profit and Loss

# **Functional Requirements Document (FRD)**

## **Module: Reports – Profit & Loss**

**Document Version:** 1.2  
**Created Date:** January 07, 2026  
**Last Updated:** July 06, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Profit & Loss

### **Purpose**

The Profit & Loss report gives agency owners a clear view of total income, cost of goods sold, operating expenses, and net profit over a selected period, with a year-over-year comparison for context.

### **Business Goals**

*   Show income, costs, and net profit for any selected period.
*   Separate direct costs (COGS) from operating expenses (OPEX) for accurate margin analysis.
*   Provide period-over-period comparison to reveal profitability trends.

### **Report Sections**

*   **Profit and Loss Analytics** – Three metric cards (Profit, Income, Expenses) with year-over-year comparison.
*   **Trend Chart** – Line chart of income, expenses, and profit over time.
*   **Summary** – Total Income, Cost of Goods Sold, Gross Profit, Total Expenses, and Net Profit/Loss with expandable line items.

### **Revenue, Cost & Tax Treatment**

*   **Income** is shown **excluding sales tax** (e.g., $100 on a $110 gross invoice with $10 tax). Income is **not** reduced by the platform fee; the platform fee is captured as a cost within COGS.
*   **Cost of Goods Sold (COGS)** = Platform fee (Pixally + Stripe) + Contractor payment + Editor payment. Editor payments (from the Post-Production module, when the editor is marked as paid) are included **within** COGS and are not shown as a separate line, card, or category.
*   **Total Expenses** = all items marked as **OPEX** (operating expenses).
*   **Date recognition:** Income is recognized on the **Payment Receipt Date**; costs are recognized on the **Transaction Date**.

### **Report Behavior**

*   **Read-only:** No action buttons. All payment and expense actions are handled in the Finance module or Project Details.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All payment and expense actions are handled in the Finance module or Project Details.

## **3\. User Flow**

3.1 The user navigates to the Reports module from the left sidebar and clicks "Reports."

3.2 The system loads the Reports landing page displaying all report cards.

3.3 The user locates the "Profit & Loss" report card and clicks "View >".

3.4 The system loads the Profit & Loss report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Profit & Loss," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays the **Profit and Loss Analytics** section with three cards — Profit, Income, and Expenses — each showing a value and a percentage change versus the same period last year.

3.7 The system displays the **Trend Chart** plotting income, expenses, and profit across the period.

3.8 The system displays the **Summary** section with expandable rows: Total Income, Cost of Goods Sold, Gross Profit, Total Expenses, and Net Profit/Loss.

3.9 The user expands a Summary row to view its underlying line items (each line item paginated independently).

3.10 The user changes the Brand and/or Date filter.

*   The system recalculates and updates all sections: the three cards, the Trend Chart, and the Summary.

3.11 The user clicks "Export Report."

*   The system generates an **XLSX** export of the Summary data (analytics cards and chart excluded) and downloads it as "Profit\_Loss\_\[Date\].xlsx".

3.12 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** All cards and Summary rows display "$0.00"; the Trend Chart renders with zero values.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands." A single-brand selection filters all data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range. Future dates are not selectable; the earliest selectable date is the agency creation date.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   The three Analytics cards (Profit, Income, Expenses)
*   The Trend Chart
*   The Summary section (all line items)

### **4.4 Analytics Cards**

*   **Profit:** Equals Net Profit/Loss for the period.
*   **Income:** Equals Total Income for the period.
*   **Expenses:** Equals COGS + Total Expenses (OPEX) for the period.
*   Each card shows a percentage change versus the same period in the prior year.

### **4.5 Summary Logic**

**Total Income:**

*   Sum of client payments received in the period, recognized on the **Payment Receipt Date**.
*   **Excludes** sales tax. Not reduced by platform fees.

**Cost of Goods Sold (COGS):**

*   **Platform fee** (Pixally fee on client-to-agency payments + Stripe fee on agency-to-contractor payments) **\+ Contractor payment + Editor payment**.
*   Editor payments are included within COGS (from Post-Production, when marked as paid) and are not itemized separately.
*   Recognized on the **Transaction Date**.

**Gross Profit:**

*   Total Income − Cost of Goods Sold.

**Total Expenses (OPEX):**

*   Sum of all items marked as operating expenses (OPEX). Does not include COGS.
*   Recognized on the **Transaction Date**.

**Net Profit/Loss:**

*   Gross Profit − Total Expenses.

### **4.6 Trend Chart Logic**

*   Line chart plotting Income, Expenses, and Profit across the selected period.
*   Updates with the applied filters.

### **4.7 Export Logic**

*   "Export Report" generates an **XLSX** file containing the Summary data (Total Income and line items, COGS and line items, Gross Profit, Total Expenses and line items, Net Profit/Loss).
*   Analytics cards and the Trend Chart are excluded (data only).
*   Filename format: "Profit\_Loss\_\[Date\].xlsx". Export reflects applied filters.

### **4.8 Impact**

*   Changing filters recalculates all three sections simultaneously.
*   No data is written back; all changes are display-only.

### **4.9 Formulas Summary**

Total Income = Σ client payments received (Payment Receipt Date in period), excluding sales tax

COGS = Platform fee (Pixally + Stripe) + Contractor payment + Editor payment (Transaction Date in period)

Gross Profit = Total Income − COGS

Total Expenses = Σ OPEX items (Transaction Date in period)

Net Profit/Loss = Gross Profit − Total Expenses

Analytics: Profit = Net Profit/Loss; Income = Total Income; Expenses = COGS + Total Expenses

YoY Change % = ((Current − Same period last year) ÷ Same period last year) × 100

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range; future dates disabled; earliest = agency creation date

### **5.2 Analytics Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Profit

Currency

Net Profit/Loss for period

"$X" with YoY %

Income

Currency

Total Income for period

"$X" with YoY %

Expenses

Currency

COGS + OPEX for period

"$X" with YoY %

### **5.3 Summary Rows**

**Row**

**Data Type**

**Description**

**Display Format**

Total Income

Currency

Payments received, excl. tax

"$X,XXX.XX"

Cost of Goods Sold

Currency

Platform fee + Contractor + Editor

"$X,XXX.XX"

Gross Profit

Currency

Income − COGS

"$X,XXX.XX"

Total Expenses

Currency

OPEX total

"$X,XXX.XX"

Net Profit/Loss

Currency

Gross Profit − Expenses

"$X,XXX.XX"

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before the agency creation date.
*   YoY calculations guard against division by zero (display "0%" or "—").
*   Income excludes sales tax; costs recognized on Transaction Date.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Payment received before service delivered:** Income is recognized on the payment receipt date, so it appears in the period the payment was received, not the event period.
*   **Negative Net Profit:** When expenses exceed income, Net Profit/Loss displays a negative value and the Profit card reflects the loss.
*   **Editor paid but contractor unpaid:** Only paid amounts feed COGS; an unpaid contractor invoice is not included, while a paid editor payment is.
*   **Auto Stripe tax agencies:** Sales tax is handled by Stripe and not stored; income already excludes tax.
*   **Refunds / adjustments:** Handled by the underlying payment and expense records; the report reflects net recognized amounts in the period.
*   **No prior-year data:** YoY comparison displays "0%" or "—" when there is no same-period-last-year baseline.
*   **COGS with no OPEX (or vice versa):** Gross Profit and Net Profit still calculate correctly with the missing component treated as $0.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Filters affect all sections (cards, Trend Chart, Summary).
*   AC-006: Future dates and dates before agency creation are not selectable.

### **8.3 Calculations**

*   AC-007: Income excludes sales tax and is not reduced by platform fees.
*   AC-008: COGS = Platform fee + Contractor payment + Editor payment.
*   AC-009: Editor payments are included within COGS and not itemized separately.
*   AC-010: Gross Profit = Total Income − COGS.
*   AC-011: Total Expenses = sum of OPEX items only.
*   AC-012: Net Profit/Loss = Gross Profit − Total Expenses.
*   AC-013: Income recognized on Payment Receipt Date; costs on Transaction Date.
*   AC-014: Analytics Expenses card = COGS + OPEX.

### **8.4 Export & Read-Only**

*   AC-015: Export generates an XLSX (Summary data only; cards and chart excluded) named "Profit\_Loss\_\[Date\].xlsx".
*   AC-016: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Payments Module

Client payment (income) data

Income cannot be calculated

Internal Module

Expense Management

OPEX and manual COGS entries

Expenses/COGS incomplete

Internal Module

Contractors Module

Contractor payment data

COGS understated

Internal Module

Post-Production Module

Editor payment (paid) data

COGS understated

Internal Module

Payment Processing (Stripe/Pixally)

Platform fee data

COGS understated

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Profit & Loss Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Profit & Loss (Figma design reference)
*   Confirmed revenue, cost, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Financial Forecast

# **Functional Requirements Document (FRD)**

## **Module: Reports – Financial Forecast**

**Document Version:** 1.3  
**Created Date:** January 07, 2026  
**Last Updated:** July 10, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Financial Forecast

### **Purpose**

The Financial Forecast report projects revenue and profit for a selected period, helping agency owners anticipate income, profitability, and per-booking value, with a breakdown by service area.

### **Business Goals**

*   Project total revenue and profit for the selected period.
*   Provide an average revenue-per-booking benchmark.
*   Break down revenue and contractor cost by service area.

### **Report Sections**

*   **Metric Cards** – Total Revenue, Projected Profit, and Avg. Revenue/Booking.
*   **By Service Area** – A table of revenue and contractor payments per service area.

### **Revenue, Profit & Tax Treatment**

*   **Total Revenue** is shown **excluding sales tax** (e.g., $100 on a $110 gross invoice). It is **not** reduced by the platform fee.
    *   **Current period:** money received so far in the period **plus** money expected later in the same period.
    *   **Future period:** money expected to be received during the selected period, regardless of deposits collected in other periods.
*   **Projected Profit** (agency level) = Total Revenue − (Contractor & Editor payment + Platform fee + general Overheads). Overhead is estimated from last year's data, or this year's average if no history exists. General Overheads here means manually-entered COGS + OPEX only (contractor, editor, and platform fee are listed separately and are not double-counted).
*   **Avg. Revenue/Booking** is shown **excluding sales tax**.
    *   **Current period:** revenue so far ÷ bookings completed in the period.
    *   **Future period:** expected revenue ÷ confirmed bookings.
*   **Date recognition (Total Revenue):** based on both the **Payment Receipt Date** (money received) and the **Invoice Due Date** (money expected).

### **Report Behavior**

*   **Read-only:** No action buttons. All booking and payment actions are handled in the Projects and Finance modules.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All booking and payment actions are handled in the Projects and Finance modules.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Financial Forecast" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Financial Forecast," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays three metric cards — Total Revenue, Projected Profit, and Avg. Revenue/Booking — each with a supporting sub-label (e.g., "From X bookings" / "Per booking").

3.7 The system displays the **By Service Area** table with columns: Service Area, Projects, Revenue, Contractor Payments, and Net Profit.

3.8 The user changes the Brand and/or Date filter.

*   The system recalculates all cards and the By Service Area table.

3.9 The user clicks "Export Report."

*   The system generates an **XLSX** export of the metrics and table (visuals excluded) and downloads it as "Financial\_Forecast\_\[Date\].xlsx".

3.10 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** All cards display "$0.00"; the booking sub-labels display "From 0 bookings"; the By Service Area table displays configured areas with $0.00 or a "No data available" message.
*   **No confirmed bookings in period:** Total Revenue "$0.00"; Projected Profit "$0.00" (or negative if overhead exists); Avg. Revenue/Booking "$0.00" or "N/A".
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters all data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   Total Revenue, Projected Profit, and Avg. Revenue/Booking cards
*   The By Service Area table

### **4.4 Total Revenue Logic**

*   Revenue is shown **excluding sales tax** and is not reduced by the platform fee.
*   **Current period:** money received so far in the period (Payment Receipt Date) **plus** money expected later in the same period (Invoice Due Date).
*   **Future period:** money expected to be received during the selected period (Invoice Due Date), regardless of deposits collected in other periods.

### **4.5 Projected Profit Logic (Agency Level)**

*   **Formula:** Total Revenue − (Contractor & Editor payment + Platform fee + general Overheads).
*   **General Overheads** = manually-entered COGS + OPEX only. Contractor, editor, and platform-fee costs are listed explicitly and are **not** also included in "Overheads," to avoid double-counting.
*   **Overhead estimation:** estimated using last year's data; if no history exists, this year's average is used.

### **4.6 Avg. Revenue / Booking Logic**

*   Shown **excluding sales tax**.
*   **Current period:** revenue so far ÷ number of bookings completed in the period.
*   **Future period:** expected revenue ÷ number of confirmed bookings.

### **4.7 By Service Area Logic**

*   Table columns: Service Area, Projects, Revenue (excl. tax), Contractor Payments, and Net Profit.
*   Revenue and Contractor Payments are attributed per service area (both are tied to a project/service area).

**⚠️ Pending Client Confirmation — Net Profit column:** A per-service-area Net Profit requires deducting all COGS and OPEX, but general expenses (e.g., business insurance, software subscriptions) are entered without being tied to a specific service area and cannot be reliably allocated per area. Showing a Net Profit that only nets off contractor payments would be misleading. **Recommendation:** remove the Net Profit column here and display only Revenue and Contractor Payments per service area, keeping the full profit calculation at the agency level (the Projected Profit card). This column is retained pending the client's confirmation.

### **4.8 TBD (To-Be-Determined) Event Date Handling**

*   Every figure on this report is forward-looking and scoped by the date filter. A project whose **event date is TBD** has no date to place it in any period, so it **cannot appear in any card, chart, or normal table row** (Total Revenue, Projected Profit, Avg. Revenue/Booking, and the By Service Area rows all exclude it).
*   TBD projects are surfaced in a dedicated **TBD area**, shown for reference and excluded from period totals until dated:
    *   **Info banner** above the report with the **count of TBD projects** and their **combined estimated revenue** and **estimated profit**.
        *   _Example copy:_ "3 booked projects have a to-be-decided (TBD) event date and can't be placed in this period, so they're not counted in the totals above. Their combined estimated revenue is $8,400.00 (est. profit $5,900.00). These figures will roll into the forecast automatically once each event date is set."
    *   **"TBD — no event date" row** at the bottom of the By Service Area table, tagged **"NOT IN TOTALS"**, showing the projects count and ~ (estimate) values for Revenue, Contractor Payments, and Net Profit.
    *   **Footnote:** "Amounts marked ~ are estimates from projects awaiting an event date. Shown for reference and excluded from period totals until dated."
*   **Estimate basis:** estimated revenue = booking value (excluding tax); estimated profit is calculated the same way as Projected Profit.
*   The TBD area **ignores the date filter** (otherwise TBD items would disappear when a period is selected) but **respects the Brand filter**. If the Brand filter doesn't match, or there are no TBD projects, the TBD banner and row are not shown.
*   "TBD" means **to be determined** (the event date is not yet set), not "not decided."

### **4.9 Export Logic**

*   "Export Report" generates an **XLSX** file containing the metric values and the By Service Area table.
*   Visual elements are excluded (data only).
*   Filename format: "Financial\_Forecast\_\[Date\].xlsx". Export reflects applied filters.

### **4.10 Impact**

*   Changing filters recalculates all cards and the By Service Area table simultaneously.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Revenue

Currency

Received + expected revenue, excl. tax

"$X" + "From X bookings"

Projected Profit

Currency

Revenue − (contractor & editor + platform fee + overhead)

"$X" + "From X bookings"

Avg. Revenue/Booking

Currency

Revenue ÷ bookings, excl. tax

"$X" + "Per booking"

### **5.3 By Service Area Table**

**Column**

**Data Type**

**Description**

**Display Format**

Service Area

Text

Configured service area

Text

Projects

Integer

Project count in the area

Whole number

Revenue

Currency

Revenue for the area, excl. tax

"+$X,XXX.XX"

Contractor Payments

Currency

Contractor cost for the area

"-$X,XXX.XX"

Net Profit

Currency

_Pending confirmation (see 4.7)_

"+$X,XXX.XX"

### **5.4 Validation Rules**

*   Date pickers reject future selections beyond the forecast horizon where applicable and dates before agency creation.
*   Division-by-zero guarded for Avg. Revenue/Booking (display "$0.00" or "N/A").
*   Revenue fields exclude sales tax.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **First-year agency (no history):** Overhead is estimated from this year's average instead of last year's data.
*   **Future period with deposits collected earlier:** Future-period revenue counts money expected in the selected period only, regardless of deposits already collected in other periods.
*   **Zero bookings in period:** Avg. Revenue/Booking displays "$0.00" or "N/A"; Projected Profit may be negative if overhead exists.
*   **General expenses not tied to a service area:** These cannot be allocated per area, which is the basis for the pending recommendation to remove the per-area Net Profit column.
*   **TBD event date:** A booked project with a TBD event date cannot be placed in any period and is excluded from all cards and normal rows; it appears only in the TBD banner and the "TBD — no event date / NOT IN TOTALS" row with ~ estimates. The TBD area ignores the date filter but respects the Brand filter, and is hidden when nothing matches.
*   **Auto Stripe tax agencies:** Tax is handled by Stripe and not stored; revenue already excludes tax.
*   **Service area with revenue but no contractor cost:** Contractor Payments displays "$0.00" for that row.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Filters affect all sections (all three cards and the By Service Area table).

### **8.3 Calculations**

*   AC-006: Total Revenue excludes sales tax and is not reduced by platform fees.
*   AC-007: Current-period Total Revenue = received (Payment Receipt Date) + expected (Invoice Due Date) within the period.
*   AC-008: Future-period Total Revenue = expected revenue in the period (Invoice Due Date).
*   AC-009: Projected Profit = Total Revenue − (Contractor & Editor payment + Platform fee + general Overheads), with no double-counting.
*   AC-010: Overhead is estimated from last year's data, or this year's average if no history exists.
*   AC-011: Avg. Revenue/Booking excludes tax and uses the current/future-period definitions.
*   AC-012: By Service Area shows Revenue and Contractor Payments per area; the Net Profit column is marked pending client confirmation.
*   AC-013: TBD-event-date projects are excluded from all cards and normal rows and shown only in the TBD banner (count + combined estimated revenue and profit) and the "TBD — no event date / NOT IN TOTALS" row with ~ estimates. The TBD area ignores the date filter, respects the Brand filter, and is hidden when nothing matches.

### **8.4 Export & Read-Only**

*   AC-014: Export generates an XLSX (metrics + table; visuals excluded) named "Financial\_Forecast\_\[Date\].xlsx".
*   AC-015: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Projects Module

Bookings and service-area data

Revenue and booking counts unavailable

Internal Module

Payments Module

Received and expected payment data

Revenue cannot be calculated

Internal Module

Invoices Module

Invoice due dates (expected money)

Expected revenue unavailable

Internal Module

Contractors / Post-Production

Contractor and editor cost data

Projected Profit understated

Internal Module

Expense Management

Overhead (COGS + OPEX) data

Overhead estimate unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Financial Forecast Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Financial Forecast (Figma design reference)
*   Confirmed revenue, profit, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Income

# **Functional Requirements Document (FRD)**

## **Module: Reports – Income**

**Document Version:** 1.3  
**Created Date:** January 07, 2026  
**Last Updated:** July 10, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Income

### **Purpose**

The Income report tracks actual collected revenue and outstanding payments, giving agency owners visibility into what has been paid and what is still owed across a selected period.

### **Business Goals**

*   Show collected revenue and outstanding balances for any selected period.
*   Distinguish overdue from pending amounts to guide collections.
*   Provide a paid/unpaid invoice breakdown for follow-up.

### **Report Sections**

*   **Metric Cards** – Collected Revenue, Overdue, Pending, and Total Outstanding.
*   **Monthly Income Breakdown** – Stacked bar chart of paid, overdue, and upcoming amounts by month.
*   **Invoices** – Paid Invoices and Unpaid Invoices tables.

### **Revenue & Tax Treatment**

*   All figures are shown **excluding sales tax** (e.g., $100 on a $110 gross invoice). Revenue is **not** reduced by the platform fee.
*   **Date recognition:** income is recognized on the **Payment Receipt Date**; unpaid invoices use the **Due Date**.

### **Report Behavior**

*   **Read-only:** No action buttons. All payment actions (Mark as Paid, Send Reminder, etc.) are handled in the Finance module or Project Details.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All payment actions are handled in the Finance module or Project Details.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Income" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Income," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays four cards: Collected Revenue, Overdue, Pending, and Total Outstanding.

3.7 The system displays the **Monthly Income Breakdown** stacked bar chart (paid, overdue, upcoming), fixed to the current year.

3.8 The system displays the **Invoices** section with Paid Invoices (default) and Unpaid Invoices tabs.

*   Table columns: Payment Date / Due Date, Invoice ID, Client, Amount, Status, Project.

3.9 The user switches to the Unpaid Invoices tab.

*   The table updates to show unpaid invoices; the cards and chart are unaffected by the tab switch.

3.10 The user sorts a table column or paginates through records.

3.11 The user changes the Brand and/or Date filter.

*   The system updates the four cards and the invoice tables. The Monthly Income Breakdown chart updates for Brand only and remains fixed to the current year (not affected by the Date filter).

3.12 The user clicks "Export Report."

*   The system generates an **XLSX** export with two sheets — Paid Invoices and Unpaid Invoices — and downloads it as "Income\_Report\_\[Date\].xlsx".

3.13 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** All cards display "$0.00"; the chart renders with zero values; the tables show an empty-state message.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

**Section / Element**

**Brand Filter**

**Date Filter**

Collected Revenue

✅

✅

Overdue

✅

✅

Pending

✅

✅

Total Outstanding

✅

✅

Paid & Unpaid Invoice tables

✅

✅

Monthly Income Breakdown (chart)

✅

❌ (fixed to current year)

TBD area (banner + TBD grouping)

✅

❌ (ignores date; see 4.9)

### **4.4 Metric Card Logic**

All amounts exclude sales tax.

*   **Collected Revenue:** Sum of payments received in the period (recognized on Payment Receipt Date).
*   **Overdue:** Sum of unpaid invoice amounts whose Due Date is in the past (before today).
*   **Pending:** Sum of unpaid invoice amounts whose Due Date is today or in the future.
*   **Total Outstanding:** Overdue + Pending (all unpaid amounts).

### **4.5 Monthly Income Breakdown Logic**

*   Stacked bar chart per month showing Paid (green), Overdue (red), and Upcoming (blue) amounts.
*   **Fixed to the current year;** responds to the Brand filter but **not** the Date filter.
*   Amounts exclude sales tax.

### **4.6 Invoices Table Logic**

**Paid Invoices tab (default):**

*   Columns: Payment Date, Invoice ID, Client, Amount, Status, Project.
*   Status shows "Paid" (green). Amount shows the payment value with an installment indicator (e.g., "$250.00" with "1 of 2").

**Unpaid Invoices tab:**

*   Columns: Due Date, Invoice ID, Client, Amount, Status, Project.
*   Status shows "Overdue" (red) for past-due invoices or "Pending" (orange) for future due dates.

**Common:**

*   All columns are sortable. Default sort: Payment Date / Due Date descending.
*   Pagination: 10 / 25 / 50 rows per page.
*   **Read-only:** no Actions column; no Mark as Paid or Send Reminder in this report.

### **4.8 TBD (To-Be-Determined) Event Date Handling**

*   The outstanding-side amounts are placed on the timeline by their due date. An unpaid invoice whose **event is TBD** has **no determinable due date**, so it cannot be classified as Overdue or Pending and cannot be placed in any period. It is therefore **excluded from the outstanding-side cards** — Overdue, Pending, and Total Outstanding — and from the normal Unpaid table rows.
*   **Collected Revenue is never affected:** any payment already collected carries a real payment date and stays in Collected Revenue. Only the **unpaid (outstanding) amount** tied to the TBD event moves to the TBD grouping. In the common case (nothing paid yet), the whole invoice sits in TBD.
*   TBD invoices are surfaced in a dedicated **TBD area**:
    *   **Info banner** above the report with the **count of TBD invoices/projects** and their **combined estimated (outstanding) revenue** (excluding tax).
    *   **"TBD — no event date" grouping** in the Unpaid Invoices table, tagged **"NOT IN TOTALS."**
*   The TBD area **ignores the date filter** (otherwise TBD items would disappear when a period is selected) but **respects the Brand filter**. If the Brand filter doesn't match, or there are no TBD invoices, the TBD area is not shown.
*   "TBD" means **to be determined** (the event date is not yet set), not "not decided."

### **4.9 Export Logic**

*   "Export Report" generates an **XLSX** file with two sheets: "Paid Invoices" and "Unpaid Invoices."
*   Cards and chart are excluded (data only).
*   Filename format: "Income\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.10 Impact**

*   Changing filters updates the four cards and the invoice tables; the Monthly Income Breakdown chart updates for Brand only and stays fixed to the current year.
*   The TBD area ignores the date filter and follows the Brand filter only.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Collected Revenue

Currency

Payments received, excl. tax

"$X,XXX.XX"

Overdue

Currency

Past-due unpaid amounts, excl. tax

"$X,XXX.XX"

Pending

Currency

Not-yet-due unpaid amounts, excl. tax

"$X,XXX.XX"

Total Outstanding

Currency

Overdue + Pending, excl. tax

"$X,XXX.XX"

### **5.3 Invoice Table Columns**

**Column**

**Data Type**

**Description**

**Display Format**

Payment Date / Due Date

Date

Paid date (Paid) or due date (Unpaid)

"MMM D, YYYY"

Invoice ID

Text

Unique invoice identifier

"#INVXXXXX"

Client

Text + Avatar

Client name with avatar

Text with avatar

Amount

Currency + Text

Amount with installment indicator

"$X.XX" + "X of Y"

Status

Badge

Paid / Overdue / Pending

Colored badge

Project

Text

Associated project

Text

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   All amounts exclude sales tax.
*   Overdue vs Pending is determined by comparing the Due Date to today.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Payment received before service delivered:** Collected Revenue reflects the payment in the period it was received (Payment Receipt Date).
*   **Past-due unpaid invoice:** Counts toward Overdue and shows an "Overdue" status; it is not labeled "Pending."
*   **Installment payments:** Amount shows "X of Y" to indicate which installment of the invoice a payment represents.
*   **Monthly Income Breakdown vs Date filter:** The chart stays on the current year even when the Date filter selects a different period; only the Brand filter affects it.
*   **TBD event date (no due date):** An unpaid invoice whose event is TBD has no determinable due date, so it is excluded from Overdue, Pending, and Total Outstanding and shown only in the TBD area (banner + "TBD — no event date / NOT IN TOTALS" grouping). Collected Revenue is unaffected; if a partial payment was collected, that portion stays in Collected Revenue and only the unpaid remainder appears in the TBD grouping. The TBD area ignores the date filter but respects the Brand filter, and is hidden when nothing matches.
*   **Auto Stripe tax agencies:** Sales tax is handled by Stripe and not stored; income already excludes tax.
*   **All invoices paid:** Unpaid Invoices tab shows an empty-state message; Overdue, Pending, and Total Outstanding show "$0.00".
*   **Purely future date range:** Collected Revenue may be "$0.00" if no payments were received in that window.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Cards and invoice tables respond to both Brand and Date filters.
*   AC-006: Monthly Income Breakdown responds to Brand only and remains fixed to the current year.
*   AC-007: The TBD area ignores the date filter and responds to the Brand filter only; it is hidden when nothing matches.

### **8.3 Calculations**

*   AC-008: All amounts exclude sales tax and are not reduced by platform fees.
*   AC-009: Collected Revenue = payments received in the period (Payment Receipt Date).
*   AC-010: Overdue = unpaid amounts past due; Pending = unpaid amounts not yet due.
*   AC-011: Total Outstanding = Overdue + Pending.
*   AC-012: Unpaid invoices whose event is TBD (no determinable due date) are excluded from Overdue, Pending, and Total Outstanding and shown only in the TBD area (banner + "TBD — no event date / NOT IN TOTALS" grouping). Collected Revenue is unaffected; only the unpaid remainder appears in the TBD grouping.

### **8.4 Tables, Export & Read-Only**

*   AC-013: Paid tab shows 6 columns with "Paid" status; Unpaid tab shows 6 columns with "Overdue"/"Pending" status.
*   AC-014: Tables have no Actions column and no Mark as Paid / Send Reminder in this report.
*   AC-015: Export generates an XLSX with two sheets (Paid Invoices, Unpaid Invoices) named "Income\_Report\_\[Date\].xlsx".
*   AC-016: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Payments Module

Collected payment data

Collected Revenue unavailable

Internal Module

Invoices Module

Invoice and due-date data

Overdue/Pending and tables unavailable

Internal Module

Payment Schedules

Installment information

Installment indicators unavailable

Internal Module

Projects Module

Links invoices to projects

Project column unavailable

Internal Module

Clients Module

Client information

Client column unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Income Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Income (Figma design reference)
*   Confirmed revenue, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Sales

# **Functional Requirements Document (FRD)**

## **Module: Reports – Sales**

**Document Version:** 1.3  
**Created Date:** January 07, 2026  
**Last Updated:** July 10, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Sales

### **Purpose**

The Sales report shows the total value of projects booked over a selected period, along with booking counts, average booking value, conversion rate, package performance, and pipeline status.

### **Business Goals**

*   Show total booked sales and booking volume for any selected period.
*   Provide average booking value and lead-to-booking conversion.
*   Reveal which packages and à la carte items drive revenue.
*   Visualize pipeline stage distribution.

### **Report Sections**

*   **Metric Cards** – Total Booked Sales, Total Bookings, Avg Booking Value, and Conversion Rate.
*   **Packages & À La Carte Items Statistics** – Two tabs listing bookings and revenue per package / item.
*   **Sales Report (Monthly Sales Breakdown)** – Bar chart of booked sales by month.
*   **Pipeline Status** – Bar chart of projects by pipeline stage.

### **Revenue & Tax Treatment**

*   Sales amounts reflect the **total value of projects booked** in each period, **not** payments collected.
*   All revenue figures are shown **excluding sales tax** (e.g., $100 on a $110 gross invoice). Revenue is **not** reduced by the platform fee.
*   **Date recognition:** based on the **Booking Date**. A project is considered **booked once the first payment is made**, and the booking (and its full value) is placed on the **first-payment date**.

### **Report Behavior**

*   **Read-only:** No action buttons. All booking actions are handled in the Projects module.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All booking actions are handled in the Projects module.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Sales" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Sales Report," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays four cards: Total Booked Sales, Total Bookings, Avg Booking Value, and Conversion Rate.

3.7 The system displays the **Packages & À La Carte Items Statistics** section with Packages (default) and À La Carte Items tabs.

*   Columns: Package/Item Name, Booked, Revenue.

3.8 The system displays the **Sales Report (Monthly Sales Breakdown)** bar chart, fixed to the current year.

3.9 The system displays the **Pipeline Status** bar chart showing project counts per stage.

3.10 The user changes the Brand and/or Date filter.

*   The system updates the four cards and the Pipeline Status chart. The Package Statistics, À La Carte Statistics, and Monthly Sales Breakdown update for Brand only and remain fixed to the current year (not affected by the Date filter).

3.11 The user clicks "Export Report."

*   The system generates an **XLSX** export of the metrics and statistics (charts excluded) and downloads it as "Sales\_Report\_\[Date\].xlsx".

3.12 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no bookings:** Cards display "$0.00" / "0" / "0%"; the statistics tables are empty (only booked packages/items are ever listed) and show a "no packages/items booked yet" message; charts render with zero values.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

**Section / Element**

**Brand Filter**

**Date Filter**

Total Booked Sales

✅

✅

Total Bookings

✅

✅

Avg Booking Value

✅

✅

Conversion Rate

✅

✅

Pipeline Status (chart)

✅

✅

Package Statistics

✅

❌ (fixed to current year)

À La Carte Statistics

✅

❌ (fixed to current year)

Monthly Sales Breakdown (chart)

✅

❌ (fixed to current year)

### **4.4 Metric Card Logic**

All revenue figures exclude sales tax.

*   **Booked definition:** a project is counted as **booked in the period when its first payment is made**, placed on the **first-payment date**. The amount counted is the **full booking value**, not the payment amount.
*   **Total Booked Sales:** Sum of the total value of projects booked in the period (booking value, not payments collected).
*   **Total Bookings:** Count of projects booked in the period (by first-payment date).
*   **Avg Booking Value:** Total Booked Sales ÷ Total Bookings.
*   **Conversion Rate:** Total Bookings ÷ Total Leads for the period, as a percentage. If Total Leads is 0, display "0%".

**Invoice adjustments:** Only the original booking value at the time of booking is counted; later invoice adjustments do not retroactively change the sales value.

### **4.5 Packages & À La Carte Statistics Logic**

*   **Packages tab:** For each package — Package Name, Booked (count), Revenue (excl. tax).
*   **À La Carte Items tab:** For each item — Item Name, Booked (count), Revenue (excl. tax).
*   **Booked basis:** a package / item is counted as booked when the project's **first payment is made**, and is placed on the **first-payment date**.
*   **List scope:** the tables list **only packages / à la carte items that have at least one booking**. Items that have never been booked do **not** appear in the list (they are not shown with a zero count).
*   Respond to the Brand filter; **fixed to the current year** (not affected by the Date filter).

### **4.6 Sales Report (Monthly Sales Breakdown) Logic**

*   Bar chart of booked sales by month.
*   Responds to the Brand filter; **fixed to the current year** (not affected by the Date filter).

### **4.7 Pipeline Status Logic**

*   Bar chart of project counts by pipeline stage (e.g., New Lead, Follow-up, Proposal Sent, Proposal Signed, Deposit Paid, Planning, Post Production, Completed).
*   Responds to **both** Brand and Date filters.

### **4.8 Export Logic**

*   "Export Report" generates an **XLSX** file containing the metric values and the package / à la carte statistics.
*   Charts are excluded (data only).
*   Filename format: "Sales\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.9 Impact**

*   Changing filters updates the four cards and Pipeline Status; the Package Statistics, À La Carte Statistics, and Monthly Sales Breakdown update for Brand only and stay fixed to the current year.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Booked Sales

Currency

Booking value, excl. tax

"$X,XXX.XX"

Total Bookings

Integer

Count of bookings

Whole number

Avg Booking Value

Currency

Total Booked Sales ÷ Total Bookings

"$X,XXX.XX"

Conversion Rate

Percentage

Bookings ÷ Leads

"X%"

### **5.3 Statistics Tables**

**Column**

**Data Type**

**Description**

**Display Format**

Package / Item Name

Text

Package or à la carte item

Text

Booked

Integer

Times booked

Whole number

Revenue

Currency

Revenue for the package/item, excl. tax

"$X,XXX.XX"

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   Conversion Rate and Avg Booking Value guard against division by zero (display "0%" / "$0.00").
*   All revenue figures exclude sales tax.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Booking value vs collected payments:** Sales reflect the booked value even if little or no payment has been collected yet.
*   **Booked = first payment:** A project (and its packages/items) is counted only once the first payment is made, and is placed on the first-payment date; a signed proposal with no payment yet is not counted.
*   **Unbooked packages/items:** A configured package or à la carte item that has never been booked does not appear in the statistics list at all.
*   **Invoice adjusted after booking:** The sales value remains the original booking amount; later adjustments do not change it.
*   **Package booked but no revenue recorded:** Revenue shows "$0.00" for that row while the Booked count still increments.
*   **Statistics/Monthly chart vs Date filter:** These stay on the current year regardless of the Date filter; only Brand affects them. Pipeline Status, by contrast, follows both filters.
*   **Zero leads with bookings:** Conversion Rate displays "0%" to avoid division by zero.
*   **Auto Stripe tax agencies:** Sales tax is handled by Stripe and not stored; sales figures already exclude tax.
*   **Agency younger than 12 months:** The monthly chart shows available months only, with zero bars before agency creation.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: The four cards and Pipeline Status respond to both Brand and Date filters.
*   AC-006: Package Statistics, À La Carte Statistics, and Monthly Sales Breakdown respond to Brand only and remain fixed to the current year.

### **8.3 Calculations**

*   AC-007: All revenue figures exclude sales tax and are not reduced by platform fees.
*   AC-008: Total Booked Sales reflects booking value, not collected payments.
*   AC-009: A project (and its packages/items) is counted as booked when its first payment is made, placed on the first-payment date.
*   AC-010: Package and À La Carte Booked counts and Revenue are placed on the first-payment date.
*   AC-011: The statistics tables list only packages/items with at least one booking; never-booked items do not appear.
*   AC-012: Avg Booking Value = Total Booked Sales ÷ Total Bookings.
*   AC-013: Conversion Rate = Bookings ÷ Leads; displays "0%" when Leads is 0.
*   AC-014: Only the original booking value is counted; later invoice adjustments do not change it.

### **8.4 Export & Read-Only**

*   AC-015: Export generates an XLSX (metrics + statistics; charts excluded) named "Sales\_Report\_\[Date\].xlsx".
*   AC-016: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Projects Module

Bookings and booking value

Sales metrics unavailable

Internal Module

Leads Module

Lead data for conversion

Conversion Rate unavailable

Internal Module

Templates / Packages

Package and à la carte definitions

Statistics tables unavailable

Internal Module

Pipeline / Workflow

Pipeline stage data

Pipeline Status unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Sales Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Sales (Figma design reference)
*   Confirmed revenue, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Accounts Receivables

# **Functional Requirements Document (FRD)**

## **Module: Reports – Accounts Receivable**

**Document Version:** 1.3  
**Created Date:** January 07, 2026  
**Last Updated:** July 10, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Accounts Receivable

### **Purpose**

The Accounts Receivable (AR) report helps agency owners manage outstanding invoices and track expected incoming payments, distinguishing overdue balances from upcoming ones.

### **Business Goals**

*   Show total outstanding invoice value for any selected period.
*   Distinguish overdue invoices from upcoming ones for collections prioritization.
*   Provide an invoice-level view of what is owed and when.

### **Report Sections**

*   **Metric Cards** – Total Invoices, Overdue Invoices, and Upcoming Invoices.
*   **Accounts Receivable Chart** – Bar chart of overdue and upcoming amounts by month.
*   **Invoices** – Upcoming Invoices and Overdue Invoices tables.

### **Amount & Tax Treatment**

*   AR is the one report that is **tax-inclusive**: all amounts show the **Total Invoice amount including sales tax** (e.g., $110 on a $100 net invoice with $10 tax).
*   **Date recognition:** based on the **Invoice Created Date** (e.g., an invoice created May 1 and due May 15 appears in the May 1 period).

### **Report Behavior**

*   **Read-only:** No action buttons. All payment actions (Mark as Paid, Send Reminder, etc.) are handled in the Finance module or Project Details.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All payment actions are handled in the Finance module or Project Details.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Accounts Receivable" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Accounts Receivable," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays three cards: Total Invoices, Overdue Invoices, and Upcoming Invoices (each with an invoice count).

3.7 The system displays the **Accounts Receivable** bar chart with Overdue Invoices and Upcoming Invoices series by month.

3.8 The system displays the **Invoices** section with Upcoming Invoices and Overdue Invoices tabs.

*   Table columns: Date, Invoice ID, Client, Amount, Status, Project.

3.9 The user switches between the Upcoming and Overdue tabs.

3.10 The user sorts a table column or paginates through records.

3.11 The user changes the Brand and/or Date filter.

*   The system recalculates all three cards, the chart, and the invoice tables.

3.12 The user clicks "Export Report."

*   The system generates an **XLSX** export of the invoices (cards and chart excluded) and downloads it as "Accounts\_Receivable\_Report\_\[Date\].xlsx".

3.13 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **No outstanding invoices:** All cards display "$0.00" / "0 invoices"; the chart renders empty; the table shows "No outstanding invoices. All payments are up to date!"
*   **No invoices created:** All cards show $0.00 / 0; the table shows "No invoices found."
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   All three cards (Total Invoices, Overdue Invoices, Upcoming Invoices)
*   The Accounts Receivable chart
*   Both invoice tables (Upcoming and Overdue)

The **TBD area** (banner + "TBD — no event date" grouping) is the exception: it **ignores the date filter** and responds to the **Brand filter only** (see 4.7).

### **4.4 Metric Card Logic**

All amounts are **tax-inclusive** (Total Invoice amount).

*   **Total Invoices:** Total value of all outstanding invoices in the period, with a count of invoices.
*   **Overdue Invoices:** Total value of outstanding invoices whose due date has passed (before today), with a count.
*   **Upcoming Invoices:** Total value of outstanding invoices whose due date is today or in the future, with a count.

### **4.5 Accounts Receivable Chart Logic**

*   Bar chart by month showing two series: **Overdue Invoices** and **Upcoming Invoices**.
*   Amounts are tax-inclusive, consistent with the cards.
*   Updates with the applied filters.

**Note:** This report does **not** use aging buckets (e.g., 1–30 / 31–60 / 61–90 days). The chart compares Overdue vs Upcoming amounts by month.

### **4.6 Invoices Table Logic**

**Upcoming Invoices tab / Overdue Invoices tab:**

*   Columns: Date, Invoice ID, Client, Amount (tax-inclusive, with installment indicator where applicable), Status, Project.
*   **Status:** "Overdue" (red) for past-due invoices; "Upcoming" for invoices due today or later.
*   All columns are sortable. Default sort: Date descending.
*   Pagination: 10 / 25 / 50 rows per page.
*   **Read-only:** no Actions column; no Mark as Paid or Send Reminder in this report.

### **4.7 TBD (To-Be-Determined) Event Date Handling**

*   Outstanding invoices are placed on the timeline by their due date, and every card and chart on this report is date-scoped. An invoice whose **event is TBD** has **no determinable due date**, so it cannot be classified as Overdue or Upcoming and cannot be placed in any period. It is therefore **excluded from Total Invoices, Overdue Invoices, and Upcoming Invoices** (and from the chart and normal table rows).
*   TBD invoices are surfaced in a dedicated **TBD area**:
    *   **Info banner** above the report with the **count of TBD invoices** and their **combined estimated amount** (Total Invoice amount, **including tax**, consistent with this report).
    *   **"TBD — no event date" grouping** in the invoice table, tagged **"NOT IN TOTALS."**
*   The TBD area **ignores the date filter** (otherwise TBD items would disappear when a period is selected) but **respects the Brand filter**. If the Brand filter doesn't match, or there are no TBD invoices, the TBD area is not shown.
*   Any payment already collected on such an invoice keeps its real date in the underlying records; only the **outstanding amount** tied to the TBD event appears in the TBD grouping.
*   "TBD" means **to be determined** (the event date is not yet set), not "not decided."

### **4.8 Export Logic**

*   "Export Report" generates an **XLSX** file containing the invoice data.
*   Cards and chart are excluded (data only).
*   Filename format: "Accounts\_Receivable\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.9 Impact**

*   Changing filters recalculates all cards, the chart, and the tables simultaneously.
*   The TBD area ignores the date filter and follows the Brand filter only.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Invoices

Currency + count

All outstanding invoices, incl. tax

"$X" + "X invoices"

Overdue Invoices

Currency + count

Past-due outstanding, incl. tax

"$X" + "X invoices"

Upcoming Invoices

Currency + count

Not-yet-due outstanding, incl. tax

"$X" + "X invoices"

### **5.3 Invoice Table Columns**

**Column**

**Data Type**

**Description**

**Display Format**

Date

Date

Invoice date

"MMM D, YYYY"

Invoice ID

Text

Unique invoice identifier

"#INVXXXXX"

Client

Text + Avatar

Client name with avatar

Text with avatar

Amount

Currency + Text

Amount incl. tax, with installment indicator

"$X.XX" + "X of Y"

Status

Badge

Overdue / Upcoming

Colored badge

Project

Text

Associated project

Text

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   All amounts are tax-inclusive (Total Invoice amount).
*   Overdue vs Upcoming is determined by comparing the due date to today.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Invoice created and due in different months:** The invoice is attributed to the period of its Invoice Created Date (e.g., created May 1, due May 15 → May 1 period).
*   **Tax-inclusive amounts:** Unlike Income and other performance reports, AR shows the full invoice amount including tax.
*   **Partially paid invoice:** The outstanding (unpaid) balance is reflected; installment indicators show which portion remains.
*   **Invoice due today:** Classified as Upcoming (not Overdue) until the due date has passed.
*   **TBD event date (no due date):** An outstanding invoice whose event is TBD has no determinable due date, so it is excluded from Total Invoices, Overdue, and Upcoming and shown only in the TBD area (banner + "TBD — no event date / NOT IN TOTALS" grouping), with amounts tax-inclusive. The TBD area ignores the date filter but respects the Brand filter, and is hidden when nothing matches.
*   **All invoices paid:** Cards show $0.00 / 0; tables show the all-clear empty-state message.
*   **Auto Stripe tax agencies:** Where tax is handled by Stripe and not stored, the invoice amount reflects what is recorded in the system.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Filters affect all sections (three cards, chart, both tables).
*   AC-006: The TBD area ignores the date filter and responds to the Brand filter only; it is hidden when nothing matches.

### **8.3 Structure & Calculations**

*   AC-007: The report shows three cards — Total Invoices, Overdue Invoices, Upcoming Invoices — each with a count.
*   AC-008: The chart shows Overdue vs Upcoming amounts by month and does not use aging buckets.
*   AC-009: All amounts are tax-inclusive (Total Invoice amount).
*   AC-010: Data is attributed by the Invoice Created Date.
*   AC-011: Overdue = past-due outstanding; Upcoming = not-yet-due outstanding.
*   AC-012: Invoices whose event is TBD (no determinable due date) are excluded from Total Invoices, Overdue, and Upcoming and shown only in the TBD area (banner + "TBD — no event date / NOT IN TOTALS" grouping), with tax-inclusive amounts.

### **8.4 Tables, Export & Read-Only**

*   AC-013: Tables have no Actions column and no Mark as Paid / Send Reminder in this report.
*   AC-014: Export generates an XLSX (invoices only; cards and chart excluded) named "Accounts\_Receivable\_Report\_\[Date\].xlsx".
*   AC-015: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Invoices Module

Invoice, due-date, and created-date data

Report cannot be calculated

Internal Module

Payments Module

Payment status for outstanding balances

Outstanding amounts inaccurate

Internal Module

Payment Schedules

Installment information

Installment indicators unavailable

Internal Module

Projects Module

Links invoices to projects

Project column unavailable

Internal Module

Clients Module

Client information

Client column unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Accounts Receivable Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Accounts Receivable (Figma design reference)
*   Confirmed amount, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Expenses

# **Functional Requirements Document (FRD)**

## **Module: Reports – Expenses**

**Document Version:** 1.2  
**Created Date:** January 07, 2026  
**Last Updated:** July 06, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Expenses

### **Purpose**

The Expenses report lets agency owners track and analyze all agency expenses, separating operating expenses (OPEX) from cost of goods sold (COGS), including contractor payments, editor payments, and platform fees.

### **Business Goals**

*   Provide a complete view of agency spending across categories.
*   Separate direct costs (COGS) from operating expenses (OPEX).
*   Surface contractor spend and per-transaction averages.

### **Report Sections**

*   **Expenses by Type** – Stacked bar chart of OPEX and COGS over time.
*   **Metric Cards** – Total Expenses, Contractor Payments, Average Expense, Total Transactions, Operating Expenses (OPEX), and COGS (Cost of Goods Sold).
*   **Expense Details** – A table of individual expense line items.

### **Cost, Fee & Tax Treatment**

*   **COGS (card and calculation)** = items manually marked as COGS **\+ Pixally fee** (charged when the client pays the agency) **\+ Stripe fee** (charged when the agency pays a contractor) **\+ Contractor payments + Editor payments**. Editor payments are included within COGS and are not itemized as a separate card or category.
*   **Total Expenses** = COGS + OPEX. (Contractor and editor payments are already inside COGS; they are not added again on top.)
*   **Contractor Payments (card)** = amount paid to contractors **excluding** Stripe fees; this is a breakout/subset of COGS shown for visibility.
*   **Fee treatment example:** to pay a contractor $100, the agency pays $103 (including the Stripe fee). The system logs $100 under Contractor Payments (part of COGS) **and** a separate $3 line item as a Stripe fee (also part of COGS).
*   **OPEX** = all items added as operating expenses.
*   **Average Expense** = Total Expenses ÷ Total Transactions.
*   **Total Transactions** = total number of expense line items.
*   **Date recognition:** expenses are recognized on the **Transaction Date**.

### **Report Behavior**

*   **Read-only:** No action buttons. All expense entry and editing is handled in the Finance / Expense Management module.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All expense entry and editing is handled in the Finance / Expense Management module.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Expenses" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, Year to Date).

3.5 The system displays the header with a back arrow, title "Expenses," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays the **Expenses by Type** stacked bar chart (OPEX + COGS) across the period.

3.7 The system displays six metric cards: Total Expenses, Contractor Payments, Average Expense, Total Transactions, Operating Expenses (OPEX), and COGS (Cost of Goods Sold).

3.8 The system displays the **Expense Details** table with columns: Date, Category (OPEX/COGS), Category (sub-category), Amount, and Notes.

3.9 The user sorts the table by a sortable column or paginates through records.

3.10 The user changes the Brand and/or Date filter.

*   The system recalculates all six cards, the chart, and the Expense Details table.

3.11 The user clicks "Export Report."

*   The system generates an **XLSX** export of the Expense Details (cards and chart excluded) and downloads it as "Expenses\_Report\_\[Date\].xlsx".

3.12 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** All cards display "$0.00" / "0"; the chart renders with zero values; the table shows an empty-state message.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters all data to that brand.
*   **Date filter:** Default "Year to Date (YTD)." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   All six metric cards
*   The Expenses by Type chart
*   The Expense Details table

### **4.4 Metric Card Logic**

**Total Expenses:**

*   COGS + OPEX. (Contractor and editor payments are already within COGS.)

**Contractor Payments:**

*   Amount paid to contractors, **excluding** Stripe fees. A breakout/subset of COGS shown for visibility.

**Average Expense:**

*   Total Expenses ÷ Total Transactions.

**Total Transactions:**

*   Total number of expense line items in the period.

**Operating Expenses (OPEX):**

*   Sum of all items added as operating expenses.

**COGS (Cost of Goods Sold):**

*   Items manually marked as COGS + Pixally fee (client-to-agency) + Stripe fee (agency-to-contractor) + Contractor payments + Editor payments.
*   The COGS card represents the **full** COGS and is therefore larger than the standalone Contractor Payments card.

### **4.5 Fee Handling Logic**

*   **Pixally fee:** charged when the client pays the agency; logged as a COGS line item.
*   **Stripe fee:** charged when the agency pays a contractor; logged as a separate COGS line item.
*   **Example:** paying a contractor $100 costs the agency $103. The system records $100 as a Contractor Payment (COGS) and $3 as a Stripe fee (COGS). Contractor Payments card shows $100 (excludes the $3 fee); COGS includes both.

### **4.6 Expenses by Type Chart Logic**

*   Stacked bar chart showing OPEX and COGS per period bucket.
*   COGS in the chart includes the Pixally fee, Stripe fee, and contractor payments.
*   Updates with the applied filters.

### **4.7 Expense Details Table Logic**

*   Columns: Date, Category (OPEX or COGS), Category (sub-category, e.g., Business Insurance, Contractor, Legal Fees), Amount, Notes.
*   Sortable columns include Date, Category, and Amount.
*   Default sort: Date descending. Pagination: 10 / 25 / 50 rows per page.

### **4.8 Export Logic**

*   "Export Report" generates an **XLSX** file containing the Expense Details line items.
*   Cards and chart are excluded (data only).
*   Filename format: "Expenses\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.9 Impact**

*   Changing filters recalculates all cards, the chart, and the table simultaneously.
*   No data is written back; all changes are display-only.

### **4.10 Formulas Summary**

COGS = Manual COGS items + Pixally fee + Stripe fee + Contractor payments + Editor payments

OPEX = Σ operating-expense items

Total Expenses = COGS + OPEX

Contractor Pmts = Σ contractor payments (excluding Stripe fees) \[subset of COGS\]

Average Expense = Total Expenses ÷ Total Transactions

Total Transactions = count of expense line items

(All recognized on Transaction Date within the selected period)

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

Year to Date (YTD)

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Expenses

Currency

COGS + OPEX

"$X,XXX.XX" — "All categories"

Contractor Payments

Currency

Contractor pay excl. Stripe fee

"$X,XXX.XX" — "Total paid to contractors"

Average Expense

Currency

Total Expenses ÷ Total Transactions

"$X,XXX.XX" — "Per transaction"

Total Transactions

Integer

Count of expense line items

Whole number — "Number of expenses"

Operating Expenses (OPEX)

Currency

Sum of OPEX items

"$X,XXX.XX"

COGS (Cost of Goods Sold)

Currency

Full COGS (incl. contractor, editor, fees)

"$X,XXX.XX"

### **5.3 Expense Details Table**

**Column**

**Data Type**

**Description**

**Display Format**

Date

Date

Transaction date

"MMM D, YYYY"

Category

Text

OPEX or COGS

Text badge

Category (sub)

Text

Sub-category

Text

Amount

Currency

Line item amount

"$X,XXX.XX"

Notes

Text

Free-text note

Text

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   Average Expense guards against division by zero (display "$0.00").
*   Contractor Payments card excludes Stripe fees; COGS includes them.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Contractor payment with Stripe fee:** Logged as two COGS line items — the contractor amount and the separate Stripe fee. The Contractor Payments card shows only the contractor amount.
*   **Editor payment:** Included within COGS; never shown as a separate card or category.
*   **Only OPEX, no COGS (or vice versa):** Total Expenses still equals COGS + OPEX with the missing component treated as $0.
*   **Zero transactions:** Average Expense displays "$0.00" to avoid division by zero.
*   **Same-day multiple expenses:** Each is counted as a distinct transaction toward Total Transactions.
*   **Auto Stripe tax agencies:** Sales tax is handled by Stripe and is not an expense line here.
*   **Refunded expense:** Reflected by the underlying expense record; the report shows the net recognized amount in the period.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and Year to Date (YTD).
*   AC-005: Filters affect all sections (six cards, chart, table).

### **8.3 Calculations**

*   AC-006: COGS = manual COGS + Pixally fee + Stripe fee + Contractor payments + Editor payments.
*   AC-007: Total Expenses = COGS + OPEX (no double-counting of contractor/editor).
*   AC-008: Contractor Payments card excludes Stripe fees and is a subset of COGS.
*   AC-009: A contractor payment with a Stripe fee is logged as two COGS line items (amount + fee).
*   AC-010: Editor payments are within COGS and not shown separately.
*   AC-011: Average Expense = Total Expenses ÷ Total Transactions.
*   AC-012: Total Transactions = count of expense line items.
*   AC-013: Expenses are recognized on the Transaction Date.

### **8.4 Export & Read-Only**

*   AC-014: Export generates an XLSX (Expense Details only; cards and chart excluded) named "Expenses\_Report\_\[Date\].xlsx".
*   AC-015: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Expense Management

OPEX and manual COGS entries

Report data incomplete

Internal Module

Contractors Module

Contractor payment data

COGS and Contractor card understated

Internal Module

Post-Production Module

Editor payment data

COGS understated

Internal Module

Payment Processing (Stripe/Pixally)

Platform fee data

COGS understated

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Expenses Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Expenses (Figma design reference)
*   Confirmed cost, fee, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Cash Ledger

# **Functional Requirements Document (FRD)**

## **Module: Reports – Cash Ledger**

**Document Version:** 1.2  
**Created Date:** January 07, 2026  
**Last Updated:** July 06, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Cash Ledger

### **Purpose**

The Cash Ledger report tracks all actual money movement — income received and expenses paid — over a selected period, giving agency owners a clear view of real cash flow.

### **Business Goals**

*   Show actual cash in and cash out for any selected period.
*   Provide a net cash-flow figure to gauge liquidity.
*   Give a chronological record of all completed transactions.

### **Report Sections**

*   **Cash Flow Summary** – Three metric cards: Total Income, Total Expenses, and Net Cash Flow.
*   **Income vs Expenses Chart** – Grouped bar chart comparing income and expenses over time.
*   **Transaction History** – A table of all completed transactions.

### **Cash & Tax Treatment**

*   This report is about **money movement, not performance**, so all figures are **tax-inclusive** (e.g., a $110 client payment that includes $10 tax is recorded as $110).
*   **Total Income** = total cash received in the period, **including** sales tax.
*   **Total Expenses** = total cash paid out in the period — contractor payments + COGS items + OPEX items (each cash-out transaction counted once).
*   **Net Cash Flow** = Total Income − Total Expenses.
*   **Transaction History** shows all transactions at their actual amounts, **including** sales tax.
*   **Date recognition:** transactions are recognized on the actual **Payment / Transaction Date**.

### **Report Behavior**

*   **Read-only:** No action buttons. All transaction entry and editing is handled in the Finance module.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All transaction entry and editing is handled in the Finance module.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Cash Ledger" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Cash Ledger," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays three cards: Total Income, Total Expenses, and Net Cash Flow.

3.7 The system displays the **Income vs Expenses** grouped bar chart (income in green, expenses in red) across the period.

3.8 The system displays the **Transaction History** table with columns: Date, Type (Income/Expense), Client, Project, and Amount.

3.9 The user sorts the table by a sortable column or paginates through records.

3.10 The user changes the Brand and/or Date filter.

*   The system recalculates all three cards, the chart, and the Transaction History table.

3.11 The user clicks "Export Report."

*   The system generates an **XLSX** export of the Transaction History (cards and chart excluded) and downloads it as "Cash\_Ledger\_\[Date\].xlsx".

3.12 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no data:** All three cards display "$0.00"; the chart renders with zero values; the table shows "No transactions recorded."
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters all data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   All three cards (Total Income, Total Expenses, Net Cash Flow)
*   The Income vs Expenses chart
*   The Transaction History table

### **4.4 Cash Flow Summary Logic**

**Total Income:**

*   Sum of all cash received in the period, **including** sales tax.

**Total Expenses:**

*   Sum of all cash paid out in the period — contractor payments + COGS items + OPEX items. Each cash-out transaction is counted once.

**Net Cash Flow:**

*   Total Income − Total Expenses. May be negative (displayed in red) when expenses exceed income.

### **4.5 Income vs Expenses Chart Logic**

*   Grouped bar chart per period bucket: an income bar (green) and an expense bar (red).
*   Amounts are tax-inclusive, consistent with the cards.
*   Updates with the applied filters.

### **4.6 Transaction History Logic**

*   Columns: Date, Type (Income or Expense), Client (transaction description/party), Project, Amount.
*   **Amount:** income shown as a positive value in green (e.g., "+$2,048.00"); expense shown as a negative value in red (e.g., "-$2,048.00"). Amounts are tax-inclusive.
*   Sortable columns include Date, Type, Client, Project, and Amount. Default sort: Date descending.
*   Pagination: 10 / 25 / 50 rows per page.

### **4.7 Export Logic**

*   "Export Report" generates an **XLSX** file containing the Transaction History.
*   Cards and chart are excluded (data only).
*   Filename format: "Cash\_Ledger\_\[Date\].xlsx". Export reflects applied filters.

### **4.8 Impact**

*   Changing filters recalculates all cards, the chart, and the table simultaneously.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Cash Flow Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Income

Currency

Cash received, incl. tax

"$X,XXX.XX"

Total Expenses

Currency

Cash paid out (contractor + COGS + OPEX)

"$X,XXX.XX"

Net Cash Flow

Currency

Income − Expenses

"$X,XXX.XX" (red if negative)

### **5.3 Transaction History Table**

**Column**

**Data Type**

**Description**

**Display Format**

Date

Date

Payment/transaction date

"MMM D, YYYY"

Type

Badge

Income or Expense

Text badge

Client

Text

Transaction party/description

Text

Project

Text

Associated project (if any)

Text or "-"

Amount

Currency

Transaction amount, incl. tax

"+$X" (green) / "-$X" (red)

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   Amounts are tax-inclusive throughout this report.
*   Net Cash Flow renders negatives distinctly (red).

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Only income, no expenses:** Total Expenses "$0.00"; Net Cash Flow equals Total Income; chart shows only green bars.
*   **Only expenses, no income:** Total Income "$0.00"; Net Cash Flow is negative (red); chart shows only red bars.
*   **Tax-inclusive amounts:** A $110 client payment (with $10 tax) records as +$110 income, unlike performance reports which exclude tax.
*   **Expense with no linked project:** Project column shows "-".
*   **Same-day income and expense:** Both appear as separate rows and net into Net Cash Flow.
*   **Refund transaction:** Recorded as a cash movement in the appropriate direction and reflected in the totals.
*   **Negative Net Cash Flow:** Displayed in red to signal cash burn.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Filters affect all sections (three cards, chart, table).

### **8.3 Calculations**

*   AC-006: Total Income is tax-inclusive.
*   AC-007: Total Expenses = contractor payments + COGS items + OPEX items (each counted once).
*   AC-008: Net Cash Flow = Total Income − Total Expenses and renders negatives in red.
*   AC-009: Transaction History shows amounts including tax, with income positive/green and expense negative/red.
*   AC-010: Transactions are recognized on the Payment/Transaction Date.

### **8.4 Export & Read-Only**

*   AC-011: Export generates an XLSX (Transaction History only; cards and chart excluded) named "Cash\_Ledger\_\[Date\].xlsx".
*   AC-012: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Payments Module

Cash-in (income) transactions

Income cannot be calculated

Internal Module

Expense Management

Cash-out (expense) transactions

Expenses cannot be calculated

Internal Module

Contractors Module

Contractor payment transactions

Expenses understated

Internal Module

Projects Module

Links transactions to projects

Project column unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Cash Ledger Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Cash Ledger (Figma design reference)
*   Confirmed cash, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Contractors

# **Functional Requirements Document (FRD)**

## **Module: Reports – Contractors**

**Document Version:** 1.2  
**Created Date:** January 07, 2026  
**Last Updated:** July 06, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Contractors

### **Purpose**

The Contractors report provides comprehensive tracking of contractor payments, showing what has been paid, what is due, and how many contractors are active.

### **Business Goals**

*   Show total contractor payments made in any selected period.
*   Surface upcoming contractor payments due.
*   Track the number of active contractors.

### **Report Sections**

*   **Metric Cards** – Total Paid, Upcoming Payments Due, and Active Contractors.
*   **Contractor Payments Chart** – Bar chart of contractor payments over time.
*   **Transaction History** – Paid and Unpaid contractor payment tables.

### **Amount & Fee Treatment**

*   All contractor amounts are shown **excluding the Stripe fee** (the fee the agency incurs to pay a contractor). For example, if paying a contractor $100 costs the agency $103, this report shows $100.
*   **Editor payments are not included** in this report; it tracks contractor payments only. (Editor payments appear within COGS in the Expenses and Profit & Loss reports.)
*   **Date recognition:** based on the payment / transaction date.

### **Report Behavior**

*   **Read-only:** No action buttons. All contractor payment actions are handled in Project Details or the Finance module.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. All contractor payment actions are handled in Project Details or the Finance module.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Contractors" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Contractors," the subtitle, the Brand filter, the Date filter, and an "Export Report" button.

3.6 The system displays three cards: Total Paid, Upcoming Payments Due (with an info tooltip), and Active Contractors.

3.7 The system displays the **Contractor Payments** bar chart across the period.

3.8 The system displays the **Transaction History** section with Paid (default) and Unpaid tabs.

3.9 The user switches between the Paid and Unpaid tabs.

3.10 The user sorts a table column or paginates through records.

3.11 The user changes the Brand and/or Date filter.

*   The system recalculates all three cards, the chart, and the Transaction History tables.

3.12 The user clicks "Export Report."

*   The system generates an **XLSX** export of the Paid and Unpaid history (cards and chart excluded) and downloads it as "Contractors\_Report\_\[Date\].xlsx".

3.13 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **New agency / no contractors:** Cards display "$0.00" / "0"; the chart renders with zero values; the tables show an empty-state message.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters affect **all report sections**:

*   All three cards (Total Paid, Upcoming Payments Due, Active Contractors)
*   The Contractor Payments chart
*   Both Transaction History tables (Paid and Unpaid)

### **4.4 Metric Card Logic**

All contractor amounts exclude the Stripe fee.

*   **Total Paid:** Total amount paid to contractors in the period (excluding Stripe fee).
*   **Upcoming Payments Due:** Total unpaid contractor fees due (excluding Stripe fee). For a purely past date range, displays "No upcoming payments in this date range."
*   **Active Contractors:** Count of active contractors, **excluding** contractors in "Setup Required" and "Pending" states.

### **4.5 No Overdue Concept**

*   There is no "Overdue" status for contractor payments. Past-due unpaid payments remain part of Upcoming Payments Due, and status badges show only "Paid" or "Unpaid."

### **4.6 Contractor Payments Chart Logic**

*   Bar chart of contractor payments across the selected period.
*   Amounts exclude the Stripe fee.
*   Updates with the applied filters.

### **4.7 Transaction History Logic**

**Paid tab (default):**

*   Displays paid contractor payments with the paid amount (excluding Stripe fee).

**Unpaid tab:**

*   Displays unpaid contractor payments due.

**Common:**

*   Columns are sortable. Default sort: Due Date descending.
*   Pagination: 10 / 25 / 50 rows per page.
*   **Read-only:** no Actions column; no Pay, Mark as Paid, or View Invoice actions in this report.

### **4.8 Export Logic**

*   "Export Report" generates an **XLSX** file containing the Paid and Unpaid contractor history.
*   Cards and chart are excluded (data only).
*   Filename format: "Contractors\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.9 Impact**

*   Changing filters recalculates all cards, the chart, and the tables simultaneously.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Metric Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Total Paid

Currency

Paid to contractors, excl. Stripe fee

"$X,XXX"

Upcoming Payments Due

Currency

Unpaid contractor fees, excl. Stripe fee

"$X,XXX" or "No upcoming payments in this date range"

Active Contractors

Integer

Active contractors (excl. Setup Required & Pending)

Whole number

### **5.3 Transaction History Tables**

**Element**

**Description**

Paid tab

Paid contractor payments with paid amount (excl. Stripe fee), status "Paid"

Unpaid tab

Unpaid contractor payments due, status "Unpaid"

Sorting

All columns sortable; default Due Date descending

Pagination

10 / 25 / 50 rows per page

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   All contractor amounts exclude the Stripe fee.
*   Status is limited to "Paid" or "Unpaid" (no "Overdue").

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Contractor payment with Stripe fee:** The report shows the contractor amount only (e.g., $100), not the $103 the agency actually paid.
*   **Editor payments:** Never appear in this report; they are tracked within COGS in the Expenses and Profit & Loss reports.
*   **Past-due unpaid payment:** Remains within Upcoming Payments Due; there is no "Overdue" status.
*   **Purely past date range:** Upcoming Payments Due shows "No upcoming payments in this date range."
*   **Setup Required / Pending contractors:** Excluded from the Active Contractors count.
*   **Contractor with only unpaid payments:** Appears in the Unpaid tab and contributes to Upcoming Payments Due, but not to Total Paid.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, Brand filter, Date filter, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Filters affect all sections (three cards, chart, both tables).

### **8.3 Calculations**

*   AC-006: All contractor amounts exclude the Stripe fee.
*   AC-007: Total Paid = amount paid to contractors in the period (excl. Stripe fee).
*   AC-008: Upcoming Payments Due = unpaid contractor fees (excl. Stripe fee); shows "No upcoming payments in this date range" for purely past ranges.
*   AC-009: Active Contractors excludes Setup Required and Pending contractors.
*   AC-010: Editor payments are not included in this report.
*   AC-011: Status is limited to "Paid" or "Unpaid" (no "Overdue").

### **8.4 Export & Read-Only**

*   AC-012: Export generates an XLSX (Paid and Unpaid history; cards and chart excluded) named "Contractors\_Report\_\[Date\].xlsx".
*   AC-013: No action buttons appear in the report.

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Contractors Module

Contractor records and states

Active count and history unavailable

Internal Module

Payments Module

Contractor payment data

Total Paid / Upcoming unavailable

Internal Module

Payment Processing (Stripe)

Fee data (to exclude)

Fee exclusion may be inaccurate

Internal Module

Projects Module

Links payments to projects

Project column unavailable

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

API

Contractors Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Contractors (Figma design reference)
*   Confirmed amount, fee, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access

Additional Info - Do Not Refer

### **Extra Logic Reference (Stakeholder Provided)**

Forward-Looking vs. Backward-Looking:

\- Total Paid = backward looking

\- Upcoming Payments Due = forward looking

\- Active Contractors = works in both directions

Date Range Logic for Upcoming Payments Due:

\- Future or overlapping range (This Month mid-month, This Quarter, Custom Aug–Dec):

→ Show sum of upcoming contractor payments in that period

\- Purely past range (Last Month, Last Year, custom ending before today):

→ Show "—" or "No upcoming payments in this date range"

Sales Tax

# **Functional Requirements Document (FRD)**

## **Module: Reports – Sales Tax**

**Document Version:** 1.2  
**Created Date:** January 07, 2026  
**Last Updated:** July 06, 2026  
**Status:** Updated

## **Table of Contents**

1.  [Module Overview](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#1-module-overview)
2.  [User Roles & Permissions](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#2-user-roles--permissions)
3.  [User Flow](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#3-user-flow)
4.  [Functional Logic](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#4-functional-logic)
5.  [Field Details & Validations](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#5-field-details--validations)
6.  [Error Message Handling](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#6-error-message-handling)
7.  [Edge Cases](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#7-edge-cases)
8.  [Acceptance Criteria](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#8-acceptance-criteria)
9.  [Dependencies](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#9-dependencies)
10.  [References](https://claude.ai/chat/8310643c-5cb9-4795-baff-b62585914433#10-references)

## **1\. Module Overview**

### **Module Name**

Reports – Sales Tax

### **Purpose**

The Sales Tax report shows the total sales tax collected over a selected period. It covers automatic tax (handled by Stripe) via quick-access links and manual tax entries tracked within the platform.

### **Business Goals**

*   Show manual sales tax collected for any selected period.
*   Provide quick access to Stripe's automatic tax reports.
*   Give an invoice-level view of manual tax entries for reconciliation.

### **Report Sections**

*   **Automatic Sales Tax Summary** – Quick-access links to Stripe Tax reports (informational; no calculated data in-app).
*   **Manual Sales Tax Summary** – Three metric cards: Manual Subtotal, Manual Sales Tax Collected, and Manual Invoiced Total.
*   **Manual Sales Tax Table** – Per-transaction breakdown of subtotal, manual tax, and total.

### **Amount & Tax Treatment**

*   **Manual Subtotal:** total invoice amount shown as revenue **excluding tax** (e.g., $100).
*   **Manual Sales Tax Collected:** total manual sales tax (e.g., $10).
*   **Manual Invoiced Total:** Manual Subtotal + Manual Sales Tax Collected (e.g., $110).
*   **Automatic tax:** When an agency uses Stripe automatic tax, tax is calculated and handled by Stripe based on customer location and applicable rates; those figures are accessed via Stripe, not calculated in-app.

### **Report Behavior**

*   **Read-only:** No action buttons. Tax settings are managed in the Settings module or the Stripe Dashboard.
*   **Export:** The report exports to **XLSX** only.

## **2\. User Roles & Permissions**

**Role**

**View Report**

**Apply Filters**

**Export Report**

**Access Level**

Owner

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Admin

✅ Yes

✅ Yes

✅ Yes

Full Access (Read-Only)

Manager

❌ No

❌ No

❌ No

No Access

Team Member

❌ No

❌ No

❌ No

No Access

**Note:** This report is read-only. Tax settings are managed in the Settings module or the Stripe Dashboard.

## **3\. User Flow**

3.1 The user navigates to the Reports module and clicks "Reports."

3.2 The system loads the Reports landing page.

3.3 The user locates the "Sales Tax" card and clicks "View >".

3.4 The system loads the report with default filters (All Brands, This Year).

3.5 The system displays the header with a back arrow, title "Sales Tax," the subtitle, and an "Export Report" button.

3.6 The system displays the **Automatic Sales Tax Summary** section with a Quick Access panel ("Learn More" and "Open Stripe Tax Reports" links) and an informational note about Stripe's automated collection.

3.7 The system displays the **Manual Sales Tax Summary** section with the Brand and Date filters and three cards: Manual Subtotal, Manual Sales Tax Collected, and Manual Invoiced Total.

3.8 The system displays the **Manual Sales Tax Table** with columns: Job/Transaction, Subtotal, Sales Tax (Manual Entry), and Total.

3.9 The user changes the Brand and/or Date filter.

*   The system recalculates the three Manual cards and the Manual Sales Tax Table. The Automatic Sales Tax Summary is informational and is not affected.

3.10 The user clicks "Export Report."

*   The system generates an **XLSX** export of the Manual summary and table (Automatic section excluded) and downloads it as "Sales\_Tax\_Report\_\[Date\].xlsx".

3.11 The user clicks the back arrow to return to the Reports landing page.

## **4\. Functional Logic**

### **4.1 Empty State**

*   **No manual tax entries:** All three Manual cards display "$0.00"; the table shows "No manual tax entries recorded."
*   **Agency uses only Stripe tax:** Manual cards show "$0.00"; the table shows "No manual tax entries. You're using automatic tax collection via Stripe." The Automatic section remains functional.
*   **Filters return no results:** "No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

### **4.2 Filters**

*   **Brand filter:** Default "All Brands"; single-brand selection filters manual tax data to that brand.
*   **Date filter:** Default "This Year." Presets plus Custom Range.

### **4.3 Filter Scope**

Filters (Brand and Date) affect the **Manual Sales Tax section only**:

*   The three Manual cards (Manual Subtotal, Manual Sales Tax Collected, Manual Invoiced Total)
*   The Manual Sales Tax Table

The Automatic Sales Tax Summary is informational (navigation links to Stripe) and is not affected by filters.

### **4.4 Automatic Sales Tax Summary Logic**

*   Displays a Quick Access panel with "Learn More" and "Open Stripe Tax Reports" links.
*   Includes an informational note: Stripe automatically calculates taxes based on customer location and applicable rates.
*   No tax amounts are calculated in-app for the automatic method; users retrieve them from the Stripe Dashboard.

### **4.5 Manual Sales Tax Summary Logic**

*   **Manual Subtotal:** Total invoice amount for manual-tax transactions, shown as revenue **excluding tax**.
*   **Manual Sales Tax Collected:** Total manual sales tax collected.
*   **Manual Invoiced Total:** Manual Subtotal + Manual Sales Tax Collected.

### **4.6 Manual Sales Tax Table Logic**

*   Columns: Job/Transaction, Subtotal, Sales Tax (Manual Entry), Total.
*   Per row, Total = Subtotal + Sales Tax (e.g., $2,048.00 + $160.00 = $2,208.00).
*   Sortable columns include Job/Transaction, Subtotal, Sales Tax, and Total.
*   Pagination: 10 / 25 / 50 rows per page.

### **4.7 Export Logic**

*   "Export Report" generates an **XLSX** file containing the Manual summary metrics and the Manual Sales Tax Table.
*   The Automatic section is excluded (Stripe data is accessed via the Stripe Dashboard).
*   Filename format: "Sales\_Tax\_Report\_\[Date\].xlsx". Export reflects applied filters.

### **4.8 Impact**

*   Changing filters recalculates the Manual cards and Manual Sales Tax Table simultaneously.
*   No data is written back; all changes are display-only.

## **5\. Field Details & Validations**

### **5.1 Filters**

**Field**

**Type**

**Default**

**Options / Notes**

Brand

Dropdown (single-select)

All Brands

All Brands + configured brands

Date Range

Date range picker

This Year

Presets + Custom Range

### **5.2 Manual Summary Cards**

**Card**

**Data Type**

**Description**

**Display Format**

Manual Subtotal

Currency

Invoice amount excl. tax

"$X,XXX.XX"

Manual Sales Tax Collected

Currency

Total manual tax

"$X,XXX.XX"

Manual Invoiced Total

Currency

Subtotal + Tax

"$X,XXX.XX"

### **5.3 Manual Sales Tax Table**

**Column**

**Data Type**

**Description**

**Display Format**

Job/Transaction

Text

Project/transaction name

Text

Subtotal

Currency

Amount excl. tax

"$X,XXX.XX"

Sales Tax (Manual Entry)

Currency

Manual tax for the row

"$X,XXX.XX"

Total

Currency

Subtotal + Sales Tax

"$X,XXX.XX"

### **5.4 Validation Rules**

*   Date pickers reject future dates and dates before agency creation.
*   Row Total must equal Subtotal + Sales Tax.
*   Manual Invoiced Total must equal Manual Subtotal + Manual Sales Tax Collected.

## **6\. Error Message Handling**

**Error Scenario**

**Error Message**

**Trigger**

**System Response**

Report Load Failure

"Unable to load report. Please try again."

Network/server error during load

Show error with retry option

Filter Application Failure

"Unable to apply filters. Please try again."

Server error processing filters

Revert to previous filter state

No Data for Filters

"No result found. No items match the selected filters. Try adjusting or reset your filter to see results."

Valid filters, no matching data

Display empty state

Invalid Date Selection

"Please select a valid date within the allowed range."

Future date or date before agency creation

Block selection and show message

Export Generation Failure

"Unable to generate report. Please try again."

XLSX generation fails

Display error toast

Stripe Link Unavailable

"Unable to open Stripe Tax Reports. Please try again."

Stripe navigation fails

Display error toast

Session Timeout

"Your session has expired. Please log in again."

Session expires

Redirect to login

## **7\. Edge Cases**

*   **Agency uses only Stripe automatic tax:** Manual cards show $0.00 and the table shows the automatic-collection message; the Automatic section remains available.
*   **Agency uses only manual tax:** Manual cards and table populate normally; the Automatic section is still shown as informational.
*   **Mixed manual and automatic:** Only manual entries appear in the Manual section; automatic figures are retrieved from Stripe.
*   **Row total mismatch:** Prevented by validation (Total must equal Subtotal + Sales Tax).
*   **No tax configured at all:** Manual section shows the empty state; the Automatic section still provides Stripe links.
*   **Zero tax on a transaction:** Subtotal shows the amount, Sales Tax shows $0.00, and Total equals the Subtotal.

## **8\. Acceptance Criteria**

### **8.1 Access & Navigation**

*   AC-001: Owner and Admin can access; Manager and Team Member cannot.
*   AC-002: Back arrow returns to the Reports landing page.
*   AC-003: Header shows title, subtitle, and Export Report button.

### **8.2 Filters**

*   AC-004: Default filters are All Brands and This Year.
*   AC-005: Brand and Date filters affect the Manual section (cards + table) only.
*   AC-006: The Automatic Sales Tax Summary is informational and is not affected by filters.

### **8.3 Calculations**

*   AC-007: Manual Subtotal is shown excluding tax.
*   AC-008: Manual Sales Tax Collected is the total manual tax.
*   AC-009: Manual Invoiced Total = Manual Subtotal + Manual Sales Tax Collected.
*   AC-010: Each table row Total = Subtotal + Sales Tax.

### **8.4 Export & Read-Only**

*   AC-011: Export generates an XLSX (Manual summary + table; Automatic section excluded) named "Sales\_Tax\_Report\_\[Date\].xlsx".
*   AC-012: No action buttons appear in the report (Stripe links are navigation only).

## **9\. Dependencies**

**Dependency Type**

**Name**

**Description**

**Impact if Unavailable**

Internal Module

Invoices Module

Manual tax entries and subtotals

Manual section unavailable

Internal Module

Payments Module

Payment data for manual tax

Manual figures inaccurate

Internal Module

Brands Module

Brand configuration for filtering

Brand filter non-functional

External Service

Stripe Tax

Automatic tax reports and links

Automatic section links fail

External Service

XLSX Generation Service

Generates Excel exports

Export will fail

Configuration

Settings Module

Tax configuration

Manual/automatic setup unavailable

API

Sales Tax Reporting API

Backend calculation and aggregation

Report will not load

## **10\. References**

*   Reports Module – Sales Tax (Figma design reference)
*   Confirmed amount, tax, and filter logic (client confirmation, July 2026)
*   Cross-report standards: read-only, XLSX export, standard empty-state message, Owner/Admin-only access