Open source personal finance application
Finapp
Personal finance app. Nuxt 4, Vue 3, Pinia, @nuxt/ui v4 (Tailwind CSS v4), Supabase (Postgres) backend, PowerSync offline-first sync, Supabase Auth (email/password + Google OAuth). Repo is a pnpm monorepo: app/ (@finapp/app, Nuxt source under app/app/, Supabase config under app/supabase/, self-hosted PowerSync under app/powersync/) and docs/ (@finapp/docs).
- Node.js >= v24.12.0
- Package manager: pnpm
- SPA mode (
ssr: false) - PWA with
generateSWstrategy from@vite-pwa/nuxt
Commands
pnpm dev- Nuxt dev server on port 3050- Local backend (run once, in
app/):supabase start(Postgres + Auth on :54321), thendocker exec -i supabase_db_app psql -U postgres -d postgres < supabase/powersync_setup.sql(replication role + publication), thendocker compose -f powersync/docker-compose.yaml up -d(PowerSync service on :8080) pnpm build/pnpm generate- both runnuxt generate(static SPA, output.output/public)pnpm lint/pnpm lint:fix- ESLintpnpm test- Vitestpnpm test:e2e- Playwright against the dev server;pnpm test:e2e:prod- Playwright against the prod buildpnpm docs:dev/pnpm docs:build- docs site
Deploy
- Single Vercel project for the app, two environments by git branch:
main→ Production (prod Supabase backend), any other branch (usedev) → Preview (per-branch preview URL on the test Supabase backend). Pushing a branch auto-builds its Preview. Concrete project/backend identifiers live in Vercel env + the gitignored.vercel/, not here. - Manual deploys: run
vercel deployfrom the monorepo rootapps/mono(never fromapp/; project root directory isapp). No flag = Preview,--prod= Production.
Conventions
- Components: PascalCase, grouped by feature in
components/[feature]/ - UI primitives in
components/ui/ - Imports use
~/alias (resolves toapp/app/) - ESLint flat config with
@antfu/eslint-config, Perfectionist for sorting - Prettier with Tailwind plugin, single quotes, no semicolons, trailing commas
- i18n:
no_prefixstrategy, two locales (en-US, ru-RU) - Always run
pnpm lint:fixbefore committing
Backend: Supabase + PowerSync
- Postgres schema migration:
app/supabase/migrations/- tablescategories,wallets,trns,user_settings,rates. All id columns aretext(client-generated UUIDs, no FK constraints - PowerSync upload order is not guaranteed). Columns are camelCase (quoted) to match the client item shapes. RLS scoped toauth.uid(). A trigger auto-createsuser_settingson signup. - PowerSync replication setup:
app/supabase/powersync_setup.sql(apowersync_rolewith REPLICATION + BYPASSRLS, and apowersyncpublication). - Self-hosted PowerSync service:
app/powersync/(docker-compose.yaml,config/service.yaml,config/sync-config.yaml). It replicates the Supabase Postgres and validates Supabase JWTs via the JWKS endpoint. Sync rules are per-user (WHERE "userId" = auth.user_id()). - Exchange rates: the
ratestable is populated server-side by thefetch-ratesedge function (app/supabase/functions/fetch-rates/) - Coinbase (base, fiat + crypto) + OER (fiat overlay, needsOPEN_EXCHANGE_RATES_KEYsecret) merged into one dailysource='merged'row. Scheduled viapg_cron(migration*_schedule_fetch_rates.sql, 06:00 UTC), which reads the function URL + anon key from Vault secretsproject_url/anon_key. Clients never write rates. TrnTypeinapp/app/components/trns/types.ts: Expense (0), Income (1), Transfer (2).- Adjustment is determined by
categoryId === 'adjustment', NOT byTrnType. It uses Expense or Income type, excluded from income/expense statistics.categoryIdalso holds the literal'transfer'for transfers.
Client data layer
app/services/powersync/-AppSchema.ts(client SQLite schema),db.ts(lazygetPowerSyncDb()singleton - dynamically imports@powersync/webto keep it out of the entry chunk - plusconnectPowerSync/pausePowerSync/watchTable/waitForFirstSync),connector.ts(SupabaseConnector:fetchCredentials+uploadData; reachable only via the dynamic import in db.ts),uploadReconcile.ts+uploadErrorHandler.ts(auto-reconcile of fatally rejected uploads),transforms.ts(row↔item: booleans 0/1,parentIdnull↔0,ratesJSON),mutations.ts(upsertRow/deleteRow/deleteTrnsReferencing- INSERT/UPDATE, neverON CONFLICT, since PowerSync tables are views).app/app/composables/useSupabase.ts- the supabase-js client +useSupabaseAuth()(reactive session,signInWithPassword/signUp/signInWithGoogle/signOut).detectSessionInUrl: trueso the Google OAuth PKCE?code=is exchanged on return to/login(handled inlogin.vue).app/app/plugins/powersync.client.ts- eagerly opens local SQLite for an already-logged-in user, then connects PowerSync when the auth session (uid) resolves. On involuntary session loss (token revoked/expired) it pauses sync (pausePowerSync: keeps local SQLite + the unsynced queue) rather than wiping, surfacing a re-auth toast when writes are pending; only an explicit sign-out (useUserStore.signOut) wipes. The synchronous route-guard gate ishasPersistedSession()(app/app/composables/useAuthSession.ts), which reads the persisted Supabase session from localStorage directly - no cookie. Local row writes stampuserIdviaresolveWriteUid(same file), which falls back to the persisted uid so an offline cold start before the session resolves doesn't write an emptyuserId(which RLS would reject).- Stores hydrate via
db.watch('SELECT * FROM ...')(one subscription handles both initial load and realtime, local + synced) and write viaupsertRow/deleteRow. Demo mode bypasses PowerSync and uses in-memory + localforage.
Documentation
- Setup, env vars, scripts:
README.md - Architecture, store pattern:
docs/content/en/3.reference/
graphify
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
Rules:
- For codebase questions, first run
graphify query "<question>"when graphify-out/graph.json exists. Usegraphify path "<A>" "<B>"for relationships andgraphify explain "<concept>"for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run
graphify update .to keep the graph current (AST-only, no API cost).