Docs

A short, in-app manual. Rough scaffolding, will grow over time.

What is The Better Decision

The Better Decision is a personal finance app for households and individuals. It tracks accounts, transactions, budgets, and forecasts, all scoped to your organization. Categories are the backbone of the model: budgets and forecasts ride on top of them, and most reporting is grouped by category. The app is pre-launch, so copy may be rough and some flows are still evolving.

Core concepts

Organizations. Every user belongs to an organization. All data (accounts, transactions, categories, plans) is scoped to that organization.
Members and roles. Within an org, users are owner, admin, or member. There is also a platform superadmin role for operators of the service.
Accounts. Bank accounts, credit cards, cash, savings. Each account has a type and a balance derived from its transactions.
Categories. Hierarchical: master categories group related subcategories. Each category has a type (income, expense, or both) which constrains where it can be used.
Transactions. Every transaction has a purchase date and a settled date. The settled date determines which billing period the transaction belongs to, which matters for credit cards where the purchase and the statement fall in different months.
Recurring transactions. Templates that fire on a cadence (monthly, weekly, biweekly, and so on) and generate transactions automatically.
Forecasts and budgets. Budgets are the current-period control surface. Forecast plans are forward-looking projections per category, used by the dashboard to show what the period is on track for.
Plans. A separate simulation sandbox for one-off life events (trip, purchase, retirement). Plans never touch your real transactions. See the Plans guide for the full mental model.

Common workflows

Importing a CSV

From the Import page, upload a CSV from your bank. The app parses the file, suggests categories where it can (auto-categorization), and shows a preview before anything is written. Confirm the preview to commit the rows as transactions.

Editing a transaction inline

On the Transactions page, click a row to expand the inline editor. You can change the amount, dates, category, and notes without leaving the list.

Promoting a transaction to recurring

When editing a transaction, the inline row exposes a "Promote to recurring" action that turns the transaction into a recurring template, so the same charge generates automatically next period.

Removing a recurring template only drops future, un-materialized occurrences. Past occurrences stay in your transaction history because they are real money movements, so balances are not affected. This is intentional: the template only schedules what has not happened yet.

Transactions generated from a recurring template are independent copies. Editing the name or category of any one of them updates the template and every upcoming (not yet settled) occurrence, so the series stays consistent going forward. Amounts and dates stay per occurrence, so you can adjust a single month without changing the rest. Settled past entries are never rewritten. Deleting a single transaction never removes other occurrences. Only stopping or deleting the recurring template removes its pending future occurrences, and settled history is always kept.

Marking transactions as a transfer pair

When money moves between two of your own accounts, you can either record the pair from the start (Add transfer) or convert an existing transaction by selecting its counterparty. The pair is then excluded from category-level spending so transfers do not double-count.

Setting up a forecast plan

From the Forecast Plans page, create a plan for the current or upcoming period. Categories pull from past activity and recurring templates as starting points; edit the per-category amount to match your expectation and save.

Reviewing the dashboard verdict

The dashboard summarizes the period with an On Track verdict that anchors on what has actually settled, not just what is projected. Below the verdict, a Forecast card shows your expected month-end balance per account (current balance plus pending items in the period), and a Forecast by Category card highlights how planned and actual compare for your top expense categories.

The Dashboard intentionally stays light on technical detail. For variance numbers, source attribution, the planned vs actual chart, and the refresh-from-sources control, open the Forecast Plans page and turn on Show details.

Forecasts: planning vs projecting

The Forecasts area can feel confusing at first because four ideas overlap: the plan, the projection, the variance, and the two buttons that fill the plan in. Here is each one in the simplest words.

Where you see what: the Dashboard answers household questions visually (are we on track, where will we end the month, which accounts and categories explain that). The Forecast Plans page is where you build and adjust the plan itself. Forecast Plans starts in a simple view and has a Show details toggle that reveals variance numbers, source attribution, the planned vs actual chart, and the refresh-from-sources control when you need them.

The plan is your wish list

A plan is a wish list with numbers. You write down what you want to spend on each category for the period. For example, "I want to spend 600 on groceries this month and 80 on coffee." That is the plan. Saving the plan does not move any money. It just records your intention.

