diff --git a/app/apps/mini_tools/tests.py b/app/apps/mini_tools/tests.py
index 7ce503c2..e2227048 100644
--- a/app/apps/mini_tools/tests.py
+++ b/app/apps/mini_tools/tests.py
@@ -1,3 +1,129 @@
-from django.test import TestCase
+from datetime import date
+from decimal import Decimal
+from unittest.mock import patch
-# Create your tests here.
+from django.contrib.auth import get_user_model
+from django.test import TestCase, override_settings
+from django.urls import reverse
+from django.utils import timezone
+
+from apps.accounts.models import Account, AccountGroup
+from apps.common.middleware.thread_local import delete_current_user, write_current_user
+from apps.currencies.models import Currency, ExchangeRate
+from apps.mini_tools.utils.simulator import get_simulator_baseline
+from apps.transactions.models import Transaction
+
+
+@override_settings(
+ STORAGES={
+ "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
+ "staticfiles": {
+ "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"
+ },
+ },
+ WHITENOISE_AUTOREFRESH=True,
+)
+@patch(
+ "apps.mini_tools.utils.simulator.timezone.localdate",
+ return_value=date(2026, 3, 15),
+)
+class SimulatorTests(TestCase):
+ def setUp(self):
+ User = get_user_model()
+ self.user = User.objects.create_user(
+ email="testuser@test.com", password="testpass123"
+ )
+ self.client.login(username="testuser@test.com", password="testpass123")
+ write_current_user(self.user)
+
+ self.currency = Currency.objects.create(
+ code="USD", name="US Dollar", decimal_places=2, prefix="$ "
+ )
+ group = AccountGroup.objects.create(name="Group")
+ self.account = Account.objects.create(
+ name="Checking", group=group, currency=self.currency
+ )
+
+ def tearDown(self):
+ delete_current_user()
+
+ def _transaction(self, type, amount, reference_date, is_paid=True, account=None):
+ return Transaction.objects.create(
+ account=account or self.account,
+ type=type,
+ is_paid=is_paid,
+ date=reference_date,
+ reference_date=reference_date,
+ amount=Decimal(amount),
+ description="Test",
+ owner=self.user,
+ )
+
+ def _currency(self, baseline):
+ return next(c for c in baseline["currencies"] if c["id"] == self.currency.id)
+
+ def test_baseline_monthly_projection(self, _):
+ self._transaction(Transaction.Type.INCOME, "1000", date(2026, 1, 1))
+ self._transaction(Transaction.Type.EXPENSE, "200", date(2026, 2, 1), False)
+ self._transaction(Transaction.Type.INCOME, "500", date(2026, 3, 1), False)
+ self._transaction(Transaction.Type.EXPENSE, "50", date(2026, 3, 1))
+ self._transaction(Transaction.Type.EXPENSE, "100", date(2031, 5, 1), False)
+
+ baseline = get_simulator_baseline(self.user)
+ currency = self._currency(baseline)
+
+ self.assertEqual(baseline["current_month"], "2026-03")
+ self.assertEqual(
+ currency["monthly"],
+ {"2026-01": 1000.0, "2026-02": -200.0, "2026-03": 450.0, "2031-05": -100.0},
+ )
+ self.assertIsNone(currency["exchange"])
+
+ def test_baseline_ignores_archived_and_untracked_accounts(self, _):
+ group = AccountGroup.objects.create(name="Other")
+ archived = Account.objects.create(
+ name="Old", group=group, currency=self.currency, is_archived=True
+ )
+ untracked = Account.objects.create(
+ name="Hidden", group=group, currency=self.currency
+ )
+ untracked.untracked_by.add(self.user)
+
+ self._transaction(Transaction.Type.INCOME, "100", date(2026, 3, 1))
+ self._transaction(
+ Transaction.Type.INCOME, "1000", date(2026, 3, 1), account=archived
+ )
+ self._transaction(
+ Transaction.Type.INCOME, "1000", date(2026, 3, 1), account=untracked
+ )
+
+ currency = self._currency(get_simulator_baseline(self.user))
+
+ self.assertEqual(currency["monthly"], {"2026-03": 100.0})
+
+ def test_baseline_exchange_rate(self, _):
+ euro = Currency.objects.create(
+ code="EUR", name="Euro", decimal_places=2, suffix=" EUR"
+ )
+ self.currency.exchange_currency = euro
+ self.currency.save()
+ ExchangeRate.objects.create(
+ from_currency=self.currency,
+ to_currency=euro,
+ rate=Decimal("0.5"),
+ date=timezone.now(),
+ )
+
+ currency = self._currency(get_simulator_baseline(self.user))
+
+ self.assertEqual(
+ currency["exchange"],
+ {"rate": 0.5, "prefix": "", "suffix": " EUR", "decimal_places": 2},
+ )
+
+ def test_simulator_view_renders(self, _):
+ response = self.client.get(reverse("simulator"))
+
+ self.assertEqual(response.status_code, 200)
+ self.assertContains(response, 'id="simulator-baseline"')
+ self.assertContains(response, "sim-start")
diff --git a/app/apps/mini_tools/urls.py b/app/apps/mini_tools/urls.py
index e4740424..0166de22 100644
--- a/app/apps/mini_tools/urls.py
+++ b/app/apps/mini_tools/urls.py
@@ -8,6 +8,11 @@ urlpatterns = [
views.unit_price_calculator,
name="unit_price_calculator",
),
+ path(
+ "tools/simulator/",
+ views.simulator,
+ name="simulator",
+ ),
path(
"tools/currency-converter/",
views.currency_converter,
diff --git a/app/apps/mini_tools/utils/simulator.py b/app/apps/mini_tools/utils/simulator.py
new file mode 100644
index 00000000..ac569550
--- /dev/null
+++ b/app/apps/mini_tools/utils/simulator.py
@@ -0,0 +1,90 @@
+from decimal import Decimal
+
+from django.db.models import Case, DecimalField, F, Sum, Value, When
+from django.db.models.functions import TruncMonth
+from django.utils import timezone
+
+from apps.accounts.models import Account
+from apps.currencies.models import Currency
+from apps.currencies.utils.convert import convert
+from apps.transactions.models import Transaction
+
+
+def get_simulator_baseline(user):
+ """
+ Build the projected baseline the simulator applies hypothetical entries on.
+
+ For each currency, returns the projected net change (every transaction,
+ paid or not) of each month that has transactions, keyed by "YYYY-MM", so
+ the balance at the start of any month can be derived by summing every
+ month before it. Archived and untracked accounts are ignored.
+
+ Currencies with an exchange currency also carry the rate used to show
+ their converted amounts.
+ """
+ accounts = Account.objects.filter(is_archived=False).exclude(
+ id__in=user.untracked_accounts.values_list("id", flat=True)
+ )
+ currencies = (
+ Currency.objects.filter(
+ id__in=accounts.values_list("currency", flat=True), is_archived=False
+ )
+ .select_related("exchange_currency")
+ .order_by("name")
+ )
+
+ monthly = {}
+ for row in (
+ Transaction.objects.filter(account__in=accounts)
+ .annotate(month=TruncMonth("reference_date"))
+ .values("account__currency", "month")
+ .annotate(
+ total=Sum(
+ Case(
+ When(type=Transaction.Type.INCOME, then=F("amount")),
+ When(type=Transaction.Type.EXPENSE, then=-F("amount")),
+ default=Value(0),
+ output_field=DecimalField(),
+ )
+ )
+ )
+ .order_by()
+ ):
+ monthly.setdefault(row["account__currency"], {})[
+ row["month"].strftime("%Y-%m")
+ ] = float(row["total"] or 0)
+
+ return {
+ "current_month": timezone.localdate(timezone.now()).strftime("%Y-%m"),
+ "currencies": [
+ {
+ "id": currency.id,
+ "name": currency.name,
+ "code": currency.code,
+ "prefix": currency.prefix,
+ "suffix": currency.suffix,
+ "decimal_places": currency.decimal_places,
+ "monthly": monthly.get(currency.id, {}),
+ "exchange": _get_exchange(currency),
+ }
+ for currency in currencies
+ ],
+ }
+
+
+def _get_exchange(currency):
+ if not currency.exchange_currency:
+ return None
+
+ rate, prefix, suffix, decimal_places = convert(
+ Decimal("1"), currency, currency.exchange_currency
+ )
+ if rate is None:
+ return None
+
+ return {
+ "rate": float(rate),
+ "prefix": prefix,
+ "suffix": suffix,
+ "decimal_places": decimal_places,
+ }
diff --git a/app/apps/mini_tools/views.py b/app/apps/mini_tools/views.py
index 2acd039d..359b1470 100644
--- a/app/apps/mini_tools/views.py
+++ b/app/apps/mini_tools/views.py
@@ -1,11 +1,14 @@
from django.contrib.auth.decorators import login_required
from django.shortcuts import render
+from django.utils import timezone
+from apps.common.widgets.datepicker import AirMonthYearPickerInput
from apps.common.widgets.decimal import convert_to_decimal
from apps.currencies.models import Currency
from apps.currencies.utils.convert import convert
from apps.mini_tools.forms import CurrencyConverterForm
from apps.mini_tools.utils.exchange_rate_map import get_currency_exchange_map
+from apps.mini_tools.utils.simulator import get_simulator_baseline
@login_required
@@ -13,6 +16,22 @@ def unit_price_calculator(request):
return render(request, "mini_tools/unit_price_calculator.html")
+@login_required
+def simulator(request):
+ start_month_input = AirMonthYearPickerInput(
+ clear_button=False, attrs={"class": "w-full sim-start"}
+ ).render("start_month", timezone.localdate(timezone.now()).replace(day=1))
+
+ return render(
+ request,
+ "mini_tools/simulator.html",
+ context={
+ "baseline": get_simulator_baseline(request.user),
+ "start_month_input": start_month_input,
+ },
+ )
+
+
@login_required
def currency_converter(request):
rate_map = get_currency_exchange_map()
diff --git a/app/templates/includes/sidebar.html b/app/templates/includes/sidebar.html
index 5162a873..1edaf52b 100644
--- a/app/templates/includes/sidebar.html
+++ b/app/templates/includes/sidebar.html
@@ -132,6 +132,12 @@
active="currency_converter"
icon="fa-solid fa-money-bill-transfer">
+
+ {% translate 'See how a one-time, recurring or installment expense or income would affect your projected balance in the coming months.' %} +
+ + {% if not baseline.currencies %} +| {% translate 'Month' %} | +{% translate 'Projected change' %} | +{% translate 'Simulated change' %} | +{% translate 'Balance without simulation' %} | +{% translate 'Balance with simulation' %} | +
|---|
+ {% translate 'The simulation starts at the earliest starting month among your entries, or the current month if there are none. Balances include paid and unpaid transactions, and archived and untracked accounts are ignored. Converted amounts use the latest exchange rate.' %} +
+ {% endif %} + + +