Read Me First

A plain-language introduction to the Personal Finance & Investment Tracker — called PFTracker on screen. If you have never seen this project before, start here. Nothing below assumes you write software.

One thing to say straight away, because it shapes everything else: this is an early, working core build. The money maths, the database and the screens are real and you can use them today. Some of the buttons that would let you put your own information in are still placeholders, and a few features need an account with an outside company before they can switch on. Every one of those gaps is named plainly in this document. Nothing here is oversold.

---

1. Who this is for

You, if your money lives in more than one place and no single app shows you the whole picture.

That usually means someone who has:

• a current account and a savings account, probably at different banks
• money invested — a workplace or personal retirement account, a brokerage account, maybe some cryptocurrency
• a home, with a mortgage against it
• some debts: a car loan, a credit card
• a partner who ought to be able to see all of it too

Budgeting apps handle the first item well and ignore the rest. Investment apps do the opposite. People in this position end up adding things up in a spreadsheet once a quarter, which is exactly the job this project is meant to take off your hands.

It is also for people who would rather their financial records not sit on somebody else's server. The whole thing can be run on a computer you own, with no connection to the outside world at all.

It is not for you if you want someone to tell you what to buy or sell. This project deliberately never does that. It shows you what is true about your money and explains what it noticed. The decisions stay yours.

---

2. What it does

It gathers every account you have — cash, investments, property, debts — into one place and gives you a single number: what you are actually worth. Then it lets you take that number apart until you can see exactly which account each piece came from.

Around that centre it does five more things. It sorts your spending into categories and tracks it against budgets you set. It spots the payments that repeat every month, and notices when one of them quietly gets more expensive. It shows what your investments are made of and how much you are losing to management charges over a lifetime. It works out roughly what you will owe in tax on investments you have sold, and produces the paperwork. And it lets you ask questions about your own finances in ordinary words and get an answer built from your real figures, with those figures shown so you can check them.

Everything it tells you is information and explanation. It is not financial, tax, or investment advice, and it says so on the screens where that matters.

---

3. The domain: personal finance and investment tracking

If this world is new to you, here is the ground it covers.

Net worth is the whole point. Add up everything you own — the money in your accounts, the value of your investments, what your house would sell for. Then subtract everything you owe — mortgage, loans, credit card balances. What is left is your net worth. It is the single most honest measure of financial progress, because it cannot be flattered by a good month's income.

Accounts come in two flavours, and the difference matters. An asset account holds something you own. A liability account records something you owe. A mortgage of $400,000 is a liability that cancels out most of the house it paid for, which is why looking at only one of them tells you nothing.

Transactions and categories. Every payment in or out is a transaction. To learn anything from them you have to group them — groceries, dining, transport, rent. That grouping is categorisation, and it is the tedious part of personal finance that software exists to do for you.

Budgets are simply a limit you set per category per month. The value is not the limit itself but seeing, mid-month, that you are already three quarters through it.

Investments have their own vocabulary. A holding is a quantity of something you own — shares in a company, units in a fund. Allocation is the mix: how much of your money sits in company shares versus bonds versus cryptocurrency. Concentration in one place is the risk everyone underestimates.

Fees deserve their own paragraph, because they are the quietest way to lose money. Investment funds charge a small annual percentage of whatever you hold with them. It looks trivial. Over thirty years, compounding, it is often tens of thousands. This project projects that number out for you, which most tools never show at all.

Return is how much your investments actually grew. It is harder to measure than it sounds, because money you paid in during the year also makes the balance go up. Proper measurement strips out the effect of your own deposits so you can see how the investments themselves did, separately from how much you saved.

Tax on investments is where most people lose track. When you sell something for more than you paid, the profit is a realised gain and is usually taxable. To calculate it you need to know what you originally paid — the cost basis — and how long you held it, because gains on things held over a year are normally taxed more kindly. Tax authorities also block a specific trick: selling something at a loss purely to claim the loss, then buying it straight back. Do that inside the restricted window and the loss is disallowed. That is a wash sale, and this project watches for it.

Tax rules here are United States rules. The tax estimate covers federal and state tax combined, based on your filing status, your tax band and your state. If you are outside the US, everything except the tax section still applies to you; the tax section will not.

Currency: this release works in one currency at a time, US dollars by default. Holding money in several currencies at once is planned, not built.

