GitHub - CmdShiftExecute/CardPulse: A credit card expense tracker with NLP-powered quick entry, billing cycle intelligence, EMI tracking, and rich analytics. Built with Next.js, TypeScript, Tailwind CSS, and SQLite.

A quieter view of your spending.

A privacy-first credit card expense tracker with smart NLP entry, multi-card billing cycle management, 6 color themes, and deep analytics — built entirely offline with no cloud dependencies.

Next.js TypeScript Tailwind CSS SQLite Recharts License: MIT Version

Live Demo

See CardPulse in action with sample data

Deploy Your Own

🔒 Your financial data never leaves your machine. No cloud. No API calls. No telemetry. Just you and your SQLite database.

✨ Key Features

🧠 Smart Transaction Entry

NLP Quick Add — type "enoc 200 fab card yesterday" and the offline parser extracts amount, category, card, date, and labels
Manual Entry — full form with dropdowns for when you want control
Self-Learning — correct a parse and it remembers for next time
91 pre-seeded keyword rules for popular merchants

💳 Multi-Card Management

Track 5+ credit cards with real billing cycles
Statement dates, due dates, credit limits
Credit utilization tracking with color-coded thresholds
Card aliases for NLP recognition

🏠 Smart Dashboard

Per-card spending breakdown
Payment ticker with due date countdowns
Category & label donuts with click-to-drill
Credit utilization overview
💚 Financial Health Card with 6-level mood face based on debt-to-income ratio

📊 Rich Analytics (7 tabs)

Trends — overall, category, and label spending over time
Compare — month-vs-month grouped bars and delta tables
Monthly Drilldown — interactive donut charts
Cycles — 3-cycle billing timeline per card
Cards — per-card area charts and grouped bars
EMIs — installment landscape view
Budgets — budget vs. actual progress

🎨 Theme System

6 themes — Sage, Midnight, Cyberpunk, Molten, Mono, Terminal
Dark + Light modes — 12 visual combinations
CSS variable architecture with instant switching
Flash-prevention for seamless page loads

📦 EMI Tracker

Manage installment plans across cards
Auto-generation prompts each billing cycle
Progress tracking with completion dates
EMI amounts reflected in card cycle estimates

🌱 Survival Summary

EMI-page tab: monthly cost-of-living floor
EMI burden + fixed costs combined into one number
18-month projection chart as installments roll off
Closure schedule of when each EMI ends

🎯 Budget Management

Set monthly budgets per category or subcategory
Visual progress bars (🟢 green / 🟡 gold / 🔴 red)
Dashboard strip + analytics tab

📥 Export Reports

Styled XLSX with blue headers, green amounts, label summaries
Month selector + currency conversion rate
Professional formatting ready for sharing

⚙️ Full Settings

Currency, date format, number format
6 color themes ×ばつ 2 modes
PIN security (enable/disable/change)
Database backup & restore
Keyword rules, labels, and categories management

📸 Screenshots

🏠 Dashboard

The home view leads with a Financial Health Card that condenses your monthly commitments into a single survival figure, followed by the Monthly Hero and per-card breakdown.

Dashboard — Financial Health Card and Monthly Hero

Dashboard — Upcoming Payments, Top Transactions and EMI Status

More from Dashboard

Dashboard — Spend by Category and Label donuts, Recent Transactions

Dashboard — Budget Tracking strip and EMI burden summary

Dashboard — Credit Overview and Card Cycle Status

✏️ Transactions

Add by typing — the offline NLP parser extracts amount, category, card, date, and labels. Switch to manual entry whenever you want full control.

Transactions list with Quick Add input and filters

Manual Entry form with amount, date, category, card, labels and notes

💳 Cards

Cards page — billing cycles, credit limits, utilization per card

📦 EMIs — Survival & Tracker

A two-tab page. Survival turns active installments and fixed costs into a monthly cost-of-living number and projects when each EMI rolls off. EMI Tracker manages the installments themselves.

EMIs — Monthly Cost of Living, EMI Burden by Card, Fixed Monthly Costs

