💸 SubTrack

Subscription and recurring expense tracker — never lose track of your monthly costs again.

SubTrack lets you log subscriptions (Netflix, Spotify, gym memberships, cloud storage…) and see what they cost you monthly and yearly, with multi-currency conversion, smart reminders, sharing, and analytics that actually answer questions you'd ask yourself.

Live app → https://subtrack-psi-nine.vercel.app

🎮 No sign-up required — click "Explore the demo" on the login page to drop straight into a fully-seeded account (subscriptions, budgets, analytics and spend history).

📸 Screenshots

✨ Features

Core

📊 Dashboard with monthly/yearly totals, upcoming payments, recent activity, and a quick "review these" widget
💸 Per-subscription cost breakdown (per cycle, monthly equivalent, yearly projection, optional yearly-vs-monthly savings hint)
🪙 Multi-currency display with live FX (Frankfurter) — default picked from your browser locale
🔍 Powerful list view: search, filter, sort, bulk actions, command palette, keyboard shortcuts (? for the cheat sheet)
🌍 English + Turkish UI, <html lang> kept in sync for screen readers
🎨 Glassmorphism dark theme with light option, installable as a PWA, works offline for cached views
🪐 3D auth & onboarding hero with real subscription-platform logos (react-three-fiber) — lightweight mobile variant + reduced-motion / WebGL fallbacks
🎮 One-click demo — "Explore the demo" provisions a throwaway, fully-seeded account (subscriptions, budgets, price history, spend snapshots) that auto-expires after 48h, so anyone can try the app without registering

Insights

