Pocket Pixel — Expense Tracker

Level up your finances. Track every coin, quest every habit.

Screenshots

Dashboard	Analytics

What is Pocket Pixel?

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

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS
Backend	Express.js, TypeORM, SQLite (better-sqlite3)
Auth	JWT (30-day sessions), bcryptjs password hashing
Scheduling	node-cron (recurring transaction automation)
Validation	Joi
Process Manager	PM2
Monorepo	npm workspaces

⚠️ Caution

This project was entirely vibe coded with claude, gemini models, and codex. The UI was designed with Google stitch. It is full of sloppy code and possible bugs with many features still under development.

Google stitch: https://stitch.withgoogle.com/projects/14795631199624450898

Agentic coding

The repository has a bunch of skills/rules defined in .agents or .claude folders. These are supported by codex and gemini models.

Project Structure

pocket_pixel/
├── packages/
│   ├── api/          # Express REST API + TypeORM entities
│   │   └── src/
│   │       ├── entities/     # User, Expense, Vault, Tag, TransactionTag
│   │       ├── routes/       # auth, users, transactions, vaults, tags, recurring, analytics
│   │       ├── middleware/   # JWT auth, error handling
│   │       └── scheduler/   # node-cron recurring job manager
│   │
│   ├── 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

Getting Started

Prerequisites

Node.js ≥ 18
npm ≥ 9

Clone the repo

git clone https://github.com/propo41/expense_tracker.git
cd expense_tracker
npm install
npm run build:shared

Create .env files

Create .env files for both the api and the ui

Copy .env.example to .env for both the api and the ui
Fill the .env files with the appropriate values (or keep the defaults for local development)

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

Test

# API tests
npm run test:api

# UI E2E tests
npm run test:e2e

Production Build

# 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:4000

API Reference

All endpoints are prefixed with /api. Protected routes require an Authorization: Bearer <token> header.

Database Schema

SQLite database managed via TypeORM with migrations.

users            — id, name, email, password, avatar
expenses         — id, userId, title, amount, type, date, interval, vaultId, deletedAt
vaults           — id, userId, name, description, icon, backgroundColor, isDefault, deletedAt
tags             — id, userId, name, icon, backgroundColor
transaction_tags — transactionId, tagId  (junction table)

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 migration

Features In Depth

Vaults

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.

Recurring Quests

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.

Analytics

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

Authentication

Passwords hashed with bcryptjs (12 salt rounds)
JWT tokens with 30-day expiration stored in localStorage
Auth guard on all protected frontend routes

Contributing

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.

How to Contribute

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:api and dev:ui)
Push your branch and open a Pull Request

Code Style

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.

Reporting Bugs

Open an issue with:

What you expected vs. what happened
Steps to reproduce
Your OS and Node.js version

License

MIT — do whatever you want with it. See LICENSE for details.

Made with ☕ and a lot of pixel art inspiration.

⬆ Back to top

FilesExpand file tree

README.md

Latest commit

History