---

4. Where it fits

The people who use it. Most often one person doing their own finances, with a partner looking over their shoulder. Sometimes a financial adviser given read-only access by a client. Sometimes someone who simply refuses to hand their bank records to a subscription service and wants to run this on their own machine.

The outside services it works alongside. Three kinds, and all three are optional.

Banks and brokerages, reached through a service called Plaid. Plaid is a middleman that many finance apps use: you log in to your bank through Plaid's own secure window, and Plaid then supplies read-only balances and transactions. Your bank password is never seen by this project. The connection can only read; it can never move money. This needs credentials from Plaid, which you would have to arrange yourself. Without them, the connect-a-bank feature reports itself unavailable rather than pretending to work, and you use manual entry or file import instead.

Market data providers, which supply the daily price of shares, funds and cryptocurrency. These also need an account key. Without one, your holdings keep whatever value was last recorded, and the calculation of your investment return cannot run — the screen tells you it is waiting for prices rather than inventing a figure. Allocation and fee projections still work fine.

AI assistants, through something called MCP — a standard way for an assistant like a chatbot to be granted a peek at data held elsewhere. You can switch on a read-only connection and issue a token, which is like a long password you hand to the assistant. It can then read your net worth, your allocation, your accounts, your goals and your tax summary, and nothing else. It can never change anything. Every single read is written to a log that records it was an assistant, not you. You can revoke it whenever you like. This part is built and works today.

---

5. First run

The quickest honest way to see the product is the preview image — a single self-contained package that carries the application, its database and a complete set of realistic sample data for a fictional household. Nothing outside it is needed. It is meant for exactly this: looking.

You need Docker installed. Then two steps.

Step one — start it. Building the package is described in preview/README.md. Once built, this starts it and turns on the demo sign-in shortcut:

docker run --rm -p 4000:4000 -e PORT=4000 -e AUTH_LOGIN_BYPASS=true pftracker-preview:latest

