Portfolio: personal investment & finance tracker
A private, mobile-first web app for tracking investment accounts, valuations, contributions, holdings and performance. GBP by default, UK date formats.
Stack: Next.js 15 (App Router, TypeScript) · Tailwind CSS + shadcn/ui-style components · Supabase (Postgres, Auth, RLS) · Recharts · decimal.js · Vitest · Vercel.
You can try everything without any setup: run it locally and choose Explore with demo data. Demo data lives only in your browser's storage and never touches the database.
What works
- Dashboard: total value, contributions, withdrawals, net contributions, investment gain/loss, time-weighted return and XIRR; portfolio value chart (1M / 3M / 6M / 1Y / All) with net-invested line and estimated points marked; accounts with latest values; allocation by account, asset class and holding; largest holdings; recent activity; best/worst performers; discrepancy warnings.
- Accounts: create, edit, archive, delete; ISA, LISA, Cash ISA, SIPP, workplace pension, GIA, cash savings, Premium Bonds, crypto, other. Provider, private reference (masked), currency, date opened, notes. Two valuation modes:
- Manual valuations: record snapshots whenever you like. Snapshots are never overwritten; you can edit or delete them explicitly.
- Calculated from holdings: holdings × latest prices + uninvested cash. Save the calculated value as a snapshot to build history.
- Transactions: contributions, withdrawals, transfers between your accounts (stored as two linked legs, edited/deleted together), buys, sells, dividends, interest, fees, adjustments. Optional linked holding, units, price and fees. Filters by account, type, date range and text; pagination; monthly and yearly deposit/withdrawal totals.
- Holdings: stocks, ETFs, funds, investment trusts and more, in UK (GBX/GBP) and US (USD) listings. Enter units and average price directly, record trades, or both. Average-cost cost basis, unrealised and realised gain, dividends, price source and last-update time. Sortable table on desktop, cards on mobile. Watchlist.
- Market prices: fetched server-side, cached, rate-limited, clearly labelled (delayed / previous close / manual / demo, market closed). Manual price fallback and refresh button.
- Daily history (weekday evenings, Vercel Cron →
/api/cron/daily): stores each investment's closing price in price_history (UK funds backfill a year on the first run) and saves the calculated value of every holdings-valued account as a snapshot. Each holding shows a value-over-time chart and 1M/3M/6M/1Y price returns.
- Insights: value over time, gain/loss over time, contributions vs withdrawals, account performance comparison, per-account performance table, allocation charts.
- CSV export: transactions (respects filters), holdings, valuation snapshots, account summaries.
- Credit cards: the statement/due-date tracker from the previous version, now per-user.
- Loading skeletons, empty states, confirmation dialogs, toasts, form validation, dark mode (follows the system).
How the numbers work
Full explanation is in the app under Settings → How the numbers are calculated. In short:
| Concept | Rule |
|---|
| Account value | Exactly one value per account: the latest snapshot (manual accounts) or holdings × price + cash (calculated accounts). Holdings in a manually valued account are compared with the snapshot but never added on top. |
| External flows | Only deposits and withdrawals. Transfers between your own accounts count for each account but cancel out in portfolio totals. Buys/sells/dividends/interest/fees are never contributions. |
| Starting point | Contributions recorded before the first valuation → start from £0. Otherwise the first valuation (less any contributions that same day) is the opening balance. |
| Gain/loss | current value + withdrawals − contributions − opening balance |
| TWR | Valuations split history into sub-periods; each uses Modified Dietz with day-weighted flows; sub-periods are chain-linked. Marked Estimate when inputs are interpolated or large flows fall in long gaps. Annualised once a year of data exists. |
| XIRR | Money-weighted annual return on your actual cash flows (Newton–Raphson with bisection fallback). |
| History | Between valuations, values are interpolated (adjusted for flows in between) and shown as hollow chart points. |
| Precision | All arithmetic via decimal.js; database uses numeric, never float. |
The calculation engine lives in src/lib/finance/ and is pure TypeScript with no UI dependencies.
Tests
npm test # unit tests: money, flows, TWR, XIRR, holdings, portfolio model, CSV, price parsing
npm run typecheck
npm run lint
Tests cover decimal safety, flow classification (transfers and trades are not contributions), the gain formula, TWR (including a deposit-neutral case), XIRR against a published spreadsheet example, average-cost holdings with fees, pence/USD conversion, no double counting of holdings vs snapshots, interpolation, and same-day valuation/contribution ordering.
Database setup (Supabase)
All tables live in their own finance Postgres schema, so the app can share a Supabase project with other apps (it currently shares the My House Dashboard project) without touching their tables. Sign-in uses that project's existing accounts.
- Apply the schema (already done for My House Dashboard), either:
- SQL editor: paste each file in
supabase/migrations/ (in order) into SQL Editor → New query and run it; or
- CLI:
npx supabase link --project-ref <ref> then npx supabase db push.
- Project Settings → Data API → Exposed schemas: add
finance (keep the schemas already listed). Without this the app can't reach its tables.
- Authentication → URL Configuration: add
http://localhost:3000/** and https://your-app.vercel.app/** to Redirect URLs. Leave the Site URL as it is if another app already uses it.
- Open the app and sign in with your existing account for that project (or create one).
The schema creates accounts, account_snapshots, assets, holdings, transactions, market_prices, fx_rates, credit_cards and credit_card_bills, with foreign keys, check constraints and indexes. Row Level Security is enabled on every table: each user can only read and write their own rows, and child rows can only reference the same user's parents (composite foreign keys). market_prices is readable by signed-in users and writable only with the service role. A create_transfer function writes both legs of a transfer atomically. The schema doesn't add triggers to auth.users or anything to public.
There's no SQL seed for real data on purpose: demo data is generated in the browser (src/lib/data/demo.ts) so it can never mix with your records.
Environment variables
Copy .env.example to .env.local and fill in:
| Variable | Where | Required | Get it from |
|---|
NEXT_PUBLIC_SUPABASE_URL | browser + server | For real data | Supabase → Project Settings → API → Project URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | browser + server | For real data | Same page → anon public key (safe to expose; RLS protects data) |
SUPABASE_SERVICE_ROLE_KEY | server only | For the daily job | Same page → service_role (secret) key. Lets the server write the shared price cache, price history and daily valuations. Never expose it. |
CRON_SECRET | server only | For the daily job | Any long random string. Vercel sends it to /api/cron/daily; other callers are refused. |
ALPHA_VANTAGE_API_KEY | server only | For live UK prices | Free key at alphavantage.co |
FINNHUB_API_KEY | server only | Optional | Free key at finnhub.io (US tickers) |
EODHD_API_KEY | server only | For UK fund prices | Free key at eodhd.com (unit trusts/OEICs by ISIN) |
Without the Supabase variables the app runs in demo mode only. Without SUPABASE_SERVICE_ROLE_KEY and CRON_SECRET the daily history job doesn't run. Without market data keys, prices fall back to manual prices (or cost) and are labelled.
Local development
npm install
cp .env.example .env.local # optional: add Supabase + API keys
npm run dev # http://localhost:3000
Choose Explore with demo data on the sign-in page to use sample data. Settings → Reset demo data restores it.
Deploying to Vercel
- Push the repository to GitHub and import it at vercel.com/new.
vercel.json pins the framework to Next.js, so an existing project set up for the old Vite app builds correctly.
- Add the environment variables above under Settings → Environment Variables (Production and Preview).
- The daily job is scheduled in
vercel.json (21:00 UTC, Monday to Friday) and needs SUPABASE_SERVICE_ROLE_KEY and CRON_SECRET.
- Deploy, then put the production URL into Supabase's Site URL / Redirect URLs (step 3 above).
Market data: choices and limitations
Researched October 2026 (free tiers):
| Provider | Free allowance | UK (LSE) | US | Freshness |
|---|
| Alpha Vantage (used) | 25 requests/day, 5/min | Yes (VUSA.LON) | Yes | Delayed / end of day |
| Finnhub (optional, US) | 60 requests/min | No (paid) | Yes | Delayed |
| EODHD (optional, UK funds) | 20 requests/day | Funds by ISIN (EUFUND) | — | End of day |
| Twelve Data | 800/day, 8/min | No (US only on free plan) | Yes | — |
- Prices are not real-time. They're labelled Delayed or Close , with a closed marker outside exchange hours (LSE 08:00–16:30 UK, US 09:30–16:00 ET; holidays aren't modelled).
- Alpha Vantage's 25 requests/day is the binding limit. Prices are cached (15 min while the market is open, 6 h when closed) in the
market_prices table, at most 5 symbols are fetched per refresh, and only signed-in users can call the price API. With many holdings, refresh in batches or set manual prices for funds.
- LSE quotes are usually in pence (GBX). Set Quoted in per investment (the form guesses from the ticker). Some LSE ETFs quote in GBP or USD.
- Unit trusts/OEICs (most UK funds) have no ticker. Enter the fund's ISIN (e.g.
GB00BG0QP604) as the ticker and add an EODHD_API_KEY to fetch its daily price; the form assumes pence (GBX), so compare the first price with your platform and switch Quoted in to GBP if it's 100× off. Without a key, use a manual price.
- Exchange rates come from the ECB via Frankfurter (free, no key, daily). Historical values in other currencies are converted at today's rate, and foreign holdings' gains exclude currency movements.
- Market data calls couldn't be exercised from the build environment (outbound access to the providers was blocked); response parsing follows the providers' documented formats. Check the Holdings page after adding your key.
Project structure
src/
app/ routes (dashboard, accounts, holdings, activity, insights, settings, login, API)
components/ UI primitives (ui/), charts, forms, layout, shared lists
lib/finance/ calculation engine + tests
lib/market/ price providers, cache, FX, market hours (server)
lib/data/ repositories (Supabase / browser demo) and demo data
supabase/migrations/ database schema
Changes from the previous version
The earlier Vite + React app was rebuilt on Next.js so price API keys stay on the server. Its features (pots with values and contributions, share transactions, credit card bills) are covered by accounts, snapshots, transactions, holdings and the credit cards page. One behavioural change: data is now private per user (the old schema shared all rows between any signed-in users). The old schema files are in git history; there was no existing database to migrate.
