Revenue chart: readable values, week/month/year views, year boundaries, history paging (#516)

* feat(dashboard): make the revenue chart readable and navigable

The monthly revenue chart could only be read by hovering each bar, was
fixed to a single 12-month window, and gave no indication of where one
calendar year ended and the next began.

Bar totals are now printed above the bars, thinning out as bars get
denser so labels never collide. A granularity control switches between
week, month and year buckets, prev/next buttons page through history,
and years are separated by an alternating background band plus a year
row under the axis. The legend chips isolate or toggle series, so a
single stack category can be read on its own.

This needed month bucketing lifted out of the backend: revenue_from_
calendar now takes a pandas frequency, and a new revenue_series
reconciles invoice-derived and calendar-derived revenue server-side.
That replaces the frontend join of two RPC calls on a formatted "MM/YY"
display string, and lets the chart page against the real data extent.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(dashboard): polish revenue chart issues found in UI smoke

Three fixes from screenshotting the chart in every granularity:

- Sub-thousand bar labels showed a pointless decimal (€903.6) and
  crowded their neighbours; compact notation has no suffix to shorten
  below a thousand, so drop the fraction digits there.
- Year view shaded alternating bars, because every bucket is its own
  year there — skip the year banding entirely in that view.
- Cap bar width so the three-bar year view doesn't draw slabs, and
  don't repeat the year on both ends of a single-year window label.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: clstaudt

tuttle/app/dashboard/intent.py

@@ -6,6 +6,7 @@
     cash_flow_projection,
     monthly_revenue_from_calendar,
     revenue_curve_with_calendar,
+    revenue_series,
 )
 from ...kpi import (
     compute_kpis,
@@ -106,6 +107,26 @@ def get_monthly_chart_data(self, n_months: int = 12) -> IntentResult:
                 exception=e,
             )
 
+    def get_revenue_series(self, granularity: str = "month", offset: int = 0) -> IntentResult:
+        """Revenue per week/month/year bucket for one window of the revenue chart."""
+        try:
+            data = revenue_series(
+                self.query(Invoice),
+                self.query(Project),
+                self._time_data_source.get_data_frame(),
+                granularity=granularity,
+                offset=int(offset),
+                country=self._get_country(),
+            )
+            return IntentResult(was_intent_successful=True, data=data)
+        except Exception as e:
+            return IntentResult(
+                was_intent_successful=False,
+                error_msg=f"Failed to load revenue series: {e}",
+                log_message=f"DashboardIntent.get_revenue_series: {e}",
+                exception=e,
+            )
+
     def get_revenue_curve(self, forecast_months: int = 6) -> IntentResult:
         """Get combined historical + calendar-based + contract-fallback revenue curve."""
         try:

tuttle/forecasting.py

@@ -1,13 +1,16 @@
 """Revenue forecasting based on contracts, time allocation, and invoices."""
 
+import calendar
 import datetime
 from decimal import Decimal
 from typing import List, Optional
 
 import pandas
 from pandas import DataFrame
 
+from .fx import primary_currency
 from .model import Contract, Invoice, Project
+from .tax_reserves import convert_invoice
 from .time import TimeUnit
 from .timetracking import event_hours
 
@@ -159,19 +162,21 @@ def _invoiced_ranges_by_tag(invoices: List[Invoice]) -> dict:
     return ranges
 
 
