Quantum Flow Spend Tracker

This is an app to track and budget your spending. It's built with Next.js and supabase (postgres).

This is an alternative to products like Mint, etc. The purpose of this app is to track your spending without needing to connect all of your accounts to a 3rd party service. At the moment, it only supports American Express emails.

Login is with Google oAuth. There is an API that is used to get the user's transactions.

For American Express, you can turn on alerts for transactions over $1 and have it send an email. Have that email autoforwaded to Zapier and then trigger a webhook to the API. It will log the transaction to the database, and, try to guess the category of the transaction based on business name keywords.

You can also add transactions manually (or edit them). Technically, you don't have to use Zapier, you can just use the API to add transactions or add them manually in the UI. There are a million nerdy ways to solve this problem. You could also use IFTTT, but, not with gmail (or a google workspace account) because there's no way to confirm the trigger email. If you really wanted, you could even roll your own POP3/IMAP server and have it send a webhook to the API.

For the Zapier integration, I used a separate gmail account just for this purpose since the integration can read all of your emails after you give it permission.

There is a budget page that allows you to set a budget for each category.

There is a category page that shows the user's categories and their spending (and allows you to add, edit, and delete categories).

Getting Started

Requirements:

• Node.js
• Supabase postgres (hobby tier is fine). You could also use a traditional postgres database. To use a traditional postgres database, you will need to update the supabase client in src/lib/supabase.ts.
• Google oAuth API key (client ID and secret, configured in Google Cloud Console)
• Zapier webhook key (set in .env) - can by any random string, preferably long and random

See .env.example for the environment variables you need to set.

To run database migrations, first login to supabase and link to the project:

supabase login
supabase link --project-ref ${SUPABASE_PROJECT_ID}

Then run the following command to reset the database (which will run the migrations):

npx supabase db reset --linked

To run the development server:

npm run dev

By default, the development server will run on http://localhost:3000

To run the production server:

npm run build
npm run start

This can be deployed to Vercel or any other platform. If deploying elsewhere, you can run this in a Docker container.

Docker Deployment

To build and run the application using Docker:

1. Build the Docker image:

docker build -t quantum-flow-spend-tracker:latest .

2. Run the container:

docker run -p 3000:3000 \
  -e NEXTAUTH_URL=http://localhost:3000 \
  -e NEXTAUTH_SECRET=your_nextauth_secret \
  -e GOOGLE_CLIENT_ID=your_google_client_id \
  -e GOOGLE_CLIENT_SECRET=your_google_client_secret \
  -e [email protected],[email protected] \
  -e SUPABASE_URL=your_supabase_url \
  -e SUPABASE_SERVICE_ROLE_KEY=your_service_role_key \
  -e SUPABASE_PROJECT_ID=your_project_id \
  -e SUPABASE_ACCESS_TOKEN=your_access_token \
  -e ZAPIER_SECRET=your_zapier_secret \
  quantum-flow-spend-tracker:latest

Zapier integration:

• Create a new zap
• Add a gmail "search" trigger with a search term that matches AMEX emails (like Large Purchase Approved)
• Add a "make a web request" action to send the email to the API
• For the web request, set the URL to the API endpoint (e.g. https://your-app-url.com/api/zapier/transactions)
• Set the request method to POST
• Set the request body to the email content
• Set the request headers to the following:
  • Content-Type: application/json
  • Authorization: Bearer ${ZAPIER_SECRET}
• Set the request body to the email content (the plain email body, not the HTML)
• Set the subject to the email subject
• Set the from to the email from address