Skip to content

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

add full data backup as ZIP download from user menu

Tássio Noronhac829de54759f
diff --git a/backend/app/api/export.py b/backend/app/api/export.py
new file mode 100644
index 00000000..30a8b2a5
--- /dev/null
+++ b/backend/app/api/export.py
@@ -0,0 +1,105 @@
+import io
+import json
+import zipfile
+from datetime import date, datetime
+from decimal import Decimal
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import current_active_user
+from app.core.database import get_async_session
+from app.models.account import Account
+from app.models.asset import Asset
+from app.models.asset_value import AssetValue
+from app.models.budget import Budget
+from app.models.category import Category
+from app.models.category_group import CategoryGroup
+from app.models.import_log import ImportLog
+from app.models.recurring_transaction import RecurringTransaction
+from app.models.rule import Rule
+from app.models.transaction import Transaction
+from app.models.user import User
+
+router = APIRouter(prefix="/api/export", tags=["export"])
+
+
+def _serialize(obj) -> dict:
+ """Convert a SQLAlchemy model instance to a JSON-serializable dict."""
+ d = {}
+ for col in obj.__table__.columns:
+ val = getattr(obj, col.key)
+ if isinstance(val, UUID):
+ val = str(val)
+ elif isinstance(val, (datetime, date)):
+ val = val.isoformat()
+ elif isinstance(val, Decimal):
+ val = str(val)
+ d[col.key] = val
+ return d
+
+
+async def backup(
+ session: AsyncSession = Depends(get_async_session),
+ user: User = Depends(current_active_user),
+):
+ user_id = user.id
+
+ # Query all entities for the current user
+ accounts = (await session.execute(select(Account).where(Account.user_id == user_id))).scalars().all()
+ transactions = (await session.execute(select(Transaction).where(Transaction.user_id == user_id))).scalars().all()
+ categories = (await session.execute(select(Category).where(Category.user_id == user_id))).scalars().all()
+ category_groups = (await session.execute(select(CategoryGroup).where(CategoryGroup.user_id == user_id))).scalars().all()
+ rules = (await session.execute(select(Rule).where(Rule.user_id == user_id))).scalars().all()
+ recurring_transactions = (await session.execute(select(RecurringTransaction).where(RecurringTransaction.user_id == user_id))).scalars().all()
+ budgets = (await session.execute(select(Budget).where(Budget.user_id == user_id))).scalars().all()
+ assets = (await session.execute(select(Asset).where(Asset.user_id == user_id))).scalars().all()
+ import_logs = (await session.execute(select(ImportLog).where(ImportLog.user_id == user_id))).scalars().all()
+
+ # AssetValue lacks user_id — filter via asset_ids
+ asset_ids = [a.id for a in assets]
+ if asset_ids:
+ asset_values = (await session.execute(select(AssetValue).where(AssetValue.asset_id.in_(asset_ids)))).scalars().all()
+ else:
+ asset_values = []
+
+ entities = {
+ "accounts": accounts,
+ "transactions": transactions,
+ "categories": categories,
+ "category_groups": category_groups,
+ "rules": rules,
+ "recurring_transactions": recurring_transactions,
+ "budgets": budgets,
+ "assets": assets,
+ "asset_values": asset_values,
+ "import_logs": import_logs,
+ }
+
+ # Build in-memory ZIP
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+ entity_counts = {}
+ for name, rows in entities.items():
+ serialized = [_serialize(r) for r in rows]
+ entity_counts[name] = len(serialized)
+ zf.writestr(f"{name}.json", json.dumps(serialized, indent=2, ensure_ascii=False))
+
+ metadata = {
+ "export_date": datetime.utcnow().isoformat(),
+ "format_version": "1.0",
+ "entity_counts": entity_counts,
+ }
+ zf.writestr("metadata.json", json.dumps(metadata, indent=2, ensure_ascii=False))
+
+ buf.seek(0)
+ today = date.today().isoformat()
+ return StreamingResponse(
+ iter([buf.getvalue()]),
+ media_type="application/zip",
+ headers={"Content-Disposition": f'attachment; filename="securo-backup-{today}.zip"'},
+ )
diff --git a/backend/app/main.py b/backend/app/main.py
index d195db14..4558d41e 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -18,6 +18,7 @@ from app.api.assets import router as assets_router
from app.api.reports import router as reports_router
from app.api.setup import router as setup_router
from app.api.currencies import router as currencies_router
+from app.api.export import router as export_router
from app.api.fx_rates import router as fx_rates_router
from app.api.transactions import router as transactions_router
from app.core.auth import auth_backend, fastapi_users
@@ -95,6 +96,7 @@ app.include_router(reports_router)
app.include_router(setup_router)
app.include_router(currencies_router)
app.include_router(fx_rates_router)
+app.include_router(export_router)
@app.get("/api/health")
diff --git a/backend/tests/test_export_api.py b/backend/tests/test_export_api.py
new file mode 100644
index 00000000..f0ea4488
--- /dev/null
+++ b/backend/tests/test_export_api.py
@@ -0,0 +1,95 @@
+import io
+import json
+import zipfile
+
+import pytest
+from httpx import AsyncClient
+
+from app.models.account import Account
+from app.models.category import Category
+from app.models.rule import Rule
+from app.models.transaction import Transaction
+
+
+async def test_backup_unauthenticated(client: AsyncClient):
+ response = await client.get("/api/export/backup")
+ assert response.status_code == 401
+
+
+async def test_backup_empty(client: AsyncClient, auth_headers):
+ response = await client.get("/api/export/backup", headers=auth_headers)
+ assert response.status_code == 200
+ assert response.headers["content-type"] == "application/zip"
+
+ buf = io.BytesIO(response.content)
+ with zipfile.ZipFile(buf) as zf:
+ names = zf.namelist()
+ assert "metadata.json" in names
+ assert "accounts.json" in names
+ assert "transactions.json" in names
+
+ metadata = json.loads(zf.read("metadata.json"))
+ assert metadata["format_version"] == "1.0"
+ assert "export_date" in metadata
+ for count in metadata["entity_counts"].values():
+ assert count == 0
+
+
+async def test_backup_with_data(
+ client: AsyncClient,
+ auth_headers,
+ test_account: Account,
+ test_transactions: list[Transaction],
+ test_categories: list[Category],
+ test_rules: list[Rule],
+):
+ response = await client.get("/api/export/backup", headers=auth_headers)
+ assert response.status_code == 200
+
+ # Verify Content-Disposition header contains filename
+ disposition = response.headers.get("content-disposition", "")
+ assert "securo-backup-" in disposition
+ assert ".zip" in disposition
+
+ buf = io.BytesIO(response.content)
+ with zipfile.ZipFile(buf) as zf:
+ expected_files = [
+ "accounts.json",
+ "transactions.json",
+ "categories.json",
+ "category_groups.json",
+ "rules.json",
+ "recurring_transactions.json",
+ "budgets.json",
+ "assets.json",
+ "asset_values.json",
+ "import_logs.json",
+ "metadata.json",
+ ]
+ for fname in expected_files:
+ assert fname in zf.namelist(), f"{fname} missing from ZIP"
+
+ # Verify entity counts match
+ metadata = json.loads(zf.read("metadata.json"))
+ counts = metadata["entity_counts"]
+ assert counts["accounts"] == 1
+ assert counts["transactions"] == len(test_transactions)
+ assert counts["categories"] == len(test_categories)
+ assert counts["rules"] == len(test_rules)
+
+ # Verify JSON content is parseable and has expected fields
+ accounts = json.loads(zf.read("accounts.json"))
+ assert len(accounts) == 1
+ assert accounts[0]["name"] == "Conta Corrente"
+
+ transactions = json.loads(zf.read("transactions.json"))
+ assert len(transactions) == len(test_transactions)
+ # Verify UUIDs are serialized as strings
+ assert isinstance(transactions[0]["id"], str)
+ # Verify dates are serialized as ISO strings
+ assert isinstance(transactions[0]["date"], str)
+ # Verify decimals are serialized as strings
+ assert isinstance(transactions[0]["amount"], str)
diff --git a/frontend/src/components/app-layout.tsx b/frontend/src/components/app-layout.tsx
index 0b963688..fbd25eee 100644
--- a/frontend/src/components/app-layout.tsx
+++ b/frontend/src/components/app-layout.tsx
@@ -3,7 +3,8 @@ import { Link, Outlet, useLocation } from 'react-router-dom'
import { useTranslation } from 'react-i18next'
import { useQuery } from '@tanstack/react-query'
import { useAuth } from '@/contexts/auth-context'
-import { auth as authApi } from '@/lib/api'
+import { auth as authApi, backup as backupApi } from '@/lib/api'
+import { toast } from 'sonner'
import { OnboardingTour } from '@/components/onboarding-tour'
import { useTheme } from 'next-themes'
import { accounts as accountsApi } from '@/lib/api'
@@ -37,6 +38,7 @@ import {
Sun,
Moon,
KeyRound,
+ HardDriveDownload,
} from 'lucide-react'
import { usePrivacyMode } from '@/hooks/use-privacy-mode'
import { ChangePasswordDialog } from '@/components/change-password-dialog'
@@ -69,6 +71,7 @@ export function AppLayout() {
const [accountsExpanded, setAccountsExpanded] = useState(true)
const { privacyMode, togglePrivacyMode, mask } = usePrivacyMode()
const [changePasswordOpen, setChangePasswordOpen] = useState(false)
+ const [backingUp, setBackingUp] = useState(false)
const showTour = user && !user.preferences?.onboarding_completed && !localStorage.getItem('onboarding_completed')
@@ -119,7 +122,17 @@ export function AppLayout() {
>
{privacyMode ? <EyeOff size={18} /> : <Eye size={18} />}
</button>
- <UserMenu userInitial={userInitial} logout={logout} onChangePassword={() => setChangePasswordOpen(true)} dark />
+ <UserMenu userInitial={userInitial} logout={logout} onChangePassword={() => setChangePasswordOpen(true)} backingUp={backingUp} onBackup={async () => {
+ setBackingUp(true)
+ try {
+ await backupApi.download()
+ toast.success(t('backup.success'))
+ } catch {
+ toast.error(t('backup.error'))
+ } finally {
+ setBackingUp(false)
+ }
+ }} dark />
</div>
</header>
@@ -322,6 +335,24 @@ export function AppLayout() {
<KeyRound size={14} />
{t('auth.changePassword')}
</DropdownMenuItem>
+ <DropdownMenuItem
+ disabled={backingUp}
+ onClick={async () => {
+ setBackingUp(true)
+ try {
+ await backupApi.download()
+ toast.success(t('backup.success'))
+ } catch {
+ toast.error(t('backup.error'))
+ } finally {
+ setBackingUp(false)
+ }
+ }}
+ className="flex items-center gap-2"
+ >
+ <HardDriveDownload size={14} />
+ {backingUp ? t('backup.downloading') : t('backup.button')}
+ </DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem
onClick={logout}
@@ -349,7 +380,7 @@ export function AppLayout() {
)
}
-function UserMenu({ userInitial, logout, onChangePassword, dark }: { userInitial: string; logout: () => void; onChangePassword: () => void; dark?: boolean }) {
+function UserMenu({ userInitial, logout, onChangePassword, onBackup, backingUp, dark }: { userInitial: string; logout: () => void; onChangePassword: () => void; onBackup: () => void; backingUp: boolean; dark?: boolean }) {
const { t } = useTranslation()
return (
<DropdownMenu>
@@ -367,6 +398,10 @@ function UserMenu({ userInitial, logout, onChangePassword, dark }: { userInitial
<KeyRound size={14} />
{t('auth.changePassword')}
</DropdownMenuItem>
+ <DropdownMenuItem disabled={backingUp} onClick={onBackup} className="flex items-center gap-2">
+ <HardDriveDownload size={14} />
+ {backingUp ? t('backup.downloading') : t('backup.button')}
+ </DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem onClick={logout} className="text-rose-600 focus:text-rose-600">
{t('auth.logout')}
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 9dd804bf..47da0d8d 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -474,4 +474,20 @@ export const importLogs = {
},
}
+// Backup
+export const backup = {
+ download: async (): Promise<void> => {
+ const { data } = await api.get('/export/backup', { responseType: 'blob' })
+ const blob = new Blob([data], { type: 'application/zip' })
+ const url = URL.createObjectURL(blob)
+ const a = document.createElement('a')
+ a.href = url
+ a.download = `securo-backup-${new Date().toISOString().slice(0, 10)}.zip`
+ document.body.appendChild(a)
+ a.click()
+ document.body.removeChild(a)
+ URL.revokeObjectURL(url)
+ },
+}
+
export default api
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 1768874a..f85a8bbe 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -510,6 +510,12 @@
"name": "Your name",
"namePlaceholder": "How should we call you?"
},
+ "backup": {
+ "button": "Backup",
+ "downloading": "Downloading...",
+ "success": "Backup downloaded successfully",
+ "error": "Failed to download backup"
+ },
"onboarding": {
"sidebar": "Sidebar Navigation",
"sidebarDesc": "Use the sidebar to navigate between sections of the app.",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index 90d41179..0da08941 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -510,6 +510,12 @@
"name": "Seu nome",
"namePlaceholder": "Como devemos te chamar?"
},
+ "backup": {
+ "button": "Backup",
+ "downloading": "Baixando...",
+ "success": "Backup baixado com sucesso",
+ "error": "Erro ao baixar backup"
+ },
"onboarding": {
"sidebar": "Navegação Lateral",
"sidebarDesc": "Use a barra lateral para navegar entre as seções do app.",