Pocket Pixel is a gamified personal finance tracker built for people who want to make budgeting actually fun. Inspired by retro RPG aesthetics, it wraps your income and expenses in a pixel-art UI where categories become Vaults, habits become Quests, and every transaction is part of your financial adventure.
- Vaults — organize spending into themed buckets (food, rent, subscriptions, anything)
- Recurring Quests — automate repeating transactions on daily, weekly, monthly, or yearly schedules
- Tags — label transactions with custom icons and colors for granular analytics
- Analytics — monthly and yearly breakdowns, tag-based insights
- Profiles — pick your avatar and make it your own
- Transaction auto-import — watch a Gmail label (bank/card alerts) and turn matching emails into transactions automatically, no manual entry
- AI-Assisted Parsing — a review queue for emails that need a closer look; parsed client-side in your browser using your own OpenRouter API key
- Wizard Assistant — an in-character chat guide that reads your vaults/transactions and gives spending advice, also powered by your own AI key
- Push Notifications — get pinged when a new pending expense is waiting for review
Pocket Pixel doesn't ship with a shared Google OAuth client or a shared AI API key. Every user connects their own Gmail OAuth client and brings their own OpenRouter key:
- Gmail OAuth credentials are encrypted at rest on the server (AES-256-GCM).
- The OpenRouter key is encrypted client-side (DEK-based, end-to-end) before it ever leaves your browser — the server only ever stores opaque ciphertext and never sees your plaintext key.
- No email body is parsed or stored server-side. Matching emails are held as a pointer (message id + vault) in a pending queue; the actual parsing happens in your browser with your own key.
See documentation/gmail-integration.md for the full setup (GCP project, Pub/Sub, OAuth client, per-user onboarding).
pocket_pixel/
├── packages/
│ ├── api/ # Express REST API + TypeORM entities
│ │ └── src/
│ │ ├── entities/ # User, Expense, Vault, Tag, TransactionTag, VaultGmailWatcher, PendingGmailExpense
│ │ ├── routes/ # auth, users, transactions, vaults, tags, recurring, analytics,
│ │ │ # vault-watchers, pending-expenses, ai-credentials, oauth (Google/Gmail)
│ │ ├── services/ # gmail.service (watch + webhook), pending-gmail-expense, user-ai-credential,
│ │ │ # user-oauth-credential (encrypted Google tokens), ...
│ │ ├── middleware/ # JWT auth, error handling
│ │ └── scheduler/ # node-cron recurring job manager + daily Gmail watch renewal
│ │
│ ├── ui/ # Next.js frontend
│ │ └── src/
│ │ ├── app/ # Dashboard, Profile, Stats, Auth pages
│ │ ├── components/ # Modals, AppBar, Nav, UI primitives
│ │ └── lib/ # API clients, helpers, icon mapper
│ │
│ └── shared/ # Shared TypeScript types/interfaces
│
├── ecosystem.config.js # PM2 production config
├── tsconfig.base.json
└── package.json # Workspace root
git clone git@github.com:ali-ahnaf/pocket_pixel.git
cd pocket_pixel
npm install
npm run build:shared # builds shared dependencies
npm run migration:run # creates/updates the .sql fileCreate .env files for both the api and the ui
- Copy
.env.exampleto.envfor both the api and the ui - Fill the .env files with the appropriate values (or keep the defaults for local development)
Run the API and UI in separate terminals:
# Terminal 1 — API (http://localhost:4000)
npm run dev:api
# Terminal 2 — UI (http://localhost:3000)
npm run dev:ui# API tests
npm run test:api
# UI E2E tests
npm run test:e2e# Build shared → UI → API in order
npm run build:prod
# run migrations and saves the file in /var/www/pocket_pixel
npm run migration:run-prod
# Start the server (API serves the compiled UI)
pm2 start ecosystem.config.js
# → http://localhost:4000All endpoints are prefixed with /api. Protected routes require an Authorization: Bearer <token> header.
SQLite database managed via TypeORM with migrations.
Run migrations:
npm run migration:run # Apply pending migrations
npm run migration:generate # Generate migration from entity changes
npm run migration:revert # Roll back the last migrationThe API can snapshot the SQLite database and upload it to Cloudflare R2 (an S3-compatible object store) every 12 hours. It's off by default — flip ENABLE_BACKUP=true in the API .env to turn it on. Backups use SQLite's online backup API, so snapshots stay consistent even while the app is writing.
Each run uploads an object named pocket_pixel/pocket_pixel-<timestamp>.sqlite to your bucket.
Why R2? The free tier includes 10 GB storage and, unlike most clouds, zero egress fees — you can pull your backups down for free. That's plenty for a SQLite file.
- Sign up (or log in) at dash.cloudflare.com — the account is free.
- In the sidebar open R2 Object Storage and click Enable R2. Cloudflare asks for a payment method to verify identity, but you are not charged while you stay within the free tier limits.
- Go to R2 → Create bucket.
- Name it (e.g.
pocket-pixel-backups) and create it. The location hint can stay on Automatic. - Remember this name — it's your
R2_BUCKET.
- On the R2 overview page click Manage R2 API Tokens → Create API Token.
- Permission: Object Read & Write.
- Scope it to the bucket you just created (recommended), then Create.
- Copy the Access Key ID and Secret Access Key — the secret is shown only once.
Your Account ID is on the R2 overview page (and in the S3 endpoint Cloudflare shows: https://<ACCOUNT_ID>.r2.cloudflarestorage.com). Copy it.
Add these to packages/api/.env (see packages/api/.env.example):
ENABLE_BACKUP=true
R2_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key-id
R2_SECRET_ACCESS_KEY=your-secret-access-key
R2_BUCKET=pocket-pixel-backupsRestart the API to pick them up (pm2 restart ecosystem.config.js in production, or restart npm run dev:api locally). On boot you should see Database backup scheduled every 12 hours to R2 in the logs. If R2 credentials are missing while ENABLE_BACKUP=true, the scheduler logs a warning and stays idle instead of crashing.
- Download the desired
.sqliteobject from your R2 bucket (Cloudflare dashboard or any S3 client). - Stop the API.
- Replace the live database file (
/var/www/pocket_pixel/pocket_pixel.sqlitein production, orpackages/api/pocket_pixel.sqlitelocally) with the downloaded file. - Start the API again.
Organize your money into custom buckets — think of them as tagged envelopes. Each vault has a name, icon (from Lucide), background color, and can be marked as your default. Transactions without a vault fall into the default one.
Set a transaction to auto-repeat on a schedule (daily / weekly / monthly / yearly). The API scheduler restores all active quests on startup using node-cron, so nothing gets missed between restarts.
Three views to understand your spending:
- Tag breakdown — which labels are eating your budget
- Monthly report — income vs. expenses by month
- Yearly report — long-term trend across all months
Connect Gmail, pick a label (e.g. a filter that tags bank alert emails), and point it at a vault. Google pushes new mail to the API via Pub/Sub in real time:
- A confident, rule-based match is recorded straight as a transaction.
- Anything less certain is enqueued in a pending review queue instead — only the Gmail message id, vault, and a guidance hint are stored, never the email body.
- You get a push notification, open the pending item in the UI, and it's parsed client-side, in your browser, using your own OpenRouter API key.
- Confirm and it becomes a transaction; dismiss and it's cleared from the queue.
The Wizard Assistant chat (Settings → AI) uses the same client-side OpenRouter key to answer questions about your spending — nothing is sent to Pocket Pixel's own servers for either feature.
Full setup (GCP project, Pub/Sub topic/subscription, OAuth client, per-user onboarding): documentation/gmail-integration.md.
Contributions are what make open source awesome. All skill levels welcome — whether it's fixing a typo, adding a new feature, or improving the docs.
- Fork the repository
- Create a feature branch
git checkout -b feat/your-feature-name
- Make your changes — keep commits focused and descriptive
- Test your changes locally (both
dev:apianddev:ui) - Push your branch and open a Pull Request
- Prettier is configured
- TypeScript strict mode is enforced
- Keep components small and single-purpose
- Name things clearly — no abbreviations unless obvious
- Do not make changes in the file that are not relevant to the task at hand.
Open an issue with:
- What you expected vs. what happened
- Steps to reproduce
- Your OS and Node.js version
╔═══════════════════════════════════════════════════╗
║ ★ P A R T Y R O S T E R ★ ║
║ These brave heroes joined the quest to slay ║
║ the dreaded budget-goblins of Pocket Pixel. ║
╚═══════════════════════════════════════════════════╝
🗡️ Want to join the party? Grab a quest from the issue board and roll for initiative.
MIT — do whatever you want with it. See LICENSE for details.
Made with ☕ and a lot of pixel art inspiration.