📈 Price history per subscription with stepped chart + total/last-change percent
📅 Payment heatmap (year-long GitHub-style grid showing days you'll pay)
🔮 Linear-regression forecast of next 6 months based on monthly snapshots
🆚 Period comparison ("now vs then" totals + per-category delta + added/cancelled list)
💰 Budgets with TOTAL or per-CATEGORY scope, MONTHLY/YEARLY periods, and 80%/100% threshold alerts (email + in-app + push)
🧠 Smart category suggestions as you type a name; bulk auto-categorize for uncategorized rows
🚨 Suggestions widget flags expensive subs, price hikes, expired trials, unused-recently rows, and duplicate categories — with 30-day dismiss

Notifications

📧 Renewal & trial-ending email reminders via SMTP (Nodemailer)
🔔 In-app notification center (bell icon, unread badge, accept/decline invitations inline)
📲 Web Push via VAPID with installable service worker
🗓️ Calendar feed (webcal:// + .ics per subscription, Google/Outlook quick-add)

Sharing & multi-user

👥 Per-subscription sharing with VIEWER / EDITOR roles
✉️ Invitation by email with single-use 7-day tokens; in-app pending invitations on the bell
🛡️ Email-bound acceptance: only the invited email can take the share

Security & privacy

🔐 2FA (TOTP) via authenticator apps with single-use backup codes
🌐 OAuth login (Google + GitHub) with link-by-email account merge
🔄 Server-side JWT revocation via tokenVersion — logout, password change, and 2FA toggles invalidate every live token
📤 Full account data export (one JSON file of every row you own, password-hash–free)
🗑️ Account deletion behind password + 2FA + typed-DELETE confirmation

Observability

🐛 Sentry on both server (Express handler) and client (React ErrorBoundary), user context auto-attached
📜 Pino structured logs on the server; HTTP request log middleware
📊 Activity log page with type chips, search, date range filtering

🛠️ Tech Stack

Frontend — React 19 · TypeScript · Vite · TailwindCSS · shadcn/ui · TanStack Query · Zustand · Recharts · Framer Motion · react-three-fiber / three.js · simple-icons · i18next · Storybook · Sentry React.

Backend — Node.js 22 · Express 5 · TypeScript · PostgreSQL · Prisma · JWT (with server-side revocation) · Pino · Nodemailer · web-push · otplib · Sentry Node.

DevOps — Docker · docker-compose (Postgres + Adminer + Mailhog) · GitHub Actions (type-check · lint · tests · build) · ESLint · Vitest (53 server unit tests + client tests).

🏗️ Architecture

flowchart LR
    User[👤 User browser] -- "HTTPS" --> Vercel
    User -- "Web Push (VAPID)" --> SW[Service Worker]

    subgraph Vercel["Vercel · Edge"]
        Client[Vite static SPA<br/>React + Tailwind]
    end

    subgraph Render["Render · Docker container"]
        API[Express + Prisma<br/>JWT · cookie-parser · helmet]
        Cron[/Cron triggers<br/>/jobs/notify-renewals<br/>/jobs/snapshot-monthly/]
    end

    subgraph Neon["Neon · Postgres 16"]
        DB[(subtrack_db<br/>users · subscriptions<br/>budgets · price_history<br/>events · shares ...)]
    end

    Mail[(SMTP / Mailhog)]
    Sentry[(Sentry)]
    Frankfurter[(Frankfurter FX API)]

    Client -- "/api/* (Vercel rewrite)" --> API
    API -- "Prisma" --> DB
    API -- "Renewal & invitation emails" --> Mail
    API -- "Web push payloads" --> SW
    API -- "FX rates" --> Frankfurter
    API -. "errors / traces" .-> Sentry
    Client -. "errors / traces" .-> Sentry
    Cron -- "X-Job-Key" --> API

The same SPA is served from Vercel's CDN; every /api/* request is rewritten to the Render API, so the browser always sees same-origin requests (no CORS preflight headaches). Push delivery goes from the API straight to the browser's service worker via VAPID, bypassing Vercel.

🧭 Quick start (local)

# 1. Bring up Postgres + Mailhog + Adminer
npm run docker:up

# 2. Install deps
npm install

# 3. Server: set env, migrate, run
cd apps/server
cp .env.example .env  # fill JWT_SECRET and INTERNAL_JOB_KEY
npx prisma migrate dev
npm run dev

# 4. Client (separate terminal)
cd apps/client
npm run dev

Visit http://localhost:5173 for the app, http://localhost:8025 for the Mailhog inbox, and http://localhost:8080 for Adminer (Postgres GUI).

Useful scripts

# Workspace
npm run type-check          # tsc across all workspaces
npm run lint                # eslint across client + server
npm run docker:up | down    # toggle local Postgres / Mailhog / Adminer

# Server (cd apps/server)
npm test                    # vitest, 53 unit tests
npm run test:coverage       # v8 coverage report
npx prisma studio           # browse the DB

# Client (cd apps/client)
npm run dev | build         # vite
npm run storybook           # component catalog on :6006
npm run check:locales       # sanity-check TR/EN parity

🚀 Deploy

The recommended free stack is Neon (Postgres) + Render (API) + Vercel (client). All three have permanent free tiers and no credit card required to start.

1. Database — Neon

Sign up at https://neon.tech with GitHub.
Create a new project (region close to Render is ideal — Frankfurt for this repo's render.yaml).
Copy the pooled connection string (it contains -pooler). You'll paste it into Render below as DATABASE_URL.

2. API — Render

Sign up at https://render.com with GitHub.
New + → Blueprint → connect this repo. Render reads render.yaml and provisions a web service named subtrack-api from apps/server/Dockerfile.

After the service is created, set the env vars that were left blank:

Key	Value
`DATABASE_URL`	The Neon pooled connection string
`APP_URL`	The Vercel URL from step 3
`CORS_ORIGIN`	Same as `APP_URL`
`OAUTH_CALLBACK_BASE_URL`	The Render URL (e.g. `https://subtrack-api.onrender.com`)
SMTP / VAPID / OAuth / Sentry	Optional — leave blank to disable that feature

Render redeploys. On boot the container runs prisma migrate deploy automatically, so the schema is created on first launch.

Heads up — Render's free Web Service spins down after 15 minutes of inactivity and takes ~30s to wake. A scheduled GitHub Actions workflow (.github/workflows/keep-alive.yml) pings /health every ~10 min to keep it warm; for guaranteed always-on hosting move to a paid Render plan or Fly.io, or use an external pinger like UptimeRobot.

3. Client — Vercel

Sign up at https://vercel.com with GitHub.
New Project → import the repo → set Root Directory to apps/client. Vercel detects Vite automatically.
Open apps/client/vercel.json and replace the CHANGE-ME placeholder with your actual Render URL, then commit. Vercel auto-redeploys.
(Optional) Add a VITE_SENTRY_DSN env var for browser error reporting.

The Vercel build outputs dist/; the rewrites block in vercel.json proxies /api/* to your Render API and rewrites every other path to index.html so client-side routing works.

4. Post-deploy checklist

https://<render-url>/health returns {"status":"ok"}.
Open https://<vercel-url> and either register or click "Explore the demo".
Confirm the user lands at /dashboard and the bell, sidebar, topbar render.
If using OAuth: update Google/GitHub OAuth app callbacks to https://<render-url>/api/auth/oauth/<provider>/callback.
If using SMTP: send a test renewal job with curl -X POST https://<render-url>/api/jobs/notify-renewals -H "X-Job-Key: <INTERNAL_JOB_KEY>".

🔌 Optional integrations

Everything in this section is wired up but disabled by default. Add the env vars below to Render to switch each one on.

Feature	What you need	Render env vars
SMTP email	A Resend, Postmark, or any SMTP provider account	`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SECURE`, `EMAIL_FROM`, `APP_URL`
Web push	A VAPID key pair (`node -e "console.log(require('web-push').generateVAPIDKeys())"`)	`VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`
Google OAuth	A Google Cloud OAuth client with the Render callback URL whitelisted	`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `OAUTH_CALLBACK_BASE_URL`
GitHub OAuth	A GitHub OAuth app	`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `OAUTH_CALLBACK_BASE_URL`
Sentry server	A Sentry project DSN	`SENTRY_DSN`, `SENTRY_TRACES_SAMPLE_RATE`
Sentry client	Same DSN, set on Vercel instead	`VITE_SENTRY_DSN` (on Vercel)
Renewal cron	Any cron service (Render Cron, cron-job.org, GitHub Actions)	Hit `POST /api/jobs/notify-renewals` daily with `X-Job-Key: <INTERNAL_JOB_KEY>`
Monthly snapshot cron	Same	Hit `POST /api/jobs/snapshot-monthly` on the 1st of each month
Budget-alert cron	Same	Hit `POST /api/jobs/check-budgets` on your preferred cadence
Demo cleanup cron	Same (optional — demos also self-prune on each new demo)	Hit `POST /api/jobs/cleanup-demo` daily to remove demo accounts >48h old

📁 Project layout

subtrack/
├── apps/
│   ├── client/                  React + Vite SPA
│   │   ├── src/
│   │   │   ├── features/        feature-scoped folders (auth, budgets, shares, …)
│   │   │   ├── components/      shared UI primitives
│   │   │   ├── pages/           top-level routes
│   │   │   ├── store/           Zustand stores
│   │   │   └── lib/             api client, i18n, sentry, formatters
│   │   ├── public/              static assets + sw.js + manifest.webmanifest
│   │   └── .storybook/          component catalog config
│   └── server/                  Express + Prisma API
│       ├── src/
│       │   ├── controllers/     route handlers
│       │   ├── services/        business logic (forecast, comparison, …)
│       │   ├── lib/             primitives (jwt, ics, totp, fx, sentry, …)
│       │   ├── middlewares/     auth, rate-limit, error handler
│       │   └── routes/          Express routers
│       └── prisma/              schema + migrations
├── packages/shared/             cross-app TypeScript types
├── docs/screenshots/            README image gallery
├── docker-compose.yml           local Postgres + Mailhog + Adminer
├── render.yaml                  one-click Render blueprint
└── apps/client/vercel.json      Vercel rewrites + headers

📄 License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.github/workflows		.github/workflows
.vscode		.vscode
apps		apps
docs/screenshots		docs/screenshots
packages/shared		packages/shared
scripts		scripts
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml

Navigation Menu

Repository files navigation

💸 SubTrack

📸 Screenshots

✨ Features

Core

Insights

Notifications

Sharing & multi-user

Security & privacy

Observability

🛠️ Tech Stack

🏗️ Architecture

🧭 Quick start (local)

Useful scripts

🚀 Deploy

1. Database — Neon

2. API — Render

3. Client — Vercel

4. Post-deploy checklist

🔌 Optional integrations

📁 Project layout

📄 License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

💸 SubTrack

📸 Screenshots

✨ Features

Core

Insights

Notifications

Sharing & multi-user

Security & privacy

Observability

🛠️ Tech Stack

🏗️ Architecture

🧭 Quick start (local)

Useful scripts

🚀 Deploy

1. Database — Neon

2. API — Render

3. Client — Vercel

4. Post-deploy checklist

🔌 Optional integrations

📁 Project layout

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages