Initial public release

Aurum — a self-hosted personal finance operating system: cash flow,
net worth tracking, budgets, goals, recurring payments, reports,
proactive alerts, and a compound-interest returns calculator, all
bilingual (RU/EN) and mobile-first. Ships as a three-container Docker
Compose stack (Postgres + FastAPI + nginx-served React frontend).

See README.md for setup and CONTRIBUTING.md for development.

frontend/src/hooks/useAccounts.ts

@@ -0,0 +1,46 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createAccount, deleteAccount, fetchAccounts, updateAccount } from "@/api/accounts";
+import type { AccountInput } from "@/types";
+
+export function useAccounts(includeArchived = false) {
+  return useQuery({ queryKey: ["accounts", includeArchived], queryFn: () => fetchAccounts(includeArchived) });
+}
+
+export function useCreateAccount() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (input: AccountInput) => createAccount(input),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["accounts"] }),
+  });
+}
+
+export function useUpdateAccount() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: Partial<AccountInput> & { is_archived?: boolean } }) =>
+      updateAccount(id, input),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["accounts"] }),
+  });
+}
+
+export function useDeleteAccount() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (id: number) => deleteAccount(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["accounts"] });
+      // A cascade-deleted account takes its transaction history with it —
+      // refresh everything derived from transactions, same set posting a
+      // recurring transaction invalidates.
+      queryClient.invalidateQueries({ queryKey: ["transactions"] });
+      queryClient.invalidateQueries({ queryKey: ["dashboard-summary"] });
+      queryClient.invalidateQueries({ queryKey: ["net-worth-summary"] });
+      queryClient.invalidateQueries({ queryKey: ["category-spending-report"] });
+      queryClient.invalidateQueries({ queryKey: ["category-ranking"] });
+      queryClient.invalidateQueries({ queryKey: ["budget-status"] });
+      queryClient.invalidateQueries({ queryKey: ["financial-alerts"] });
+      queryClient.invalidateQueries({ queryKey: ["advice"] });
+      queryClient.invalidateQueries({ queryKey: ["cash-flow"] });
+    },
+  });
+}

frontend/src/hooks/useAdvice.ts

@@ -0,0 +1,6 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchAdvice } from "@/api/advice";
+
+export function useAdvice() {
+  return useQuery({ queryKey: ["advice"], queryFn: fetchAdvice });
+}

frontend/src/hooks/useAssets.ts