Auto-populate fills the wish list for you

When you create a brand new plan, the wish list is empty. Click Auto-populate and the app fills it in for you. It looks at three things, in order, for each master category:

Recurring bills that will fire in the period (rent, Netflix, salary). Their amounts are added up.
Your last 3 months of activity, averaged. Used for categories that don't have a recurring bill.
Whatever you've already booked in this period, blended in with the past 3 months so the suggestion reflects your most recent reality. A category can be seeded from current-period activity alone, even if it has no 3-month history.

Each row in the plan shows where its number came from: a recurring template, your history (labeled "Auto"), or a manual edit you made.

Variance: did you stick to the wish list

Variance compares your plan to what actually happened.

You planned 600 for groceries and spent 400 so far. Variance is 200 under plan, shown in green. You have room to spare.
You planned 600 for groceries and spent 700. Variance is 100 over plan, shown in red. You went past the number you wrote down.
For income, the colors flip. Earning more than you planned is good (green), earning less is amber or red.

Projected: the app's best guess for end of month

The Projected number on the dashboard is a totally different idea from the plan. The plan is what you want to spend. Projected is what the app thinks will actually happen by the end of the month, given everything it can already see. It is the sum of:

Settled: what has already cleared.
Pending: charges that have been booked but not yet cleared (a card swipe waiting on the statement, a manual upcoming expense you typed in).
Scheduled recurring: every recurring bill that will fire from now until the end of the period.

Projected is not Planned Income minus Planned Expenses. It can be higher than your plan if pending charges or upcoming recurring bills are bigger than you expected, or lower if life has been quiet and not many bills are scheduled. Treat Projected as a heads-up, not a verdict. The dashboard's On Track verdict reads from what has actually settled, so a noisy projection won't alarm you before any money has moved.

Refresh from sources: re-check after life changes

Auto-populate is for the very first fill. Refresh from sources is for later. Use it when something about your setup has changed since you first built the plan. Maybe you added a new subscription, ended an old one, edited the amount of a recurring bill, or imported new transactions that should feed the average.

Refresh drops every row whose source is Recurring or Auto (the rows the system filled in) and re-runs Auto-populate against today's templates and history. Rows you typed or edited yourself are kept untouched. Categories that have shown up since the first populate will be added in this pass too.

Refresh from sources is part of the details view on the Forecast Plans page (turn on Show details to see it). On a draft plan, Refresh runs immediately. On a finalized plan, Refresh opens an Edit and refresh confirmation that reverts the plan to draft, refreshes the auto-generated rows, and keeps the lines you added or edited yourself. If the refresh step fails after the revert, the plan is left in draft and the error is shown so you can retry or continue editing manually.

Admin workflows

Renaming the org. Owners can rename the organization from Settings. Names are unique case-insensitively across the platform, and the change is captured in the audit log.
Inviting members. Owners and admins can invite people by email. Invitees receive a link, set up an account, and join the org with the role chosen at invite time.
Managing roles and permissions. Superadmins can review and edit platform roles and the permissions attached to each, from the Admin area.
Viewing the audit log. Superadmins can browse the audit log to see security and admin events (logins, role changes, org renames, deletions).
Toggling org settings. Settings holds org-level preferences (billing cycle, defaults) that influence how periods are computed and how new transactions are filed.

System health

When something feels off (slow loads, missing data, dashboard not updating), superadmins can check the Admin dashboard's System health card. It reports the live status of the database and Redis, including latency. Failures there usually explain whatever the rest of the app is doing.

Dashboard

The Dashboard is the household summary screen. The On Track hero tile reads from what has actually settled in the current billing period, so it stays calm even when pending charges or upcoming recurring bills make the projection jumpy. Below the hero, the Accounts strip shows balance plus pending per account, and a Forecast card shows the expected month-end balance for each account. Three cards underneath summarize spending by category, budget progress, and forecast by category. Use the period nav at the top to step through past or future periods; the donut and bars are filterable by category. For variance numbers, source attribution, and the planned-vs-actual chart, open Forecast Plans and turn on Show details.

Transactions

The Transactions page lists every booked row in the selected billing period. Click a row to expand the inline editor, where you can change description, amount, dates, category, status, and notes without leaving the list. From the same row you can promote a transaction to a recurring template, convert it into a transfer leg by selecting its counterparty account, or attach tags. Use the toolbar to filter by status, account, or category, and to sort the columns. Imports land here as a preview first, so nothing is committed until you confirm.

Transfers and paying a credit card

A transfer is money moving between two of your own accounts (checking to savings, checking to credit card, and so on). Transfers are not income or expense: they do not change your net position, so the app tracks them as a paired movement and keeps them out of category-level spending totals.

How transfers are categorized

Both legs of a transfer share one category. That category has to be transfer-compatible (its type is "both"), so it works on the outgoing leg as well as the incoming leg. The transfer form filters the category picker to just these transfer-compatible categories. If you leave the picker empty, the app uses the built-in Transfer category, which is enough for most setups.

Paying a credit card bill

A credit card payment is a transfer, not an expense. The spending already happened when you swiped the card. Paying the statement moves cash from your bank account to your credit card account, which clears the card balance back toward zero.

Card purchases (groceries, gas, restaurants) stay as regular expenses on the credit card account. Categorize them the way you would any other purchase.
Paying the statement is a single transfer from your bank account to the credit card account. Use Add transfer (or Mark as transfer on an existing pair).
If you want to see card payments broken out separately from generic transfers, pick Credit Card Payment (or create another transfer-compatible category) from the transfer form. Both legs will use that category. The picker shows only categories that work on both legs, so expense-only categories like Debt Repayment or Credit Cards cannot be used on a transfer.

Heads up: an expense-only category (for example "Debt Repayment / Credit Cards") cannot be used on a transfer. The picker hides those choices on the transfer form, and the backend rejects them on the API, since an expense-only category cannot apply to the incoming leg that lands on the credit card account.

Recurring transactions

The Recurring page lists every template you have set up, split into Active and Paused. Templates are created by promoting an existing transaction (open the row on the Transactions page and use "Promote to recurring"); they are not authored directly here.

Generate this period

"Generate this period" fills the current billing cycle with this period's recurring transactions, materializing an occurrence for every active recurring template that falls within the cycle. Items due later in the period appear as pending until their date arrives, so you can forecast a credit card statement that has not closed yet. Run it whenever you want this period's recurring rows to appear; they are not created automatically. Stopping a template removes its remaining pending future rows; settled past rows are kept because they are real money movements.

Accounts

Accounts represent your real-world money containers: bank accounts, credit cards, cash, savings. Each account has a type, a currency, and a balance derived from its transactions plus pending items. Credit-card accounts also carry a close day, which drives the billing period for charges on that card. From here you can add new accounts, set the default one (it shows first on the Dashboard strip), close an account, or post a manual balance adjustment when the in-app total drifts from the bank's.

Budgets

Budgets are the current-period control surface: a number per category that represents the cap you want to spend against for this period. The bar chart on the Budgets page colors each row by utilization (under, near, over), and the Dashboard's Budget Progress card pulls the same numbers. Budgets are scoped to the open billing period. For future periods, use Forecast Plans instead, and click From Forecast to seed the current period's budgets from the matching plan.

Forecast Plans

Forecast Plans is where you build and adjust the wish list of what you expect to spend and earn per category for a billing period. Auto-populate fills the plan from recurring bills, your last 3 months of activity, and anything already booked in the period. The Show details toggle reveals variance, source attribution, the planned vs actual chart, and Refresh from sources, which re-runs auto-population while preserving rows you typed yourself. See the Forecasts section above for the full mental model of plan vs projected vs variance.

Admin

The Admin area is the platform-ops hub, visible only to users with platform permissions. The header summarizes live database and Redis health; the totals strip tracks orgs, users, active subscriptions, and recent signups. The tiles below open the Organizations browser, the Audit log, and the Roles editor. Most destructive actions (subscription overrides, org deletes, tenant resets) are captured in the audit log automatically.

What's next, known gaps

This page is rough scaffolding, not a finished manual. Expect more depth here over time, with screenshots, edge-case notes, and better cross-linking. Areas that are intentionally light right now:

Reporting beyond the dashboard summary.
A side-by-side comparison page for budgets and forecasts.
Onboarding for first-time users.

← Home