Dashboard Refactor: Flow-based Metrics + Unified Data Model (#4)

# Dashboard Refactor: Flow-based Metrics + Unified Data Model

## Summary

This MR transforms the dashboard into a **flow-driven, backend-powered analytics system** with a significantly cleaner architecture and improved UX.

## Overview

This MR introduces a **major refactor of the dashboard and report data model**, transitioning from separate `expense/income` handling to a unified **flow-based (`outflows` / `inflows`) system** backed by a single `metric` structure.

It simplifies data handling, improves UI consistency, and enables better extensibility for future analytics.

---

## Key Changes

### 1. Data Model Simplification

* Replaced:

  * `expenses` / `incomes`
* With:

  * `metric`

```ts
ReportPeriod {
  start: string;
  end: string;
  metric: {
    sum: number;
    count: number;
    transactions: Transaction[];
  }
}
```

* Eliminates duplication across logic paths
* Flow is now controlled at query level instead of data shape

---

### 2. Flow-based System (Core Change)

* Introduced:

  ```ts
  type DashboardFlow = "outflows" | "inflows";
  ```

* Replaced all references of:

  * `expense` → `outflows`
  * `income` → `inflows`

* Flow is now:

  * Controlled at **Dashboard level**
  * Propagated to **API query (`useReport`)**

---

### 3. API Changes

#### `useReport`

* Removed legacy params:

  * `group_by`, `rolling`, `include_transactions`, etc.

* New structure:

```ts
useReport({
  periods: ["daily", "weekly", "monthly", "all"],
  flow,
  payee,
  tags
})
```

* Backend now handles:

  * Flow filtering
  * Aggregation

---

### 4. Period System Update

* Removed:

  * yearly, fyly, full

* Added:

  * `daily`
  * `all`

```ts
type PeriodType = "daily" | "weekly" | "monthly" | "all";
```

* Updated helpers:

  * `periodIdToKey`
  * `buildPeriodId`
  * `buildLabel`

---

### 5. React Query UX Improvement

* Added:

```ts
placeholderData: keepPreviousData
```

* Prevents UI flicker on filter/flow changes
* Enables smooth transitions

---

### 6. Dashboard State Refactor

#### Before

```ts
mode: "expense" | "income"
```

#### After

```ts
flow: "outflows" | "inflows"
```

* Introduced `onFlowChange` callback
* Lifted flow state to parent (`Dashboard.tsx`)
* Flow change triggers API refetch

---

### 7. UI Improvements

#### Flow Toggle

* Replaced mode toggle with:

  * Outflows / Inflows switch

#### Loading State Handling

* Added `isFetching` across components
* UI behavior during fetch:

  * Reduced opacity
  * Disabled interactions

#### Drill-down UX

* Added:

  * "Clear Drill-down" button

---

### 8. New Components

#### TopPayees

* New analytics card

* Shows top payees based on:

  * Selected period
  * Drill-down filters

* Supports:

  * Click-to-filter (drill-down)

---

### 9. Adapter Layer Simplification

#### Removed mode branching everywhere

Examples:

* `getAmount(period)` now uses:

  ```ts
  period.metric.sum
  ```

* `LatestItems`, `TopTags`, `HistoryChart`:

  * No longer split logic by expense/income
  * Work on unified transaction stream

---

### 10. GroupKey Generalization

#### Before

```ts
{
  payee?: string[];
  tags?: string[];
}
```

#### After

```ts
{
  [dimension: string]: string[];
}
```

* Enables future dimensions without refactor

---

## Behavioral Changes

* Flow selection now **controls backend query**
* All components consume **filtered data only**
* No client-side filtering for expense/income

---

## Benefits

* Single source of truth (`metric`)
* Cleaner adapters (no branching explosion)
* Easier feature additions (new dimensions, filters)
* Better UX (no flicker, smoother transitions)
* Backend-driven correctness

---

## Migration Notes

* Replace all `mode` usages with `flow`
* Update adapters to use `metric`
* Remove assumptions about:

  * `expenses`
  * `incomes`
* Ensure API supports:

  * `flow`
  * new period types

---

## Future Scope

* Add more dimensions (account, category hierarchy)
* Multi-flow comparison (inflows vs outflows together)
* Snapshot-based caching (already partially supported)

---

## Testing Notes

Verify:

* Flow toggle updates API calls
* No UI flicker on filter change
* Drill-down works across:

  * tags
  * payees
* Daily / Weekly / Monthly / All tabs behave correctly
* Loading state disables interaction properly

---

Reviewed-on: #4
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

src/Dashboard.tsx

@@ -11,6 +11,7 @@ import {
 } from "@mui/material";
 
 import ConfigurableDashboard from "./components/Dashboard";
+import { DashboardState } from "./components/Dashboard";
 import { configuration } from "./dashboard-config";
 import {
   useReport,
@@ -18,6 +19,8 @@ import {
 } from "./features/report";
 
 export default function Dashboard() {
+  const [flow, setFlow] = React.useState<"outflows" | "inflows">("outflows");
+
   const [appliedPayees, setAppliedPayees] = React.useState<string[]>([]);
   const [appliedTags, setAppliedTags] = React.useState<string[]>([]);
 
@@ -28,10 +31,8 @@ export default function Dashboard() {
   const [loadedTags, setLoadedTags] = React.useState<string[]>([]);
 
   const report = useReport({
-    periods: ["weekly", "monthly", "full"],
-    rolling: true,
-    include_transactions: true,
-    group_by: ["tags"],
+    periods: ["daily", "weekly", "monthly", "all"],
+    flow: flow,
     payee: appliedPayees.length > 0 ? appliedPayees : undefined,
     tags: appliedTags.length > 0 ? appliedTags : undefined,
   });
@@ -43,10 +44,7 @@ export default function Dashboard() {
         report.data.data.buckets.forEach((b: any) => {
           Object.values(b.periods).forEach((periodArray: any) => {
             periodArray?.forEach((p: any) => {
-              p.expenses?.transactions?.forEach((t: any) => {
-                if (t.payee?.name) pSet.add(t.payee.name);
-              });
-              p.incomes?.transactions?.forEach((t: any) => {
+              p.metric?.transactions?.forEach((t: any) => {
                 if (t.payee?.name) pSet.add(t.payee.name);
               });
             });
@@ -60,10 +58,7 @@ export default function Dashboard() {
         report.data.data.buckets.forEach((b: any) => {
           Object.values(b.periods).forEach((periodArray: any) => {
             periodArray?.forEach((p: any) => {
-              p.expenses?.transactions?.forEach((t: any) => {
-                t.tags?.forEach((tag: any) => tSet.add(tag.name || tag));
-              });
-              p.incomes?.transactions?.forEach((t: any) => {
+              p.metric?.transactions?.forEach((t: any) => {
                 t.tags?.forEach((tag: any) => tSet.add(tag.name || tag));
               });
             });
@@ -77,6 +72,10 @@ export default function Dashboard() {
   const isLoading = report.isLoading;
   const error = report.error;
 
+  /** Callback for the ConfigurableDashboard's flow toggle */
+  const handleFlowChange = React.useCallback((newState: DashboardState) => {
+    setFlow(newState.flow);
+  }, []);
 
   if (isLoading && !report.data) {
     return (
@@ -152,7 +151,7 @@ export default function Dashboard() {
               setAppliedTags(tagsInput);
             }}
             disabled={isLoading}
-            sx={{ height: 40, borderRadius: 2 }} // Changed from 56 to 40 to match minHeight of inputs
+            sx={{ height: 40, borderRadius: 2 }}
           >
             Apply
           </Button>
@@ -161,6 +160,8 @@ export default function Dashboard() {
       <ConfigurableDashboard
         config={configuration}
         data={data}
+        isFetching={report.isFetching}
+        onFlowChange={handleFlowChange}
       />
     </Box>
   );