(preview/README.md notes the bypass answers 404 — that is true of the image's defaults; the -e AUTH_LOGIN_BYPASS=true above is what switches it on, and it can never activate in a cloud/Kubernetes deployment.)

Give it fifteen to thirty seconds to set itself up.

Step two — open it. Go to http://localhost:4000/api/v1/auth/bypass in your browser. That long address is the demo sign-in shortcut; it drops you straight onto the dashboard as the sample household and you will not need it again. Open the plain http://localhost:4000 and you will see the app shell with every panel saying "Sign in to see your…" — each with a Sign in button that takes you to the sign-in page, which is the ordinary way in.

You will land as Jordan Rivera — a fictional person with eleven accounts, a house, a mortgage, a workplace retirement account, a brokerage account, a crypto wallet, and about twenty months of spending history. Net worth just under $492,000. Click through the nine sections in the left-hand menu; every number on every screen traces back to that sample data.

How signing in works. There is a sign-in page at /signin, reachable from every signed-out panel and from the sidebar, and it offers whichever ways in your installation actually has:

• On an appliance or in the cloud, the app delegates sign-in to the identity provider your destination already runs, so your password is never handled here. If you are already signed in with that provider — which on an appliance you usually are — the app recognises you on the first page load and takes you straight to your dashboard, without asking again. It tries that once and never loops: if nobody is signed in, you simply see the sign-in page.
• Running it offline on your own machine, the same page shows an email and password form, because there is no provider to delegate to.

Once you are in, your name sits at the top of the left-hand menu. Click it for a menu with your details and settings and Sign out. Signing out ends the session with the identity provider too, so the next sign-in genuinely asks.

The demo shortcut above is separate from all of this — it is how the project's own screenshots were taken, and it exists only in local containers you start yourself with -e AUTH_LOGIN_BYPASS=true. If you just want to evaluate the product, explore the demo household; that is what it is there for.

If a sign-in does not work, docs/login-troubleshooting.md lists the causes worth checking, in the order they actually happen.

Also note that the preview throws its data away when the container is removed, unless you deliberately attach storage to it. That is intentional for something you are only test-driving.

---

6. Setting up

This is the section to read if you want to go beyond looking, and it is the section where the honesty matters most.

Putting your own information in. In this build, the buttons on the Accounts screen — Link an institution, Add manual account, Import CSV / OFX — are placeholders. They are visible but not yet wired up. The same is true of New goal on the Goals screen and Invite a member on Settings. The machinery behind all of them exists and works; only the connection from the button to the machinery is missing. Until that lands, adding accounts and importing statement files is something a technically confident person does directly, or something you wait for.

For the same reason, you cannot currently correct a transaction's category in the browser. The list shows you the category it was given, but the inline edit is not there yet. The learning behaviour — correct a merchant once and future payments from that merchant are categorised the same way — is built, and will come to life when the editing control does.

File import, as designed. The intended route for any bank that cannot be connected automatically is to download a statement from your bank as a CSV or OFX file — both are ordinary statement formats every bank offers — and upload it. Re-uploading the same file twice will not create duplicate entries; the system recognises what it has already seen. This works in the engine; it is the upload button that is pending.

Keys for the optional services. Three separate things, each independently switchable, each needing an account you set up with the provider:

To get this	You need	Without it
Automatic bank and brokerage updates	Plaid credentials	Connecting reports itself unavailable; manual entry and file import instead
Live share, fund and crypto prices	A market-data provider key	Last known values are kept; investment return cannot be calculated
A properly written AI coach answer	An AI provider key	You still get the right figures, but almost no written explanation

That last one deserves expanding, because it is the easiest to misjudge. Ask the coach a question with no AI key configured and it will answer — correctly, from your real data, with the exact figures it used listed underneath. What it will not do is write you a paragraph. You get the numbers and the sources, without the prose. With a real key you get a proper explanation on top of the same verified figures.

Setting up a real environment. If you are standing this up properly rather than previewing it, the companion document production-initialization.md walks an operator through it: creating the first administrator account, the safety checks that stop the wrong database being wiped, and what to verify afterwards. Read §8, "Known limitation — per-user data keys are not durable", before putting genuine financial records in.

---

7. Day to day

Once your information is flowing in, the rhythm looks like this.

Most days, a glance. Open the dashboard. Read the one number. Under it, "Worth a look" lists what the software noticed overnight — that your share allocation has drifted above where you wanted it, that a loss on one holding is worth harvesting against this year's gains, that dining is running well above its recent average, that a subscription price went up. These are observations with the reasoning attached, not instructions.

Weekly, a tidy-up. Open Transactions and read down the recent entries. Look for anything you do not recognise, and for anything landing in the wrong category. The search box and the category filter narrow the list instantly as you type. Note that this screen shows your two hundred most recent transactions and tells you when there is older history behind them, and that the search works across that window rather than your whole history.

Monthly, the budget check. Open Budgets. Each category shows what you planned, what you actually spent, how much of the allowance is gone, and what is left, with anything overspent marked. Underneath, the recurring charges list — every repeating payment the software found on its own, with what it usually costs, when it last went out, how many times it has been seen, and a flag where the amount changed. That list is the single most reliable way to find subscriptions you forgot you had.

Occasionally, the investments. Open Investments for your mix by asset class, and for the fee section, which is the part worth returning to. It shows the blended annual charge across your holdings and then projects it over ten, twenty and thirty years, side by side with what you would have had without it. In the sample data a charge of four hundredths of one percent — a rounding error, to look at — costs about twenty thousand five hundred dollars over thirty years.

Now and then, a question. Open AI Coach and ask in plain words. "How much did fees cost me last year?" "Am I on track for my retirement goal?" "What's my largest spending category this month?" The answer arrives with the figures it was built from listed beneath it, so you can check every claim, and with a note that this is education rather than advice.

Goals, when your plans change. Each goal shows what is funded so far, your monthly contribution, and a likelihood of actually reaching the target by its date — worked out by running ten thousand simulated futures and counting how many arrive. It is deliberately blunt. In the sample data the retirement goal comes back around sixty-three percent likely and the two nearer goals come back under one percent. A tool that told you what you wanted to hear would be worth nothing.

---

8. Ongoing care

Every quarter, reconcile. Open each account's balance against what the bank itself says. Automatic feeds go stale, and this project marks accounts it is not confident about rather than quietly folding a wrong number into your net worth — but it is still worth your own eyes on it a few times a year.

Every quarter, prune. Work through the recurring charges list and cancel what you no longer use. This is the single highest-return habit the software enables.

Once a year, at tax time. Open Tax. It shows the year's realised gains split into short-term and long-term, dividends received, any wash sales flagged, and an estimated bill combining federal and state tax. One button downloads the detail as a spreadsheet in Form 8949 layout, which is the US form for reporting investment sales. Two caveats: the estimate is an estimate and the screen says so, and in this build the export identifies each row by an internal reference rather than the investment's name, so you will want to label the rows before handing it to anyone.

Twice a year, review your profile. The tax estimate depends on the filing status, tax band and state recorded in Settings. If any of those changed, the estimate is wrong until you say so.

Regularly, keep your own copy. Settings has Export all my data, which gives you everything the system holds about you in one download. Take one periodically. It is your insurance against every kind of loss, and it is also the thing that means you are never locked in.

Understand what deletion means here. Settings also offers to erase your account, and it is thorough: as well as removing your records it destroys the key that decrypts your sensitive information, so what remains cannot be read back. There is no undo. It asks you to type a confirmation word for exactly that reason.

A limitation to plan around. Right now the keys that protect your most sensitive stored items are held in the running program's memory rather than saved anywhere durable. In practice that means those protected items may not survive the application being restarted. This is documented rather than hidden, and it is the main thing to resolve before trusting the system with real long-term financial records. production-initialization.md covers it.

---

Glossary

Aggregation — automatically pulling balances and transactions in from your banks, rather than typing them.

Allocation — the mix of your investments across kinds of asset: company shares, bonds, cash, cryptocurrency.

Asset / liability — something you own; something you owe.

Cost basis — what you originally paid for an investment. Needed to work out the profit when you sell.

CSV / OFX — two ordinary file formats banks offer when you download a statement. CSV is a simple spreadsheet; OFX is a banking-specific version.

Expense ratio — the annual percentage an investment fund charges you for holding your money.

Fee drag — the total amount those small annual charges will have cost you over many years, once compounding is accounted for.

Form 8949 — the US tax form for reporting sales of investments.

Household — a group of people who share one financial picture, each with their own permission level.

MCP — an agreed standard that lets an AI assistant read data from another system with your permission. Here it is read-only and logged.

Net worth — everything you own minus everything you owe.

Plaid — the service that connects apps to banks securely, without the app ever seeing your bank password.

Realised / unrealised gain — profit you have locked in by selling; profit that exists only on paper because you still hold the thing.

Simulated projection (Monte Carlo) — running your plan through thousands of randomly varied futures to see in what fraction of them you reach your goal.

Tax-loss harvesting — deliberately selling something that has lost value, so the loss offsets a gain elsewhere and reduces your tax bill.

Time-weighted return — how much your investments grew, with the effect of your own deposits and withdrawals stripped out.

Wash sale — selling at a loss and buying the same thing back too soon. The tax authority disallows the loss.

---

The other documents

In this folder (user-docs/):

• READ-ME-FIRST.md — this document. Orientation for a first-time reader.
• production-initialization.md — for whoever is setting up a real installation. Covers creating the first administrator, the safeguards against destroying data, verification afterwards, and the encryption-key limitation described above. Written for a technical operator, not an end user.

Deeper guides (collateral/):

• user-guide/getting-started-plain-language.md — a friendlier step-by-step first walk through the product.
• user-guide/user-guide-detailed.md — the full manual, feature by feature.
• guides/installation.md, guides/self-hosting.md, guides/integration.md — installing it, running it privately with no outside connections, and connecting banks, price feeds and assistants.
• white-papers/ — four longer essays: cross-account tax optimisation, responsible AI in personal finance, privacy-first self-hosting, and fee drag. Read these for the reasoning behind the product rather than instructions.
• marketing/faq.md, marketing/one-pager.md — quick summaries.
• technical/ — architecture and data model, for developers.

Elsewhere: README.md at the top of the project is the developer-facing overview. preview/README.md covers the demo package in detail. The project specification lives under specs/. Bear in mind that these describe the full intended product; this document describes what is actually built today, and where the two differ, this one is the accurate one.

---

Who can see what: household roles

A household is how you share your financial picture without sharing any passwords. Members get one of three roles.

• Owner — full control. Can see and change everything, and manage who else belongs. The person who set the household up.
• Editor — can see everything and change things: add accounts, fix categories, set budgets. A partner who manages the money with you.
• Viewer — can see everything and change nothing. The right level for a financial adviser, or a family member you want kept informed.

Sharing is by role, never by handing over your login. No member ever sees any other member's bank credentials, because the system does not hold them in the first place. The role you have appears on your Settings screen. Note that the Invite a member button is one of the placeholders in this build.

---

The sample data, and starting clean

The preview package ships with one fictional household so that every screen has something real to show.

Jordan Rivera (demo@pftracker.app) is a married US taxpayer in California in the 24% tax band. The household has eleven accounts: a current account, two savings accounts, a workplace retirement account, a personal retirement account, a brokerage account, a crypto wallet, a house, a mortgage, a car loan and a credit card. Net worth just under $492,000, against about $925,000 of assets. There are roughly 550 transactions across about twenty months, eight monthly budgets, a dozen detected recurring charges, twelve investment holdings, records of investments sold, three goals, and five things the software noticed and flagged.

All of it is invented. No real person, bank or account is involved.

Two things to know about it. The sample transactions stop in July 2026, so if today is later than that the current month's budgets will read as untouched with every allowance full — the Budgets screen tells you this rather than leaving you guessing. And because there is no price feed configured, the investment return figure cannot be calculated, so that panel explains what it is waiting for instead of showing a number.

Starting clean. The preview is disposable by design: stop the container and its data goes with it. For a real installation you would not load the sample data at all — the setup routine described in production-initialization.md creates one administrator, one household and the standard spending categories, and nothing else. You begin with an empty dashboard and fill it with your own records.

---

Common questions and things that catch people out

Is my bank password stored anywhere? No. When a bank connection is used, you log in through the connecting service's own secure window and this project never receives your credentials. It only ever gets read access, and cannot move money.

Do I have to connect anything to the internet? No. Running it privately with no outside connections is a supported, deliberate mode. You lose automatic bank updates, live prices and the written AI explanations. Everything else — net worth, accounts, spending, budgets, allocation, fees, tax, goals — works offline.

Is this financial advice? No, and it is designed not to be. It shows you facts about your own money and explains what it noticed. It will not tell you what to buy or sell, and it repeats that beneath the screens where the temptation to read it as advice is strongest.

Why does the dashboard not show a graph of my net worth over time? The history is being recorded — a snapshot is taken regularly — but the trend chart is not in the interface yet. This build shows today's figure and its breakdown.

Why can't I click "Add manual account" or "Import CSV / OFX"? Those buttons are placeholders in this build. The capability exists underneath; the button is not connected to it yet. Same for New goal and Invite a member.

Why can't I change a transaction's category? The same reason. The edit control has not been built into the browser view yet.

The coach gave me numbers but barely any explanation. That is the offline fallback, used when no AI provider key is configured. The figures are correct and come from your real data; the prose is what is missing. Configure a key and the explanation appears.

Why does it say my investment return can't be calculated? Measuring return needs at least two priced valuations of your holdings. With no price feed configured, there is only one. The screen says what it is waiting for rather than showing you a zero and hoping you do not ask.

I imported the same statement twice — have I doubled everything? No. Repeated imports are recognised and will not create duplicate entries.

Someone shared their household with me and I can't change anything. You have the viewer role. Only an owner can change that.

Will re-running the setup script wipe my data? It refuses to run against a database that already has records unless you explicitly force it, and it makes you type a confirmation first. See production-initialization.md.

Can I trust it with my real finances today? Not yet, in a shared or long-lived installation — because of the encryption-key limitation described in section 8. Treat this build as a working core to evaluate, extend and brand, which is exactly what it is meant to be.

---

Where to get help

This project is part of the World's Biggest Software Project, a community building open applications like this one in the open.

Start at wbsp.ai. The community there can help you get it running, extend it, or fit it to how you actually work. Other members have built their own versions of this same application, and one of them may suit you better than this plain core does — it is worth looking before you build.

That plainness is deliberate. This is a foundation with the functionality real and the styling minimal, meant to be shaped and badged to a particular requirement. If you know this subject and can direct AI tools, you can take it from here yourself. If not, wbsp.ai will connect you with people who can.

---

Everything in this document was checked against the application as it actually runs. Where the product falls short of what the specification promises, this document says so. Nothing here is a forecast.