Skip to content

Home

Jump to bottom
Evan Newman edited this page Jul 2, 2026 · 1 revision

SubSync

SubSync is a local-first subscription tracker for streaming and media services, packaged as a single portable Windows app. It keeps every subscription — plan, price, billing cadence, renewal date — in one dashboard, imports billing details straight from your Gmail, and reminds you before renewals hit. All data lives in a SQLite file on your machine; there is no cloud account, no server, and nothing to sign up for.

Current release: v1.1.2 (July 2, 2026) — see Releases and CHANGELOG.md.

Highlights

  • Subscription lifecycle — create, edit, and delete subscriptions with a full audit trail (SubscriptionEvent records power a per-subscription timeline and a "Recent activity" feed on the dashboard).
  • Gmail billing import — connect Gmail with real, read-only OAuth. SubSync scans billing/receipt emails on a 6-hour schedule (or on demand), infers the provider, plan, price, currency, and renewal date, and creates or updates subscriptions automatically. Refresh tokens are stored encrypted, locally. Emails can also be pasted in manually; imports with no detectable billing amount are rejected rather than guessed.
  • Renewal reminders — a background worker queues reminders using your lead-time and channel preferences, delivered as native OS notifications by the desktop app. Renewal rows can be snoozed from the dashboard.
  • Dashboard analytics — monthly spend, active-subscription count, upcoming renewals, spend by category, and duplicate-plan detection. Amounts render in each subscription's own currency.
  • Searchable grid — filter by status, search by name, URL-synced filters, service logos.
  • Export, backup, restore — CSV/JSON export of subscriptions plus one-click SQLite backup and restore.
  • Auto-update — the portable exe checks GitHub Releases via electron-updater; updates can be checked, downloaded, and installed from Settings.

Download & install

Grab SubSync <version>.exe from the latest GitHub Release and run it — no installer, no Docker, no Node.js required. See the Windows quickstart for first-run notes (the exe is unsigned, so SmartScreen may warn on first launch).

Your data lives at %APPDATA%\SubSync\data\subsync.db.

How it works

The exe is an Electron shell that boots two embedded servers on localhost and points a desktop window at them:

┌───────────────────────── SubSync.exe (Electron) ─────────────────────────┐
│                                                                          │
│  BrowserWindow ──▶ Next.js 14 UI (127.0.0.1:43101)                       │
│                        │ REST                                            │
│                        ▼                                                 │
│                    NestJS 10 API (127.0.0.1:43100)                       │
│                        │ Prisma 5                                        │
│                        ▼                                                 │
│                    SQLite (%APPDATA%\SubSync\data\subsync.db)            │
│                                                                          │
│  On launch: migrations apply once each, tracked in a _migrations ledger  │
│  Background: Gmail sync (6h) · renewal reminders · update checks         │
└──────────────────────────────────────────────────────────────────────────┘

Both servers bind to 127.0.0.1 only — nothing is exposed to the network. Database migrations are applied by a shared runner (desktop/migrations.cjs) with a ledger table and per-migration transactions, so fresh installs, upgrades, and relaunches are all safe (since v1.1.2).

Tech stack

Layer Technology
API NestJS 10 (TypeScript)
Database SQLite via Prisma 5
Web UI Next.js 14 (App Router), Tailwind CSS, Radix UI, Lucide icons
Desktop Electron 41, electron-builder 26 (Windows portable), electron-updater
Monorepo npm workspaces — apps/api, apps/web, packages/types, desktop/

Data model

Core tables: Service (seeded provider catalog with logos and OAuth flags), Subscription, SubscriptionEvent (audit trail), IntegrationConnection, GmailConnection (encrypted tokens), ProcessedGmailMessage, PendingNotification, UserSettings.

Subscription statuses: active, trial, canceled_pending. Billing intervals: monthly, quarterly, yearly, custom.

API surface

All endpoints are prefixed with /api and served on 127.0.0.1:43100:

Area Endpoints
Services GET /services
Subscriptions CRUD on /subscriptions, POST /subscriptions/:id/snooze, GET /subscriptions/events/recent, GET /subscriptions/:id/events
Dashboard GET /dashboard/summary
Gmail GET /gmail/status, GET /gmail/auth-url, GET /gmail/callback, POST /gmail/sync, POST /gmail/disconnect
Email import POST /ingest/email
Integrations GET /integrations, POST /integrations/:provider/connect, DELETE /integrations/:provider
Data GET /data/export/subscriptions, POST /data/backup, GET /data/backups, POST /data/restore, POST /data/restore/:fileName
Notifications GET /notifications/pending, POST /notifications/:id/ack, GET/PUT /notifications/preferences
Settings GET/PUT /settings

Developing

git clone https://github.com/ejames-dev/SubSync.git
cd SubSync
npm install
cp .env.example .env && cp .env apps/api/.env

# Database (safe to re-run; migrations are ledger-tracked)
cd apps/api
DATABASE_URL="file:./dev.db" npm run prisma:migrate
DATABASE_URL="file:./dev.db" npm run prisma:generate
DATABASE_URL="file:./dev.db" npm run prisma:seed
cd ../..

npm run dev:api   # NestJS on 127.0.0.1:43100
npm run dev:web   # Next.js on http://127.0.0.1:3000/dashboard

Checks: npm run lint, npm test (API unit + desktop migration-runner tests), npm run test:e2e --workspace api.

Desktop builds: npm run build:desktop stages the runtime on any OS; producing the portable exe (npm run dist:desktop) requires native Windows — see the release checklist.

Release history

Version Date Theme
1.1.2 2026-07-02 Reliability: migration ledger (fresh-install / relaunch crashes), no more fabricated import prices, packaged API entry fix
1.1.1 2026-06-20 Build fixes: Prisma client path, incremental-build cache
1.1.0 2026-06-05 "It actually works": Gmail OAuth, OS notifications, export/backup/restore, auto-update, dashboard polish
1.0.1 2026-05-17 Packaging fixes
1.0.0 2026-03-17 First portable desktop release

Roadmap

Near-term: consistent branding, a CI pipeline, spend-by-category chart, larger service catalog, stronger provider-specific email parsing. Longer-term: macOS/Linux builds, direct provider OAuth (Spotify/YouTube), spend forecasting, budget alerts. Full plan: docs/release-roadmap.md.

Further reading

Clone this wiki locally