EMIs — 18-month Burden Projection chart and Closure Schedule

📊 Analytics (7 tabs)

Seven views over the same dataset: long-term trends, month-vs-month comparison, monthly drilldown donuts, billing-cycle timelines, per-card bars, EMI distribution, and budget vs actual.

Analytics — Trends tab with Overall Spending Trend chart

Analytics — Compare tab with month-vs-month bars and delta table

More from Analytics

Analytics — Monthly Drilldown with category and label donuts

Analytics — Cycles tab with three-cycle timeline per card

Analytics — Cards tab with card-wise spending bars

Analytics — EMIs tab with EMI Distribution by Card and Timeline Horizon

Analytics — Budgets tab with Budget vs Actual progress bars

🎯 Budgets

Budgets page with Set Budget modal

⚙️ Settings

Nine sections covering currency, fixed costs, appearance, security, cards, NLP keyword rules, labels, categories, and database export/import. Defaults are sensible; nothing leaves your machine.

Settings — General: currency, date format, number format, household income

Settings — Fixed Costs: add monthly obligations with icon and color

More from Settings

Settings — Labels manager

Settings — Categories tree (read-only)

Settings — Data Management: export, import, reset

💚 Financial Health Card — close-up

A standalone view of the dashboard's signature card. Six mood faces map the ratio of monthly commitments to income, from Thriving to Underwater.

Financial Health Card close-up showing Required to survive next month, card bills, fixed monthly costs and per-card outstanding

🚀 Quick Start

Option 1: npm (requires Node.js)

# Clone the repository
git clone https://github.com/CmdShiftExecute/CardPulse.git
cd CardPulse
# Install dependencies
npm install
# Start the development server
npm run dev

Option 2: Docker (no Node.js required)

# Clone the repository
git clone https://github.com/CmdShiftExecute/CardPulse.git
cd CardPulse
# Build and run
docker build -t cardpulse .
docker run -p 3000:3000 -v $(pwd)/data:/app/data cardpulse

Open http://localhost:3000 — you'll be guided through PIN setup on first launch.

The -v flag mounts the data/ folder so your SQLite database persists across container restarts.

🎬 First Run

Step	What Happens
1️⃣	Database auto-created with categories, labels, keyword rules
2️⃣	Create your PIN (4–6 digits, bcrypt-hashed)
3️⃣	Dashboard loads — add your first transaction via Quick Add
4️⃣	Explore Analytics once you have a few transactions

💡 Tip: The PIN can be disabled from Settings > Security if you're running locally. See the Getting Started guide for details.

📚 Documentation Portal

For detailed information, refer to the guides in the docs/ folder:

Document	Target Audience	Description
🚀 Getting Started	New Users	Installation, first run, PIN setup, your first transaction
🏠 Dashboard Guide	All Users	Every dashboard section explained with interactions
✏️ Transaction Entry	All Users	NLP quick-add, manual entry, learning, bulk operations
💳 Card Management	All Users	Credit cards, billing cycles, aliases, utilization
📦 EMI Tracker	All Users	Installment plans, auto-generation, progress tracking
📊 Analytics Deep Dive	All Users	All 7 analytics tabs in detail
🎯 Budgets	All Users	Setting and tracking monthly spending limits
⚙️ Settings Reference	All Users	All 8 settings sections (themes, currency, backup, etc.)
📥 Export Reports	All Users	XLSX export format and options
🏗️ Architecture Overview	Developers	Tech stack, DB schema, API routes, system design
🚢 Deployment Guide	Developers	Local dev, production, VPS, SQLite considerations
🌱 Survival Summary	All Users	Monthly cost-of-living floor + 18-month EMI closure projection
💚 Financial Health Card	All Users	Dashboard mood-face card based on debt-to-income ratio

🛠️ Tech Stack

