Financial Planner
Personal finance planner: a Next.js web app in web/, deployed on Vercel
at https://fse-group-project.vercel.app, with Supabase for the database and
login, and a bank connection through Tink (Demo Bank sandbox). The database
and the app's server routes both run in Ireland: Supabase in eu-west-1 and
Vercel Functions in Dublin (dub1, set under Settings → Functions on Vercel).
To check it, the x-vercel-id response header contains dub1.
The project documentation (user stories with acceptance criteria, the Tink
integration, decisions) starts at docs/README.md.
How to evaluate
Nothing needs to be installed.
- Open https://fse-group-project.vercel.app and log in with
[email protected] and password demo-planner-2026. This login is public on
purpose and owns only sandbox data (demo login).
- Look at the dashboard (balances, income and spending per month, spending
by category), Transactions (filter, search, change a category, export
as CSV) and Manage bank (connection status, Refresh data).
- If the bank page says the connection has expired: the saved accounts and
transactions stay visible. Tink's free sandbox deletes its users (see
known limitations). Click Reconnect bank, choose
Tink Demo Bank in Tink Link and log in with a Tink Demo Bank test user;
the import starts by itself when you return.
- Each user story names the code that implements it and the tests that check
it: docs/user-stories.md.
Project structure
web/ Next.js app: pages, API routes, components (see web/README.md)
src/
features/ Shared JavaScript: categorisation and exact amounts; auth/ is unused (see Authentication)
lib/supabase/ Supabase client for the shared code
supabase/
migrations/ Database schema, applied in file-name order
seed.sql Demo login and sample data
seed-data/ Category list; seeds/ holds the SQL generated from it
functions/_shared/tink/ Tink client and bank-data rules, used by the web app
tests/ Tests for the shared code; tests/database/ checks the database
docs/ Project documentation: user stories, Tink integration, decisions, data model
Supabase setup
The web app has its own settings file; see web/README.md. For the scripts in
scripts/, copy .env.example to .env.local and add your Supabase project
URL and publishable key. Never put a Supabase secret or service-role key in
client-side environment variables.
Authentication
The web app logs in with @supabase/ssr directly: email and password in
web/app/login/page.tsx, and Google login finished on the server in
web/app/auth/callback/route.ts. See web/README.md.
src/features/auth/ is an earlier, framework-neutral login service written
before the web stack was chosen. The web app does not use it; only the manual
check scripts/try-login.mjs and its own tests in tests/ do.
Google OAuth configuration
The web app runs on http://localhost:3000 locally. Google sends the user back
to Supabase, and Supabase then sends them to the app's /auth/callback.
- In Google Auth Platform, set up branding (app name, support email) and
choose the External audience.
- Create an OAuth client of type Web application:
- Authorized JavaScript origins:
http://localhost:3000 (plus the Vercel
URL once deployed).
- Authorized redirect URIs: the Supabase callback shown in
Authentication > Sign In / Providers > Google, of the form
https://<project-ref>.supabase.co/auth/v1/callback.
- Enable Google in Supabase > Authentication > Sign In / Providers and
enter the Google client ID and secret there. Never add the client secret to
this repo.
- In Supabase > Authentication > URL Configuration, set the Site URL to
the app's address and add the app to the Redirect URLs, for example
http://localhost:3000/** (plus https://<vercel-app>.vercel.app/** once
deployed). Use the wildcard form: the app asks to return to
/auth/callback?next=/dashboard, with a query string attached.
- While the Google app is in Testing mode, only the Google accounts listed
under Audience > Test users can log in. Add the team (and the examiners
for the presentation), or publish the app; with only the basic sign-in
scopes, Google does not require a review.
The same Google OAuth flow handles both login and registration. A first-time
Google user is registered in Supabase Auth; an existing user is logged in. The
web app exposes this flow on both /login and /register.
Bank data (Tink)
The bank connection runs in the web app, in the server route web/app/api/tink
with web/lib/tink.ts; its settings and setup are in web/README.md. A GitHub
Actions schedule (.github/workflows/bank-sync.yml) also updates every user's
bank data four times a day through web/app/api/cron/bank-sync. The Tink
code it uses lives in supabase/functions/_shared/tink/ (the folder name comes
from an earlier plan to run it as Supabase Edge Functions). client.ts talks
to Tink, consents.ts decides when a bank permission must be renewed, and
errors.ts decides what the user is told when the bank or Tink fails.
convert.ts turns Tink's accounts and transactions into our rows (amounts
as integer cents from Tink's varying decimal scale, booked/pending status,
transfer flag); reconcile.ts decides which stored transaction each
incoming one is, so a repeated sync never duplicates rows. Both are pure
functions with tests in tests/tink/, run against 309 real Demo Bank
transactions in tests/fixtures/.
Known limitations
- Tink's free sandbox deletes our users. Tink keeps users and their data
longer than 24 hours only for Enterprise customers with permanent users (Tink
Docs);
our sandbox app is not one. By 24 October 2026, 6 of the 7 app users with a
bank connection had lost their Tink user at least once (Tink answers
USER_NOT_FOUND). In a controlled test, two users connected on 23 October
were still there after 10 hours and gone after 38 hours, untouched. One user
created on 2 October has not been deleted; we don't know why. We ruled out our
own code (no version of it ever deleted a Tink user) and two people sharing
one Demo Bank login (two app users on the same Demo Bank login stayed healthy
side by side). Support is not available to sandbox apps. Effect: the app asks
the person to reconnect; their saved accounts, transactions and categories
stay. An hourly read-only check on 26 and 27 October saw this happen: one
user's Tink user disappeared between 14:58 and 08:53 UTC; the app marked the
connection expired and kept all 3,582 saved transactions. The demo login was
not affected.
- Demo Bank only. The bank connection refuses to start with
TINK_TEST_MODE=false. Real banks would need a commercial and regulatory
arrangement with Tink, code changes and testing against real banks.
- Euro only. Only banks in the EU with accounts in euro are in scope
(team decision, 25 October 2026). Totals add up amounts without converting
currencies, so an account in another currency would make them wrong.
- One bank per user. After the first bank is connected, the app offers
only Manage bank for it, not a second bank.
Remaining security limitations
- Administrators can read every user's profile, including name and
address (policy "Admins read profiles"). The admin page itself shows only
the username. The team accepts this
(user story 12).
- The demo password is public on purpose, so the examiners can log in. The
demo login owns only sandbox data.
- No multi-factor login. Email and password, or Google.
main is not protected on GitHub. Reviews and green checks before
merging are a team rule (AGENTS.md), not enforced by GitHub.
Checks
Needs Node 24 or later.
npm test # unit tests
npm run typecheck # TypeScript type check
npm run check:category-seed
CI also builds a throwaway database from the migrations and seed files and
runs the checks in tests/database/ against it: data, ownership and
cascade rules in the database itself (db-check.sql), and the access rules
through the real Auth and Data API (rls-check.mjs). Locally, with Docker and
the Supabase CLI:
supabase start
eval "$(supabase status -o env)"
psql "$DB_URL" -f tests/database/db-check.sql
node tests/database/rls-check.mjs "$API_URL" "$PUBLISHABLE_KEY"
AI coding agents
Rules for every coding agent working in this repository, and for the people
instructing them, are in AGENTS.md: no direct pushes to main,
no secrets in Git, a person types the bank login, and the data rules learned
from live Tink data. The agent configuration is versioned here:
AGENTS.md, CLAUDE.md (points to AGENTS.md) and
web/AGENTS.md (notes for the Next.js app).
- Data the agents see: the project holds no real bank data; all bank data
is Tink sandbox data (the Demo Bank). Agents work in the repository and,
only when a team member asks, run read-only checks on the hosted database,
which holds the team's own test accounts. Secrets stay in git-ignored local
files; agents must not print them or ask for them.
- Same bar as human code: AI-written changes go through the same pull
request template (with its "AI use" section), the same CI checks and a
teammate's review. Their commits end with a
Co-Authored-By: line naming
the agent.
Categories
Category names, keyword rules, and ignored test descriptions are maintained in
supabase/seed-data/transaction-categories.json. The dashboard sorts
transactions into categories with this list (web/lib/data/dashboard.ts); a
category set by hand on the transaction takes precedence.
The same list fills the category tables of migration 008 through a generated,
idempotent SQL seed. Regenerate or verify it with:
npm run generate:category-seed
npm run check:category-seed
Bank data reaches the database only through the Tink sync, which uses the
categorisation and exact-amount helpers in
src/features/transactions/transaction-rules.js. See
docs/fintech-erm.md for the data model.
