PiggyBack

Your finances on autopilot with Up Bank. Auto-syncing transactions, budgets, savings goals, and a 35-tool AI financial assistant. Self-hosted on Vercel + Supabase.

Check out the live demo

Overview

PiggyBack syncs with Up Bank to automatically import your accounts and transactions, then provides tools to manage your finances. It features shared budgets with fair-split calculations, savings goal tracking linked to Up savers, recurring expense detection, investment portfolio tracking with live price updates from Yahoo Finance and CoinGecko, FIRE (Financial Independence) planning, and an AI-powered financial assistant.

Each user connects their own Up Bank account using a personal access token. All financial data is stored in the user's own Supabase database with row-level security -- no data is shared with third parties.

Features

• Up Bank Sync -- Automatic import of accounts, transactions, categories, and tags via webhooks
• Couples Partnership -- Shared financial view with your partner, income-weighted expense splitting
• Zero-Based Budgeting -- Category budgets with real-time spending tracking and period-aware calculations
• Savings Goals -- Visual progress tracking linked to Up Bank saver accounts
• Recurring Expenses -- Auto-detection and tracking of subscriptions and bills
• Investment Portfolio -- Track stocks, ETFs, crypto, and property with live price updates (Yahoo Finance for ASX/US stocks, CoinGecko for crypto)
• Watchlist -- Track investments you don't own yet with price monitoring
• Target Allocations -- Set portfolio allocation targets and see rebalancing recommendations
• FIRE Planning -- Australian two-bucket FIRE calculator with lean/regular/fat/coast variants
• AI Assistant -- Chat-based financial insights powered by your choice of Google, OpenAI, or Anthropic
• Net Worth Tracking -- Real-time snapshots via webhook with historical charts
• Customizable UI -- Multiple themes, accent colors, and layout configurations

Screenshots

Budget Tracking

Transaction Activity

Savings Goals

Investment Portfolio

FIRE Planning

Spending Analysis

Tech Stack

Getting Started

Prerequisites

• Node.js 20+
• npm or pnpm
• A Supabase account (free tier works)
• An Up Bank account (Australian neobank)

1. Clone the repository

git clone https://github.com/BenLaurenson/PiggyBack.git
cd PiggyBack
npm install

2. Set up Supabase

Create a new Supabase project, then apply the database migrations in order:

# Apply all migrations from supabase/migrations/ via the Supabase dashboard SQL editor
# or using the Supabase CLI

The supabase/migrations/ directory contains a single consolidated migration that sets up all tables, RLS policies, and functions.

3. Configure environment variables

Copy the example file and fill in your values:

cp .env.local.example .env.local

Required variables:

4. Run the development server

npm run dev

Open http://localhost:3005 to access the app. Make sure NEXT_PUBLIC_APP_URL in .env.local is set to http://localhost:3005 and your Supabase auth redirect URLs include the :3005 port.

5. Connect Up Bank

1. Sign up / log in to PiggyBack
2. Go to Settings > Up Bank Connection
3. Enter your Up Bank Personal Access Token (from the Up app or api.up.com.au)
4. Your accounts and transactions will sync automatically

Project Structure

PiggyBack/
├── src/
│   ├── app/              # Next.js App Router
│   │   ├── (app)/        # Authenticated pages
│   │   │   ├── home/
│   │   │   ├── activity/
│   │   │   ├── analysis/
│   │   │   ├── budget/
│   │   │   ├── goals/
│   │   │   ├── invest/
│   │   │   ├── plan/
│   │   │   ├── notifications/
│   │   │   └── settings/
│   │   ├── actions/      # Server actions
│   │   ├── api/          # REST API routes
│   │   └── auth/
│   ├── components/       # 125 React components
│   ├── lib/              # Business logic
│   │   └── __tests__/    # 50 test files
│   └── utils/
│       └── supabase/     # Client setup
├── documentation/
├── supabase/
│   └── migrations/
└── package.json

Up Bank API Usage

This app uses the Up Bank API for personal banking data. Per Up's API Acceptable Use Policy:

• The API is for personal use only
• Each user must use their own personal access token
• Tokens must not be shared with third parties
• Do not extract merchant data for commercial use

Your Up API token is encrypted at rest in the database and is never exposed in client-side code.

Running Tests

npm test          # Watch mode
npm run test:run  # Single run

The test suite covers 1120+ tests across 50 test files, including:

• Budget calculations (zero-based, shared budgets, period helpers, income frequency)
• Investment logic (price APIs, portfolio aggregation, FIRE calculations, invest calculations)
• Expense projections and matching
• AI tool definitions

Deployment

Two deployment guides are available:

• Deploy to the Cloud — Vercel + hosted Supabase (free tier, quickest setup)
• Deploy Locally — Docker + local or hosted Supabase (self-hosted, maximum privacy)

Documentation

Detailed documentation for contributors and developers:

See the full documentation index for details.

Security

PiggyBack takes security seriously. The project maintains an OpenSSF Best Practices passing badge and is continuously monitored by the OpenSSF Scorecard.

CI/CD Security Pipeline

Every push and pull request is scanned by:

All workflow files are in .github/workflows/.

Application Security

• AES-256-GCM encryption — Up Bank API tokens encrypted at rest
• Row Level Security (RLS) — All user-facing Supabase tables protected
• HMAC-SHA256 webhook verification — Timing-safe comparison for Up Bank webhooks
• Zod input validation — Schema validation on all server actions and API routes
• Content Security Policy — CSP headers configured in Next.js
• GitHub Secret Scanning — Push protection enabled to prevent credential leaks

Vulnerability Reporting

Please report security vulnerabilities privately via GitHub Security Advisories or see SECURITY.md for details.

Disclaimer

This software is provided for personal, non-commercial use. It is not financial advice. The developers are not responsible for any financial decisions made based on information displayed by this application. Always consult a qualified financial adviser for financial decisions.

This project is not affiliated with, endorsed by, or officially connected to Up Bank (Ferocia Pty Ltd / Bendigo and Adelaide Bank).

Users are responsible for compliance with Up Bank's Terms of Use and API Acceptable Use Policy, as well as applicable Australian privacy and consumer data laws.

Contributing

Contributions are welcome! Please read:

• CONTRIBUTING.md — setup guide, workflow, and code standards
• CODE_OF_CONDUCT.md — community guidelines
• SECURITY.md — how to report vulnerabilities

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

• Up Bank for their excellent banking API
• Supabase for the backend platform
• Next.js and the React ecosystem
• shadcn/ui for the component library
• Vercel for hosting and deployment