@@ -0,0 +1,47 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { addAssetValuation, createAsset, deleteAsset, fetchAssets, updateAsset } from "@/api/assets";
+import type { AssetInput, AssetUpdateInput, AssetValuationInput } from "@/types";
+
+function useInvalidateNetWorth() {
+  const queryClient = useQueryClient();
+  return () => {
+    queryClient.invalidateQueries({ queryKey: ["assets"] });
+    queryClient.invalidateQueries({ queryKey: ["net-worth-summary"] });
+  };
+}
+
+export function useAssets() {
+  return useQuery({ queryKey: ["assets"], queryFn: fetchAssets });
+}
+
+export function useCreateAsset() {
+  const invalidate = useInvalidateNetWorth();
+  return useMutation({
+    mutationFn: (input: AssetInput) => createAsset(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateAsset() {
+  const invalidate = useInvalidateNetWorth();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: AssetUpdateInput }) => updateAsset(id, input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useAddAssetValuation() {
+  const invalidate = useInvalidateNetWorth();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: AssetValuationInput }) => addAssetValuation(id, input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteAsset() {
+  const invalidate = useInvalidateNetWorth();
+  return useMutation({
+    mutationFn: (id: number) => deleteAsset(id),
+    onSuccess: invalidate,
+  });
+}

frontend/src/hooks/useBudgets.ts

@@ -0,0 +1,44 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createBudget, deleteBudget, fetchBudgetStatus, fetchBudgets, updateBudget } from "@/api/budgets";
+import type { BudgetInput } from "@/types";
+
+function useInvalidateBudgets() {
+  const queryClient = useQueryClient();
+  return () => {
+    queryClient.invalidateQueries({ queryKey: ["budgets"] });
+    queryClient.invalidateQueries({ queryKey: ["budget-status"] });
+    queryClient.invalidateQueries({ queryKey: ["financial-alerts"] });
+  };
+}
+
+export function useBudgets() {
+  return useQuery({ queryKey: ["budgets"], queryFn: fetchBudgets });
+}
+
+export function useBudgetStatus(year: number, month: number) {
+  return useQuery({ queryKey: ["budget-status", year, month], queryFn: () => fetchBudgetStatus(year, month) });
+}
+
+export function useCreateBudget() {
+  const invalidate = useInvalidateBudgets();
+  return useMutation({
+    mutationFn: (input: BudgetInput) => createBudget(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateBudget() {
+  const invalidate = useInvalidateBudgets();
+  return useMutation({
+    mutationFn: ({ id, monthlyLimit }: { id: number; monthlyLimit: string }) => updateBudget(id, monthlyLimit),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteBudget() {
+  const invalidate = useInvalidateBudgets();
+  return useMutation({
+    mutationFn: (id: number) => deleteBudget(id),
+    onSuccess: invalidate,
+  });
+}

frontend/src/hooks/useCashFlow.ts

@@ -0,0 +1,9 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchCashFlow } from "@/api/cashFlow";
+
+export function useCashFlow(startDate?: string, endDate?: string) {
+  return useQuery({
+    queryKey: ["cash-flow", startDate, endDate],
+    queryFn: () => fetchCashFlow(startDate, endDate),
+  });
+}

frontend/src/hooks/useCategories.ts

@@ -0,0 +1,6 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchCategories } from "@/api/categories";
+
+export function useCategories() {
+  return useQuery({ queryKey: ["categories"], queryFn: fetchCategories });
+}

frontend/src/hooks/useDashboard.ts

@@ -0,0 +1,9 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchDashboardSummary } from "@/api/dashboard";
+
+export function useDashboardSummary(year: number, month: number) {
+  return useQuery({
+    queryKey: ["dashboard-summary", year, month],
+    queryFn: () => fetchDashboardSummary(year, month),
+  });
+}

frontend/src/hooks/useGoals.ts

@@ -0,0 +1,44 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { addGoalContribution, createGoal, deleteGoal, fetchGoals, updateGoal } from "@/api/goals";
+import type { GoalContributionInput, GoalInput } from "@/types";
+
+function useInvalidateGoals() {
+  const queryClient = useQueryClient();
+  return () => queryClient.invalidateQueries({ queryKey: ["goals"] });
+}
+
+export function useGoals() {
+  return useQuery({ queryKey: ["goals"], queryFn: fetchGoals });
+}
+
+export function useCreateGoal() {
+  const invalidate = useInvalidateGoals();
+  return useMutation({
+    mutationFn: (input: GoalInput) => createGoal(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateGoal() {
+  const invalidate = useInvalidateGoals();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: Partial<GoalInput> }) => updateGoal(id, input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteGoal() {
+  const invalidate = useInvalidateGoals();
+  return useMutation({
+    mutationFn: (id: number) => deleteGoal(id),
+    onSuccess: invalidate,
+  });
+}
+
+export function useAddGoalContribution() {
+  const invalidate = useInvalidateGoals();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: GoalContributionInput }) => addGoalContribution(id, input),
+    onSuccess: invalidate,
+  });
+}

frontend/src/hooks/useInsights.ts

@@ -0,0 +1,9 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchFinancialAlerts } from "@/api/insights";
+
+export function useFinancialAlerts() {
+  return useQuery({
+    queryKey: ["financial-alerts"],
+    queryFn: fetchFinancialAlerts,
+  });
+}

frontend/src/hooks/useLocalStorageState.ts

@@ -0,0 +1,15 @@
+import { useState } from "react";
+
+export function useLocalStorageState(key: string, initial: boolean) {
+  const [value, setValue] = useState<boolean>(() => {
+    const stored = localStorage.getItem(key);
+    return stored === null ? initial : stored === "true";
+  });
+
+  const update = (next: boolean) => {
+    setValue(next);
+    localStorage.setItem(key, String(next));
+  };
+
+  return [value, update] as const;
+}

frontend/src/hooks/useNetWorth.ts

@@ -0,0 +1,10 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchNetWorthSummary } from "@/api/netWorth";
+import type { NetWorthRange } from "@/types";
+
+export function useNetWorthSummary(range: NetWorthRange) {
+  return useQuery({
+    queryKey: ["net-worth-summary", range],
+    queryFn: () => fetchNetWorthSummary(range),
+  });
+}

frontend/src/hooks/useRecurring.ts

@@ -0,0 +1,65 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  createRecurring,
+  deleteRecurring,
+  fetchRecurring,
+  postRecurring,
+  updateRecurring,
+} from "@/api/recurring";
+import type { RecurringTransactionInput } from "@/types";
+
+function useInvalidateRecurring() {
+  const queryClient = useQueryClient();
+  return (alsoInvalidateTransactions: boolean) => {
+    queryClient.invalidateQueries({ queryKey: ["recurring"] });
+    if (alsoInvalidateTransactions) {
+      // Posting creates a real Transaction — refresh everything derived from it.
+      queryClient.invalidateQueries({ queryKey: ["transactions"] });
+      queryClient.invalidateQueries({ queryKey: ["dashboard-summary"] });
+      queryClient.invalidateQueries({ queryKey: ["net-worth-summary"] });
+      queryClient.invalidateQueries({ queryKey: ["category-spending-report"] });
+      queryClient.invalidateQueries({ queryKey: ["category-ranking"] });
+      queryClient.invalidateQueries({ queryKey: ["budget-status"] });
+      queryClient.invalidateQueries({ queryKey: ["financial-alerts"] });
+      queryClient.invalidateQueries({ queryKey: ["advice"] });
+      queryClient.invalidateQueries({ queryKey: ["cash-flow"] });
+    }
+  };
+}
+
+export function useRecurring() {
+  return useQuery({ queryKey: ["recurring"], queryFn: fetchRecurring });
+}
+
+export function useCreateRecurring() {
+  const invalidate = useInvalidateRecurring();
+  return useMutation({
+    mutationFn: (input: RecurringTransactionInput) => createRecurring(input),
+    onSuccess: () => invalidate(false),
+  });
+}
+
+export function useUpdateRecurring() {
+  const invalidate = useInvalidateRecurring();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: Partial<RecurringTransactionInput> }) =>
+      updateRecurring(id, input),
+    onSuccess: () => invalidate(false),
+  });
+}
+
+export function useDeleteRecurring() {
+  const invalidate = useInvalidateRecurring();
+  return useMutation({
+    mutationFn: (id: number) => deleteRecurring(id),
+    onSuccess: () => invalidate(false),
+  });
+}
+
+export function usePostRecurring() {
+  const invalidate = useInvalidateRecurring();
+  return useMutation({
+    mutationFn: (id: number) => postRecurring(id),
+    onSuccess: () => invalidate(true),
+  });
+}

