Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

feat: hide transfers from dashboard/drill-down and add transfer tooltip

Tássio Noronhacae0ab7ce9b1
diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.py
index 49d74287..83fb0b83 100644
--- a/backend/app/api/transactions.py
+++ b/backend/app/api/transactions.py
@@ -45,12 +45,14 @@ async def list_transactions(
page: int = Query(1, ge=1),
limit: int = Query(50, ge=1, le=500),
include_opening_balance: bool = Query(False),
+ exclude_transfers: bool = Query(False),
session: AsyncSession = Depends(get_async_session),
user: User = Depends(current_active_user),
):
transactions, total = await transaction_service.get_transactions(
session, user.id, account_id, category_id, payee_id, from_date, to_date, page, limit,
include_opening_balance, search=q, uncategorized=uncategorized, txn_type=type,
+ exclude_transfers=exclude_transfers,
)
primary_currency = user.primary_currency
items = [_tag_fx_fallback(TransactionRead.model_validate(tx, from_attributes=True), primary_currency) for tx in transactions]
diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.py
index 6be04156..c6ffade8 100644
--- a/backend/app/services/transaction_service.py
+++ b/backend/app/services/transaction_service.py
@@ -57,6 +57,7 @@ async def get_transactions(
uncategorized: bool = False,
txn_type: Optional[str] = None,
skip_pagination: bool = False,
+ exclude_transfers: bool = False,
) -> tuple[list[Transaction], int]:
# Base query: user's own transactions (manual or via account)
base_query = (
@@ -89,6 +90,8 @@ async def get_transactions(
Transaction.category_id == None,
Transaction.transfer_pair_id.is_(None),
)
+ if exclude_transfers:
+ base_query = base_query.where(Transaction.transfer_pair_id.is_(None))
if txn_type:
base_query = base_query.where(Transaction.type == txn_type)
if from_date:
diff --git a/backend/app/services/transfer_detection_service.py b/backend/app/services/transfer_detection_service.py
index eccb2e26..190cf53e 100644
--- a/backend/app/services/transfer_detection_service.py
+++ b/backend/app/services/transfer_detection_service.py
@@ -17,14 +17,15 @@ async def detect_transfer_pairs(
"""Detect inter-account transfer pairs and link them with a shared UUID.
Algorithm:
- 1. Load unpaired debit transactions (optionally filtered to candidate_ids)
+ 1. When candidate_ids is given, load candidate debits AND candidate credits
+ so that detection works regardless of which side was just imported.
2. For each debit, find an unpaired credit with: same user, different account,
same absolute amount, date within ±tolerance days
3. Greedy closest-date-first matching; each tx can only pair once
Returns the number of pairs created.
"""
- # Load candidate debits
+ # Load candidate debits — filtered to candidate_ids when provided
debit_query = select(Transaction).where(
Transaction.user_id == user_id,
Transaction.type == "debit",
@@ -37,7 +38,24 @@ async def detect_transfer_pairs(
debit_result = await session.execute(debit_query)
debits = list(debit_result.scalars().all())
- if not debits:
+ # When candidate_ids is given, also load ALL unpaired debits that could
+ # match new credits (the reverse direction).
+ if candidate_ids:
+ reverse_debit_query = select(Transaction).where(
+ Transaction.user_id == user_id,
+ Transaction.type == "debit",
+ Transaction.transfer_pair_id.is_(None),
+ Transaction.source != "opening_balance",
+ Transaction.id.not_in(candidate_ids),
+ )
+ reverse_result = await session.execute(reverse_debit_query)
+ reverse_debits = list(reverse_result.scalars().all())
+ else:
+ reverse_debits = []
+
+ all_debits = debits + reverse_debits
+
+ if not all_debits:
return 0
# Load all unpaired credits for the user (potential partners)
@@ -53,27 +71,37 @@ async def detect_transfer_pairs(
if not credits:
return 0
+ # When candidate_ids is given, restrict reverse debits to only match
+ # credits that are in candidate_ids (avoid pairing two old transactions).
+ candidate_id_set = set(candidate_ids) if candidate_ids else None
+
# Build a lookup: amount -> list of credits
credit_by_amount: dict[float, list[Transaction]] = defaultdict(list)
for c in credits:
credit_by_amount[abs(float(c.amount))].append(c)
paired_credit_ids: set[uuid.UUID] = set()
+ paired_debit_ids: set[uuid.UUID] = set()
pairs_created = 0
- for debit in debits:
+ for debit in all_debits:
debit_amount = abs(float(debit.amount))
- candidates = credit_by_amount.get(debit_amount, [])
+ amount_candidates = credit_by_amount.get(debit_amount, [])
+
+ is_reverse_debit = candidate_id_set is not None and debit.id not in candidate_id_set
# Find closest-date match in a different account
best_match: Optional[Transaction] = None
best_delta: Optional[int] = None
- for credit in candidates:
+ for credit in amount_candidates:
if credit.id in paired_credit_ids:
continue
if credit.account_id == debit.account_id:
continue
+ # Reverse debits may only match credits from candidate_ids
+ if is_reverse_debit and candidate_id_set and credit.id not in candidate_id_set:
+ continue
delta = abs((credit.date - debit.date).days)
if delta > date_tolerance_days:
@@ -88,6 +116,7 @@ async def detect_transfer_pairs(
debit.transfer_pair_id = pair_id
best_match.transfer_pair_id = pair_id
paired_credit_ids.add(best_match.id)
+ paired_debit_ids.add(debit.id)
pairs_created += 1
return pairs_created
diff --git a/backend/tests/test_transactions_api.py b/backend/tests/test_transactions_api.py
index 13b393fe..54b64999 100644
--- a/backend/tests/test_transactions_api.py
+++ b/backend/tests/test_transactions_api.py
@@ -1,9 +1,16 @@
+import uuid
+from datetime import date, datetime, timezone
+from decimal import Decimal
+
import pytest
+import pytest_asyncio
from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
from app.models.account import Account
from app.models.transaction import Transaction
from app.models.category import Category
+from app.models.user import User
@pytest.mark.asyncio
@@ -290,3 +297,86 @@ async def test_create_transaction_without_account_fails(
},
)
assert response.status_code == 422
+
+
+# --- exclude_transfers tests ---
+
+@pytest_asyncio.fixture
+async def test_transactions_with_transfers(
+ session: AsyncSession, test_user: User, test_account: Account,
+) -> list[Transaction]:
+ """Create a mix of regular and transfer transactions."""
+ today = date.today()
+ pair_id = uuid.uuid4()
+ transactions = []
+ data = [
+ ("GROCERIES", Decimal("50.00"), today, "debit", None, None),
+ ("SALARY", Decimal("3000.00"), today, "credit", None, None),
+ ("Transfer out", Decimal("200.00"), today, "debit", None, pair_id),
+ ("Transfer in", Decimal("200.00"), today, "credit", None, pair_id),
+ ]
+ for desc, amount, dt, typ, cat_id, transfer_id in data:
+ txn = Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ account_id=test_account.id,
+ category_id=cat_id,
+ description=desc,
+ amount=amount,
+ date=dt,
+ type=typ,
+ source="transfer" if transfer_id else "manual",
+ transfer_pair_id=transfer_id,
+ created_at=datetime.now(timezone.utc),
+ )
+ session.add(txn)
+ transactions.append(txn)
+ await session.commit()
+ for txn in transactions:
+ await session.refresh(txn)
+ return transactions
+
+
+async def test_list_transactions_includes_transfers_by_default(
+ client: AsyncClient, auth_headers, test_transactions_with_transfers,
+):
+ """Without exclude_transfers, all transactions including transfers are returned."""
+ response = await client.get("/api/transactions", headers=auth_headers)
+ assert response.status_code == 200
+ data = response.json()
+ assert data["total"] == 4
+ descriptions = [item["description"] for item in data["items"]]
+ assert "Transfer out" in descriptions
+ assert "Transfer in" in descriptions
+
+
+async def test_list_transactions_exclude_transfers(
+ client: AsyncClient, auth_headers, test_transactions_with_transfers,
+):
+ """With exclude_transfers=true, transfer transactions are hidden."""
+ response = await client.get(
+ "/api/transactions?exclude_transfers=true", headers=auth_headers
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data["total"] == 2
+ descriptions = [item["description"] for item in data["items"]]
+ assert "GROCERIES" in descriptions
+ assert "SALARY" in descriptions
+ assert "Transfer out" not in descriptions
+ assert "Transfer in" not in descriptions
+
+
+async def test_exclude_transfers_false_includes_all(
+ client: AsyncClient, auth_headers, test_transactions_with_transfers,
+):
+ """Explicitly setting exclude_transfers=false still includes transfers."""
+ response = await client.get(
+ "/api/transactions?exclude_transfers=false", headers=auth_headers
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data["total"] == 4
diff --git a/backend/tests/test_transfer_detection.py b/backend/tests/test_transfer_detection.py
index d4e1bd5e..f5b6e1b1 100644
--- a/backend/tests/test_transfer_detection.py
+++ b/backend/tests/test_transfer_detection.py
@@ -254,3 +254,111 @@ async def test_unlink_nonexistent_pair(session: AsyncSession, test_user):
"""Unlinking a nonexistent pair returns 0."""
unlinked = await unlink_transfer_pair(session, test_user.id, uuid.uuid4())
assert unlinked == 0
+
+
+# ---------------------------------------------------------------------------
+# Reverse-direction candidate_ids detection
+# ---------------------------------------------------------------------------
+
+
+async def test_candidate_credit_matches_existing_debit(session: AsyncSession, test_user):
+ """When candidate_ids contains only a credit, it pairs with an existing debit.
+
+ Simulates: Account A synced first (debit already exists), then Account B
+ syncs and imports the matching credit.
+ """
+ acc1 = await _make_account(session, test_user.id, "Rev A")
+ acc2 = await _make_account(session, test_user.id, "Rev B")
+ today = date.today()
+
+ # Existing debit (from a previous sync)
+ debit = await _add_txn(session, test_user.id, acc1.id, 750, "debit", today)
+
+ # New credit just imported
+ credit = await _add_txn(session, test_user.id, acc2.id, 750, "credit", today)
+
+ # Only the credit is in candidate_ids (second sync)
+ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[credit.id])
+ await session.commit()
+ assert pairs == 1
+
+ await session.refresh(debit)
+ await session.refresh(credit)
+ assert debit.transfer_pair_id is not None
+ assert debit.transfer_pair_id == credit.transfer_pair_id
+
+
+async def test_candidate_debit_matches_existing_credit(session: AsyncSession, test_user):
+ """When candidate_ids contains only a debit, it pairs with an existing credit.
+
+ Simulates: Account B synced first (credit already exists), then Account A
+ syncs and imports the matching debit.
+ """
+ acc1 = await _make_account(session, test_user.id, "Fwd A")
+ acc2 = await _make_account(session, test_user.id, "Fwd B")
+ today = date.today()
+
+ # Existing credit (from a previous sync)
+ credit = await _add_txn(session, test_user.id, acc2.id, 600, "credit", today)
+
+ # New debit just imported
+ debit = await _add_txn(session, test_user.id, acc1.id, 600, "debit", today)
+
+ # Only the debit is in candidate_ids (second sync)
+ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[debit.id])
+ await session.commit()
+ assert pairs == 1
+
+ await session.refresh(debit)
+ await session.refresh(credit)
+ assert debit.transfer_pair_id is not None
+ assert debit.transfer_pair_id == credit.transfer_pair_id
+
+
+async def test_reverse_detection_does_not_pair_two_old_transactions(session: AsyncSession, test_user):
+ """Reverse detection must not pair two transactions that are both outside candidate_ids."""
+ acc1 = await _make_account(session, test_user.id, "Guard A")
+ acc2 = await _make_account(session, test_user.id, "Guard B")
+ acc3 = await _make_account(session, test_user.id, "Guard C")
+ today = date.today()
+
+ # Two old unpaired transactions that could match each other
+ old_debit = await _add_txn(session, test_user.id, acc1.id, 300, "debit", today)
+ old_credit = await _add_txn(session, test_user.id, acc2.id, 300, "credit", today)
+
+ # A new unrelated credit (different amount) triggers detection
+ new_credit = await _add_txn(session, test_user.id, acc3.id, 999, "credit", today)
+
+ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[new_credit.id])
+ await session.commit()
+ assert pairs == 0
+
+ # Old transactions must remain unpaired
+ await session.refresh(old_debit)
+ await session.refresh(old_credit)
+ assert old_debit.transfer_pair_id is None
+ assert old_credit.transfer_pair_id is None
+
+
+async def test_both_sides_imported_together(session: AsyncSession, test_user):
+ """When both debit and credit are new (same sync), both are in candidate_ids."""
+ acc1 = await _make_account(session, test_user.id, "Both A")
+ acc2 = await _make_account(session, test_user.id, "Both B")
+ today = date.today()
+
+ debit = await _add_txn(session, test_user.id, acc1.id, 200, "debit", today)
+ credit = await _add_txn(session, test_user.id, acc2.id, 200, "credit", today)
+
+ pairs = await detect_transfer_pairs(
+ session, test_user.id, candidate_ids=[debit.id, credit.id],
+ )
+ await session.commit()
+ assert pairs == 1
+
+ await session.refresh(debit)
+ await session.refresh(credit)
+ assert debit.transfer_pair_id == credit.transfer_pair_id
diff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsx
index f605e338..4c5bf676 100644
--- a/frontend/src/components/transaction-dialog.tsx
+++ b/frontend/src/components/transaction-dialog.tsx
@@ -438,8 +438,11 @@ function TransactionForm({
</div>
)}
{!!transaction?.transfer_pair_id && (
- <div className="flex items-center gap-2 p-3 text-sm bg-blue-50 dark:bg-blue-950 border border-blue-200 dark:border-blue-800 rounded-md text-blue-700 dark:text-blue-300">
- {t('transactions.transferInfo')}
+ <div className="p-3 text-sm bg-blue-50 dark:bg-blue-950 border border-blue-200 dark:border-blue-800 rounded-md text-blue-700 dark:text-blue-300 space-y-1">
+ <div className="flex items-center gap-2">
+ {t('transactions.transferInfo')}
+ </div>
+ <p className="text-xs text-blue-500 dark:text-blue-400">{t('transactions.transferTooltip')}</p>
</div>
)}
{recurringMatch && (
diff --git a/frontend/src/components/transaction-drill-down.tsx b/frontend/src/components/transaction-drill-down.tsx
index bc8d94fd..abb24dad 100644
--- a/frontend/src/components/transaction-drill-down.tsx
+++ b/frontend/src/components/transaction-drill-down.tsx
@@ -65,6 +65,7 @@ export function TransactionDrillDown({
from: filter?.from,
to: filter?.to,
limit: 200,
+ exclude_transfers: true,
}),
enabled: !!filter,
})
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 81043471..cc3fc626 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -240,6 +240,7 @@ export const transactions = {
page?: number
limit?: number
include_opening_balance?: boolean
+ exclude_transfers?: boolean
}): Promise<PaginatedResponse<Transaction>> => {
const { data } = await api.get('/transactions', { params })
return data
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 08f75089..b28e3c53 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -177,7 +177,8 @@
"transferSameAccount": "Source and destination must be different",
"transferDescription": "Description",
"transferNotes": "Notes",
- "transferInfo": "This is a transfer — changes to description, date, and notes will apply to both sides"
+ "transferInfo": "This is a transfer — changes to description, date, and notes will apply to both sides",
+ "transferTooltip": "Transfers are excluded from report and dashboard totals"
},
"accounts": {
"title": "Accounts",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index 3038ad96..fb4cec88 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -177,7 +177,8 @@
"transferSameAccount": "Origem e destino devem ser diferentes",
"transferDescription": "Descrição",
"transferNotes": "Notas",
- "transferInfo": "Esta é uma transferência — alterações na descrição, data e notas serão aplicadas em ambos os lados"
+ "transferInfo": "Esta é uma transferência — alterações na descrição, data e notas serão aplicadas em ambos os lados",
+ "transferTooltip": "Transferências são excluídas dos totais de relatórios e dashboard"
},
"accounts": {
"title": "Contas",
diff --git a/frontend/src/pages/account-detail.tsx b/frontend/src/pages/account-detail.tsx
index ae68d8d7..a75e5abd 100644
--- a/frontend/src/pages/account-detail.tsx
+++ b/frontend/src/pages/account-detail.tsx
@@ -8,7 +8,7 @@ import { toast } from 'sonner'
import type { Transaction } from '@/types'
import { Skeleton } from '@/components/ui/skeleton'
import { Button } from '@/components/ui/button'
-import { ArrowLeft, ArrowLeftRight, Clock, Paperclip, X } from 'lucide-react'
+import { ArrowLeft, ArrowLeftRight, Clock, HelpCircle, Paperclip, X } from 'lucide-react'
import { CategoryIcon } from '@/components/category-icon'
import { TransactionDialog, extractApiError } from '@/components/transaction-dialog'
import { TransferDialog } from '@/components/transfer-dialog'
@@ -474,6 +474,7 @@ export default function AccountDetailPage() {
<span className="ml-2 inline-flex items-center gap-1 text-xs text-blue-600 font-normal bg-blue-50 border border-blue-200 rounded px-1.5 py-0.5">
<ArrowLeftRight className="h-3 w-3" />
{t('transactions.transfer')}
+ <span title={t('transactions.transferTooltip')}><HelpCircle className="h-3 w-3 text-blue-400" /></span>
</span>
)}
{isPending && (
diff --git a/frontend/src/pages/dashboard.tsx b/frontend/src/pages/dashboard.tsx
index fe20b299..e3f323b6 100644
--- a/frontend/src/pages/dashboard.tsx
+++ b/frontend/src/pages/dashboard.tsx
@@ -118,6 +118,7 @@ export default function DashboardPage() {
from: `${selectedMonth}-01`,
to: `${selectedMonth}-${String(monthLastDay(selectedMonth)).padStart(2, '0')}`,
limit: 500,
+ exclude_transfers: true,
}),
})
diff --git a/frontend/src/pages/transactions.tsx b/frontend/src/pages/transactions.tsx
index 09a48b2e..9a7f42c9 100644
--- a/frontend/src/pages/transactions.tsx
+++ b/frontend/src/pages/transactions.tsx
@@ -15,7 +15,7 @@ import {
} from '@/components/ui/table'
import { Input } from '@/components/ui/input'
import { Skeleton } from '@/components/ui/skeleton'
-import { AlertTriangle, ArrowLeftRight, Check, Download, Paperclip, Search, X } from 'lucide-react'
+import { AlertTriangle, ArrowLeftRight, Check, Download, HelpCircle, Paperclip, Search, X } from 'lucide-react'
import type { Transaction } from '@/types'
import { PageHeader } from '@/components/page-header'
import { CategoryIcon } from '@/components/category-icon'
@@ -426,6 +426,7 @@ export default function TransactionsPage() {
<span className="inline-flex items-center gap-1 text-[10px] font-semibold uppercase tracking-wide text-blue-600 bg-blue-50 border border-blue-200 px-1.5 py-0.5 rounded-full">
<ArrowLeftRight className="h-3 w-3" />
{t('transactions.transfer')}
+ <span title={t('transactions.transferTooltip')}><HelpCircle className="h-3 w-3 text-blue-400" /></span>
</span>
)}
{recurringList?.some(r => r.description === tx.description && r.type === tx.type) && (