Skip to content
This repository was archived by the owner on Jun 19, 2026. It is now read-only.

feat: add weekly financial summary digest #1122

Open
Jorel97 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add weekly financial summary digest #1122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,17 @@ OpenAPI: `backend/app/openapi.yaml`
- Expenses: CRUD `/expenses`
- Bills: CRUD `/bills`, pay/mark `/bills/{id}/pay`
- Reminders: CRUD `/reminders`, trigger `/reminders/run`
- Insights: `/insights/monthly`, `/insights/budget-suggestion`
- Insights: `/insights/monthly`, `/insights/budget-suggestion`,
`/insights/weekly-summary?week_start=YYYY-MM-DD&currency=USD`

### Weekly Financial Summary

`GET /insights/weekly-summary` returns an authenticated smart digest for the
selected ISO week. It normalizes any `week_start` date to Monday, compares
expenses with the previous week, groups spending by category, returns seven
daily buckets, highlights the largest expenses, includes bills due that week,
and emits deterministic insights plus recommendations. Omit `week_start` for
the current week and omit `currency` to include all currencies.

## MVP UI/UX Plan
- Auth screens: register/login.
Expand Down
44 changes: 43 additions & 1 deletion app/src/__tests__/Analytics.integration.test.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,10 @@ jest.mock('@/hooks/use-toast', () => ({
}));

const getBudgetSuggestionMock = jest.fn();
const getWeeklySummaryMock = jest.fn();
jest.mock('@/api/insights', () => ({
getBudgetSuggestion: (...args: unknown[]) => getBudgetSuggestionMock(...args),
getWeeklySummary: (...args: unknown[]) => getWeeklySummaryMock(...args),
}));

describe('Analytics integration', () => {
Expand All @@ -52,13 +54,50 @@ describe('Analytics integration', () => {
method: 'heuristic',
warnings: [],
});
getWeeklySummaryMock.mockResolvedValue({
period: {
week_start: '2026-05-25',
week_end: '2026-05-31',
previous_week_start: '2026-05-18',
previous_week_end: '2026-05-24',
},
currency: 'USD',
summary: {
income: 800,
expenses: 200,
net_flow: 600,
transaction_count: 3,
expense_count: 2,
income_count: 1,
average_daily_expense: 28.57,
},
comparison: {
previous_expenses: 50,
expense_delta: 150,
expense_delta_pct: 300,
expense_trend: 'up',
},
category_breakdown: [
{ category_id: 1, category_name: 'Dining', amount: 120, share_pct: 60 },
],
daily_breakdown: [
{ date: '2026-05-25', income: 800, expenses: 0, net_flow: 800 },
],
top_expenses: [],
upcoming_bills: [],
insights: ['Dining was the largest spending category.'],
recommendations: ['Set a temporary cap for Dining next week.'],
method: 'deterministic',
});
});

it('loads and renders insights data', async () => {
render(<Analytics />);
await waitFor(() => expect(getBudgetSuggestionMock).toHaveBeenCalled());
expect(screen.getByText(/live spending analytics/i)).toBeInTheDocument();
expect(screen.getByText(/suggested budget/i)).toBeInTheDocument();
expect(await screen.findByText(/suggested budget/i)).toBeInTheDocument();
expect(screen.getByText(/weekly digest/i)).toBeInTheDocument();
expect(screen.getByText(/dining was the largest spending category/i)).toBeInTheDocument();
expect(screen.getByText(/tip a/i)).toBeInTheDocument();
});

Expand All @@ -68,6 +107,8 @@ describe('Analytics integration', () => {

await userEvent.clear(screen.getByLabelText(/analytics month/i));
await userEvent.type(screen.getByLabelText(/analytics month/i), '2026-01');
await userEvent.clear(screen.getByLabelText(/analytics week/i));
await userEvent.type(screen.getByLabelText(/analytics week/i), '2026-01-05');
await userEvent.selectOptions(screen.getByLabelText(/analytics persona/i), 'Debt-focused planner');
await userEvent.type(screen.getByLabelText(/gemini api key/i), 'abc123');
await userEvent.click(screen.getByRole('button', { name: /refresh insights/i }));
Expand All @@ -81,5 +122,6 @@ describe('Analytics integration', () => {
}),
),
);
expect(getWeeklySummaryMock).toHaveBeenLastCalledWith({ weekStart: '2026-01-05' });
});
});
67 changes: 67 additions & 0 deletions app/src/api/insights.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,62 @@ export type BudgetSuggestion = {
net_flow?: number;
};