frontend/src/hooks/useReports.ts

@@ -0,0 +1,18 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchCategoryRanking, fetchCategorySpendingReport } from "@/api/reports";
+import type { CategoryKind } from "@/types";
+
+export function useCategorySpendingReport(categoryId: number | null, startDate?: string, endDate?: string) {
+  return useQuery({
+    queryKey: ["category-spending-report", categoryId, startDate, endDate],
+    queryFn: () => fetchCategorySpendingReport(categoryId as number, startDate, endDate),
+    enabled: categoryId !== null,
+  });
+}
+
+export function useCategoryRanking(kind: CategoryKind, startDate?: string, endDate?: string) {
+  return useQuery({
+    queryKey: ["category-ranking", kind, startDate, endDate],
+    queryFn: () => fetchCategoryRanking(kind, startDate, endDate),
+  });
+}

frontend/src/hooks/useSettings.ts

@@ -0,0 +1,19 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { fetchSettings, updateSettings } from "@/api/settings";
+import { setCurrency } from "@/lib/i18n";
+import type { AppSettings } from "@/types";
+
+export function useAppSettings() {
+  return useQuery({ queryKey: ["settings"], queryFn: fetchSettings });
+}
+
+export function useUpdateAppSettings() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (input: Partial<AppSettings>) => updateSettings(input),
+    onSuccess: (data) => {
+      queryClient.setQueryData(["settings"], data);
+      setCurrency(data.currency);
+    },
+  });
+}

frontend/src/hooks/useTransactions.ts

@@ -0,0 +1,56 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  createTransaction,
+  deleteTransaction,
+  fetchTransactions,
+  updateTransaction,
+  type TransactionFilters,
+} from "@/api/transactions";
+import type { TransactionInput } from "@/types";
+
+function useInvalidateAfterTransactionChange() {
+  const queryClient = useQueryClient();
+  return () => {
+    queryClient.invalidateQueries({ queryKey: ["transactions"] });
+    queryClient.invalidateQueries({ queryKey: ["dashboard-summary"] });
+    queryClient.invalidateQueries({ queryKey: ["net-worth-summary"] });
+    queryClient.invalidateQueries({ queryKey: ["category-spending-report"] });
+    queryClient.invalidateQueries({ queryKey: ["category-ranking"] });
+    queryClient.invalidateQueries({ queryKey: ["budget-status"] });
+    queryClient.invalidateQueries({ queryKey: ["financial-alerts"] });
+    queryClient.invalidateQueries({ queryKey: ["advice"] });
+    queryClient.invalidateQueries({ queryKey: ["cash-flow"] });
+  };
+}
+
+export function useTransactions(filters: TransactionFilters) {
+  return useQuery({
+    queryKey: ["transactions", filters],
+    queryFn: () => fetchTransactions(filters),
+  });
+}
+
+export function useCreateTransaction() {
+  const invalidate = useInvalidateAfterTransactionChange();
+  return useMutation({
+    mutationFn: (input: TransactionInput) => createTransaction(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateTransaction() {
+  const invalidate = useInvalidateAfterTransactionChange();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: Partial<TransactionInput> }) =>
+      updateTransaction(id, input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteTransaction() {
+  const invalidate = useInvalidateAfterTransactionChange();
+  return useMutation({
+    mutationFn: (id: number) => deleteTransaction(id),
+    onSuccess: invalidate,
+  });
+}