-def monthly_revenue_from_calendar(
-    time_data: DataFrame,
+def revenue_from_calendar(
+    time_data: Optional[DataFrame],
     projects: List[Project],
     start_date: datetime.date,
     end_date: datetime.date,
     invoices: Optional[List[Invoice]] = None,
+    freq: str = "M",
 ) -> DataFrame:
-    """Derive monthly revenue from calendar time-tracking events.
+    """Derive revenue per time bucket from calendar time-tracking events.
 
     The calendar DataFrame is the source of truth for hours worked (past)
     and hours planned (future).  Filters *time_data* for events in
-    [start_date, end_date], groups by month and project tag, then converts
-    hours to revenue via contract rates.
+    [start_date, end_date], groups by *freq* period and project tag, then
+    converts hours to revenue via contract rates.  *freq* is a pandas
+    period alias — "W", "M" or "Y".
 
     If *invoices* is given, hours already captured in a timesheet attached
     to a (non-cancelled) invoice are excluded, keyed by the timesheet's own
@@ -180,18 +185,19 @@ def monthly_revenue_from_calendar(
     "planned" for the month it was done, and again as "invoiced" for the
     month the invoice was actually raised.
 
-    Returns a DataFrame with columns: month, project, revenue, contract_id, hours.
+    Returns a DataFrame with columns: period, project, revenue, contract_id, hours.
     """
+    empty = DataFrame(columns=["period", "project", "revenue", "contract_id", "hours"])
     if time_data is None or time_data.empty:
-        return DataFrame(columns=["month", "project", "revenue", "contract_id", "hours"])
+        return empty
 
     tag_to_project = {p.tag: p for p in projects if p.tag and p.contract}
 
     index_dates = time_data.index.date
     mask = (index_dates >= start_date) & (index_dates <= end_date)
     filtered = time_data[mask]
     if filtered.empty:
-        return DataFrame(columns=["month", "project", "revenue", "contract_id", "hours"])
+        return empty
 
     if invoices:
         invoiced_ranges = _invoiced_ranges_by_tag(invoices)
@@ -203,11 +209,11 @@ def monthly_revenue_from_calendar(
             ]
             filtered = filtered[[not v for v in already_invoiced]]
             if filtered.empty:
-                return DataFrame(columns=["month", "project", "revenue", "contract_id", "hours"])
+                return empty
 
     records = []
     df = filtered.copy()
-    df["_month"] = pandas.to_datetime(df.index).to_period("M").to_timestamp()
+    df["_period"] = pandas.to_datetime(df.index).to_period(freq).to_timestamp()
     df["_hours"] = df.apply(
         lambda row: event_hours(
             row,
@@ -216,7 +222,7 @@ def monthly_revenue_from_calendar(
         axis=1,
     )
 
-    grouped = df.groupby(["_month", "tag"]).agg(hours=("_hours", "sum")).reset_index()
+    grouped = df.groupby(["_period", "tag"]).agg(hours=("_hours", "sum")).reset_index()
     for _, row in grouped.iterrows():
         tag = row["tag"]
         project = tag_to_project.get(tag)
@@ -228,7 +234,7 @@ def monthly_revenue_from_calendar(
         revenue = float(Decimal(str(billable_units)) * contract.rate)
         records.append(
             {
-                "month": row["_month"],
+                "period": row["_period"],
                 "project": project.title,
                 "revenue": revenue,
                 "contract_id": contract.id,
@@ -237,10 +243,25 @@ def monthly_revenue_from_calendar(
         )
 
     if not records:
-        return DataFrame(columns=["month", "project", "revenue", "contract_id", "hours"])
+        return empty
     return DataFrame(records)
 
 
+def monthly_revenue_from_calendar(
+    time_data: Optional[DataFrame],
+    projects: List[Project],
+    start_date: datetime.date,
+    end_date: datetime.date,
+    invoices: Optional[List[Invoice]] = None,
+) -> DataFrame:
+    """Monthly view of :func:`revenue_from_calendar`, keyed by ``month``.
+
+    Returns a DataFrame with columns: month, project, revenue, contract_id, hours.
+    """
+    df = revenue_from_calendar(time_data, projects, start_date, end_date, invoices=invoices, freq="M")
+    return df.rename(columns={"period": "month"})
+
+
 def cash_flow_projection(
     revenue_forecast: DataFrame,
     contracts: List[Contract],
@@ -326,3 +347,166 @@ def revenue_curve_with_calendar(
     combined = combined.sort_values("month").reset_index(drop=True)
     combined["cumulative_revenue"] = combined["revenue"].cumsum()
     return combined
+
+
+# Bucket sizes per granularity: pandas period alias, buckets per window, and
+# how many of those buckets sit in the future when viewing the present.
+_GRANULARITY = {
+    "week": ("W", 13, 3),
+    "month": ("M", 16, 3),
+    "year": ("Y", 0, 0),
+}
+
+
+def revenue_window(
+    granularity: str,
+    offset: int = 0,
+    today: Optional[datetime.date] = None,
+) -> tuple:
+    """Start and end date of the visible window for a paged revenue chart.
+
+    *offset* pages the window: 0 is the window containing today, -1 the one
+    before it, and so on.  A month window spans 16 buckets and a week window
+    13, both reaching three buckets into the future at offset 0 so planned
+    work is visible.  Any 16 consecutive months contain a January, so the
+    month view always has a year boundary on screen.
+    """
+    today = today or datetime.date.today()
+    freq, size, ahead = _GRANULARITY[granularity]
+    if size == 0:
+        raise ValueError(f"{granularity} is not a paged granularity")
+
+    current = pandas.Period(today, freq=freq)
+    last = current + ahead + offset * size
+    first = last - (size - 1)
+    return first.start_time.date(), last.end_time.date()
+
+
+def _data_extent(
+    invoices: List[Invoice],
+    time_data: Optional[DataFrame],
+) -> tuple:
+    """Earliest and latest date covered by invoices or calendar events."""
+    dates = [inv.date for inv in invoices if not inv.cancelled and inv.date]
+    if time_data is not None and not time_data.empty:
+        dates.append(time_data.index.min().date())
+        dates.append(time_data.index.max().date())
+    if not dates:
+        return None, None
+    return min(dates), max(dates)
+
+
+def _bucket_label(start: datetime.date, granularity: str) -> str:
+    if granularity == "week":
+        return f"W{start.isocalendar()[1]:02d}"
+    if granularity == "year":
+        return str(start.year)
+    return calendar.month_abbr[start.month]
+
+
+def revenue_series(
+    invoices: List[Invoice],
+    projects: List[Project],
+    time_data: Optional[DataFrame],
+    granularity: str = "month",
+    offset: int = 0,
+    country: str = "",
+    today: Optional[datetime.date] = None,
+) -> dict:
+    """Received, invoiced and planned revenue per bucket for one chart window.
+
+    Reconciles the two revenue sources the dashboard chart needs into a
+    single series so the frontend does not have to join them: invoices give
+    ``received`` (paid) and ``invoiced`` (sent but unpaid) keyed by invoice
+    date, while the calendar gives ``planned`` — tracked or scheduled work
+    that no timesheet has billed yet, in the past as well as the future.
+
+    *granularity* is "week", "month" or "year".  Week and month windows are
+    paged with *offset*; the year window always spans the full data extent.
+    Empty buckets are included so the time axis stays continuous.
+    """
+    if granularity not in _GRANULARITY:
+        raise ValueError(f"unknown granularity: {granularity}")
+
+    today = today or datetime.date.today()
+    freq = _GRANULARITY[granularity][0]
+    currency = primary_currency(country)
+    extent_start, extent_end = _data_extent(invoices, time_data)
+
+    if granularity == "year":
+        first_year = min(extent_start.year if extent_start else today.year, today.year)
+        last_year = max(extent_end.year if extent_end else today.year, today.year)
+        window_start = datetime.date(first_year, 1, 1)
+        window_end = datetime.date(last_year, 12, 31)
+    else:
+        window_start, window_end = revenue_window(granularity, offset, today=today)
+
+    periods = pandas.period_range(start=window_start, end=window_end, freq=freq)
+    buckets = {
+        p: {
+            "bucket": p.start_time.date().isoformat(),
+            "bucket_end": p.end_time.date().isoformat(),
+            "label": _bucket_label(p.start_time.date(), granularity),
+            "year": p.start_time.year,
+            "received": 0.0,
+            "invoiced": 0.0,
+            "planned": 0.0,
+            "invoice_count": 0,
+            "hours": 0.0,
+        }
+        for p in periods
+    }
+
+    for inv in invoices:
+        if inv.cancelled or not inv.date:
+            continue
+        period = pandas.Period(inv.date, freq=freq)
+        bucket = buckets.get(period)
+        if bucket is None:
+            continue
+        converted = convert_invoice(inv, currency)
+        if converted is None:
+            continue
+        if inv.paid:
+            bucket["received"] += float(converted[0])
+            bucket["invoice_count"] += 1
+        elif inv.sent:
+            bucket["invoiced"] += float(converted[0])
+            bucket["invoice_count"] += 1
+
+    cal = revenue_from_calendar(time_data, projects, window_start, window_end, invoices=invoices, freq=freq)
+    if not cal.empty:
+        grouped = cal.groupby("period").agg(revenue=("revenue", "sum"), hours=("hours", "sum")).reset_index()
+        for _, row in grouped.iterrows():
+            bucket = buckets.get(pandas.Period(row["period"], freq=freq))
+            if bucket is None:
+                continue
+            bucket["planned"] += max(0.0, float(row["revenue"]))
+            bucket["hours"] += float(row["hours"])
+
+    current_period = pandas.Period(today, freq=freq)
+    rows = []
+    previous_year = None
+    for period in periods:
+        row = buckets[period]
+        row["is_current"] = period == current_period
+        row["is_future"] = period > current_period
+        row["is_year_start"] = previous_year is not None and row["year"] != previous_year
+        row["total"] = round(row["received"] + row["invoiced"] + row["planned"], 2)
+        for key in ("received", "invoiced", "planned", "hours"):
+            row[key] = round(row[key], 2)
+        previous_year = row["year"]
+        rows.append(row)
+
+    paged = granularity != "year"
+    return {
+        "granularity": granularity,
+        "offset": offset,
+        "currency": currency,
+        "window_start": window_start.isoformat(),
+        "window_end": window_end.isoformat(),
+        "buckets": rows,
+        "total": round(sum(r["total"] for r in rows), 2),
+        "has_earlier": bool(paged and extent_start and extent_start < window_start),
+        "has_later": bool(paged and offset < 0),
+    }