export type WeeklySummary = {
period: {
week_start: string;
week_end: string;
previous_week_start: string;
previous_week_end: string;
};
currency: string;
summary: {
income: number;
expenses: number;
net_flow: number;
transaction_count: number;
expense_count: number;
income_count: number;
average_daily_expense: number;
};
comparison: {
previous_expenses: number;
expense_delta: number;
expense_delta_pct: number | null;
expense_trend: 'up' | 'down' | 'flat' | string;
};
category_breakdown: Array<{
category_id: number | null;
category_name: string;
amount: number;
share_pct: number;
}>;
daily_breakdown: Array<{
date: string;
income: number;
expenses: number;
net_flow: number;
}>;
top_expenses: Array<{
id: number;
description: string;
amount: number;
currency: string;
date: string;
category_id: number | null;
}>;
upcoming_bills: Array<{
id: number;
name: string;
amount: number;
currency: string;
next_due_date: string;
cadence: string;
}>;
insights: string[];
recommendations: string[];
method: 'deterministic' | string;
};

export async function getBudgetSuggestion(params?: {
month?: string;
geminiApiKey?: string;
Expand All @@ -32,3 +88,14 @@ export async function getBudgetSuggestion(params?: {
if (params?.persona) headers['X-Insight-Persona'] = params.persona;
return api<BudgetSuggestion>(`/insights/budget-suggestion${monthQuery}`, { headers });
}

export async function getWeeklySummary(params?: {
weekStart?: string;
currency?: string;
}): Promise<WeeklySummary> {
const search = new URLSearchParams();
if (params?.weekStart) search.set('week_start', params.weekStart);
if (params?.currency) search.set('currency', params.currency);
const query = search.toString();
return api<WeeklySummary>(`/insights/weekly-summary${query ? `?${query}` : ''}`);
}
141 changes: 133 additions & 8 deletions app/src/pages/Analytics.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,12 @@ import {
FinancialCardTitle,
} from '@/components/ui/financial-card';
import { useToast } from '@/hooks/use-toast';
import { getBudgetSuggestion, type BudgetSuggestion } from '@/api/insights';
import {
getBudgetSuggestion,
getWeeklySummary,
type BudgetSuggestion,
type WeeklySummary,
} from '@/api/insights';
import { formatMoney } from '@/lib/currency';

const PERSONAS = [
Expand All @@ -22,22 +27,28 @@ const PERSONAS = [
export function Analytics() {
const { toast } = useToast();
const [month, setMonth] = useState(() => new Date().toISOString().slice(0, 7));
const [weekStart, setWeekStart] = useState(() => new Date().toISOString().slice(0, 10));
const [persona, setPersona] = useState(PERSONAS[0]);
const [geminiKey, setGeminiKey] = useState('');
const [loading, setLoading] = useState(true);
const [data, setData] = useState<BudgetSuggestion | null>(null);
const [weeklyData, setWeeklyData] = useState<WeeklySummary | null>(null);
const [error, setError] = useState<string | null>(null);

async function load() {
setLoading(true);
setError(null);
try {
const payload = await getBudgetSuggestion({
month,
persona,
geminiApiKey: geminiKey.trim() || undefined,
});
setData(payload);
const [budgetPayload, weeklyPayload] = await Promise.all([
getBudgetSuggestion({
month,
persona,
geminiApiKey: geminiKey.trim() || undefined,
}),
getWeeklySummary({ weekStart }),
]);
setData(budgetPayload);
setWeeklyData(weeklyPayload);
} catch (err: unknown) {
const message = err instanceof Error ? err.message : 'Failed to load insights';
setError(message);
Expand All @@ -61,6 +72,10 @@ export function Analytics() {
];
}, [data]);

const trendLabel = weeklyData?.comparison.expense_delta_pct == null
? 'New baseline'
: `${weeklyData.comparison.expense_delta_pct.toFixed(2)}%`;

return (
<div className="page-wrap space-y-6">
<div className="page-header">
Expand All @@ -71,7 +86,7 @@ export function Analytics() {
Live spending analytics with Gemini-powered budget coaching.
</p>
</div>
<div className="grid gap-2 md:grid-cols-4">
<div className="grid gap-2 md:grid-cols-5">
<div>
<Label htmlFor="analytics-month">Month</Label>
<Input
Expand All @@ -82,6 +97,16 @@ export function Analytics() {
onChange={(e) => setMonth(e.target.value)}
/>
</div>
<div>
<Label htmlFor="analytics-week">Week</Label>
<Input
id="analytics-week"
aria-label="analytics week"
type="date"
value={weekStart}
onChange={(e) => setWeekStart(e.target.value)}
/>
</div>
<div>
<Label htmlFor="analytics-persona">Persona</Label>
<select
Expand Down Expand Up @@ -170,6 +195,106 @@ export function Analytics() {
</FinancialCardContent>
</FinancialCard>

{weeklyData ? (
<FinancialCard variant="financial">
<FinancialCardHeader>
<FinancialCardTitle>Weekly Digest</FinancialCardTitle>
<FinancialCardDescription>
{weeklyData.period.week_start} to {weeklyData.period.week_end}
</FinancialCardDescription>
</FinancialCardHeader>
<FinancialCardContent>
<div className="grid gap-3 md:grid-cols-4">
<div className="rounded-lg border p-3">
<div className="text-sm text-muted-foreground">Income</div>
<div className="font-semibold">
{formatMoney(weeklyData.summary.income, weeklyData.currency)}
</div>
</div>
<div className="rounded-lg border p-3">
<div className="text-sm text-muted-foreground">Expenses</div>
<div className="font-semibold">
{formatMoney(weeklyData.summary.expenses, weeklyData.currency)}
</div>
</div>
<div className="rounded-lg border p-3">
<div className="text-sm text-muted-foreground">Net Flow</div>
<div className="font-semibold">
{formatMoney(weeklyData.summary.net_flow, weeklyData.currency)}
</div>
</div>
<div className="rounded-lg border p-3">
<div className="text-sm text-muted-foreground">WoW Change</div>
<div className="font-semibold">{trendLabel}</div>
</div>
</div>

<div className="mt-5 grid gap-5 lg:grid-cols-2">
<div>
<h4 className="mb-3 font-semibold">Top Categories</h4>
{weeklyData.category_breakdown.length ? (
<div className="space-y-3">
{weeklyData.category_breakdown.slice(0, 5).map((category) => (
<div key={category.category_id ?? category.category_name}>
<div className="mb-1 flex items-center justify-between text-sm">
<span>{category.category_name}</span>
<span>
{formatMoney(category.amount, weeklyData.currency)} -{' '}
{category.share_pct.toFixed(1)}%
</span>
</div>
<div className="h-2 rounded-full bg-muted">
<div
className="h-2 rounded-full bg-primary"
style={{ width: `${Math.min(category.share_pct, 100)}%` }}
/>
</div>
</div>
))}
</div>
) : (
<div className="text-sm text-muted-foreground">No category spend this week.</div>
)}
</div>

<div>
<h4 className="mb-3 font-semibold">Daily Flow</h4>
<div className="space-y-2">
{weeklyData.daily_breakdown.map((day) => (
<div
key={day.date}
className="flex items-center justify-between rounded-lg border px-3 py-2 text-sm"
>
<span>{day.date}</span>
<span>{formatMoney(day.net_flow, weeklyData.currency)}</span>
</div>
))}
</div>
</div>
</div>

<div className="mt-5 grid gap-5 lg:grid-cols-2">
<div>
<h4 className="mb-3 font-semibold">Insights</h4>
<ul className="list-disc pl-5 space-y-1 text-sm">
{weeklyData.insights.map((insight) => (
<li key={insight}>{insight}</li>
))}
</ul>
</div>
<div>
<h4 className="mb-3 font-semibold">Recommendations</h4>
<ul className="list-disc pl-5 space-y-1 text-sm">
{weeklyData.recommendations.map((recommendation) => (
<li key={recommendation}>{recommendation}</li>
))}
</ul>
</div>
</div>
</FinancialCardContent>
</FinancialCard>
) : null}

<FinancialCard variant="financial">
<FinancialCardHeader>
<FinancialCardTitle>Coach Tips</FinancialCardTitle>
Expand Down
Loading