Layer	Technology	Purpose
Framework	Next.js 14 (App Router)	Full-stack React with API routes
Language	TypeScript (strict mode)	Type safety for financial data
Styling	Tailwind CSS 3.4	Utility-first with CSS variable themes
Database	SQLite via `better-sqlite3`	Zero config, local-first, single file
ORM	Drizzle ORM	Lightweight, type-safe, SQLite-native
Charts	Recharts	Composable React-native charting
NLP/Matching	Fuse.js + custom rules	Offline fuzzy matching, no LLM
Export	ExcelJS	Styled XLSX with formatting
Animations	Framer Motion	Subtle micro-interactions
Icons	Lucide React	Clean, consistent iconography
Fonts	Inter + JetBrains Mono	Via `next/font/google`

📁 Project Structure

cardpulse/
├── 📂 src/app/ # Pages + API routes
│ ├── dashboard/ # Main dashboard
│ ├── transactions/ # Transaction list + entry
│ ├── cards/ # Card management
│ ├── emis/ # EMI tracker
│ ├── analytics/ # 7-tab analytics
│ ├── budgets/ # Budget management
│ ├── settings/ # 9-section settings (incl. Fixed Costs)
│ └── api/ # 20 API endpoints
│
├── 📂 src/components/ # React components
│ ├── ui/ # Reusable primitives
│ ├── layout/ # Sidebar, header, ticker
│ ├── providers/ # Theme context
│ ├── dashboard/ # Dashboard sections
│ ├── analytics/ # Charts and insight cards
│ └── ... # Cards, EMIs, budgets, etc.
│
├── 📂 src/lib/ # Core logic
│ ├── db/ # Schema, seed, queries
│ ├── nlp/ # 4-stage NLP parser
│ ├── export/ # XLSX generator
│ ├── format.ts # Currency/date formatting
│ ├── cycle-utils.ts # Billing cycle math
│ └── chart-utils.ts # Shared chart helpers
│
├── 📂 docs/ # Documentation (13 guides)
├── 📂 data/ # SQLite database (gitignored)
└── 📂 drizzle/ # Generated migrations

⚙️ Configuration

Environment Variables

Variable	Default	Description
`DB_PATH`	`./data/cardpulse.db`	Path to the SQLite database file

Set in .env.local:

DB_PATH=./data/cardpulse.db

No other environment variables needed. No API keys, no cloud services.

Application Settings

All settings are configurable from the Settings page:

Setting	Default	Options
Currency	USD	USD, EUR, GBP, INR, AED, SAR, ... (or any custom 3-letter code)
Household Income (monthly)	—	Optional number used by the Financial Health Card to compute commitment ratio
Date Format	DD/MM	DD/MM, MM/DD
Number Format	1,234.56	comma_period, period_comma
Theme	Sage	Sage, Midnight, Cyberpunk, Molten, Mono, Terminal
Color Mode	Dark	Dark, Light
PIN	Enabled	Enable/Disable/Change

📊 At a Glance

Metric	Count
📄 Pages	9 (Dashboard, Transactions, Cards, EMIs, Analytics, Budgets, Settings, Lock, Setup)
🔌 API Routes	20 (CRUD + analytics + exports + NLP + auth + settings + fixed-costs)
🧩 Components	70+ (UI primitives, page sections, charts, forms)
🗄️ DB Tables	12 (cards, transactions, categories, subcategories, labels, keyword_rules, emis, budgets, settings, cycle_payments, transaction_labels, fixed_costs)
🔍 Keyword Rules	91 pre-seeded (popular merchants, banks, services)
🏷️ Labels	25 system labels + unlimited custom
📂 Categories	11 main → 68 subcategories
🎨 Themes	6 themes ×ばつ 2 modes = 12 combinations

🤝 Contributing

CardPulse is a personal project built as a portfolio piece. Contributions, suggestions, and bug reports are welcome! Feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

CardPulse v2.1 — fueled by ☕ and a healthy fear of 💳 statements.

Name		Name	Last commit message	Last commit date
data		data
docs		docs
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
drizzle.config.ts		drizzle.config.ts
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
railway.toml		railway.toml
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation