💰 TrackIt: Your Personal Finance Command Center

Take control of your finances with intelligent expense tracking, learned categorization, and powerful analytics

📋 Table of Contents

• Why TrackIt?
• Features
• Tech Stack
• Quick Start
• How It Works
• RESTful Endpoints
• Architecture
• Project Structure
• Security
• Contributing
• License

🎯 Why TrackIt?

Managing personal finances shouldn't be complicated. TrackIt transforms the way you handle money by:

• ⚡ Automating the Mundane: Import CSVs and categorize with learned rules, history, and patterns
• 📊 Revealing Insights: Discover spending patterns you never noticed
• 🤖 Asking Your Data: Chat with a finance agent grounded in your transactions
• 🔒 Keeping Data Private: Per-user isolation; your data stays in your database
• 📱 Working Everywhere: Access from any device with a modern browser

✨ Features

🏦 Core Financial Management

Multi-Account Support Connect all your accounts in one place Bank Credit Savings

Transaction Import Bulk CSV import with duplicate detection CSV Preview Confirm

Finance Agent Ask natural-language questions about your spending Gemini Groq Tools

Multi-Institution Support for major banks and cards CIBC AMEX WS RBC BMO

🧠 Intelligence & Automation

Smart Categorization Learns from your corrections; no per-row LLM on import Exact History RULES Fuzzy

Learned Rules Per-user merchant mappings with confidence Apply to Other Edit

Suggestions Scored category recommendations for Other rows

Grounded Agent Tool-backed answers and category proposals Accept Dismiss

📊 Analytics & Insights

Powerful Analytics Monthly, category, and trend analysis

Beautiful Charts Interactive Chart.js visualizations

Real-time Dashboard Live updates as you categorize

Spending Trends Track patterns over time

🛠 Tech Stack

Backend Technologies

Technology	Version	Purpose
	3.14+	Core Language
	0.139	Web Framework
	17	Database
	0.0.39	ORM
	0.51	ASGI Server
	0.16	Lint (CI)

Frontend Technologies

Technology	Version	Purpose
	3.5	UI Framework
	6.0	Type Safety
	8	Build Tool
	4.3	Styling
	4.5	Charts
	10	Packages

DevOps & Tools

Technology	Purpose
	Containerization
	CI / deploy
	Version Control

🚀 Quick Start

Using Docker (Recommended)

# Clone and start
git clone https://github.com/Nandan-18/trackit.git
cd trackit
./nginx/generate-certs.sh   # requires mkcert
docker compose up -d

Live demo: trackit-sigma-taupe.vercel.app · Product docs: trackit-sigma-taupe.vercel.app/docs

Open the live demo · Guest walkthrough

Authentication setup (required)

TrackIt uses Google OAuth and isolates data per user. Copy .env.example to .env in the repo root and fill in values:

cp .env.example .env

Required keys (see .env.example for the full template):

# Google OAuth credentials
GOOGLE_CLIENT_ID="YOUR_GOOGLE_OAUTH_CLIENT_ID"
VITE_GOOGLE_CLIENT_ID="YOUR_GOOGLE_OAUTH_CLIENT_ID"

# JWT secret
JWT_SECRET="CHANGE_ME_TO_A_LONG_RANDOM_SECRET"

# Finance agent keys and defaults
GEMINI_API_KEY=""
GROQ_API_KEY=""
AGENT_DEFAULT_PROVIDER="gemini"
GEMINI_MODEL="gemini-3.1-flash-lite"
GROQ_MODEL="llama-3.3-70b-versatile"

# DB import (optional)
PROD_DATABASE_URL=""

Add 127.0.0.1 local.trackit.com to /etc/hosts if needed, then open:

Frontend local.trackit.com

API local.trackit.com/api

Product Docs local.trackit.com/docs

API Docs local.trackit.com/api/docs

🔄 How It Works

RESTful Endpoints

POST   /api/auth/google                 # Exchange Google ID token for TrackIt JWT

GET    /api/accounts                      # List current user's accounts
POST   /api/accounts                      # Create an account for current user
PATCH  /api/accounts/{id}                 # Rename or archive an account

GET    /api/mappings                              # List learned merchant rules
POST   /api/mappings                              # Create a merchant rule
PATCH  /api/mappings/{id}                         # Update pattern and/or category
DELETE /api/mappings/{id}                         # Delete a merchant rule
POST   /api/mappings/{id}/apply-to-other          # Rewrite matching Other transactions

POST   /api/transactions/upload/preview         # Preview CSV upload
POST   /api/transactions/upload/confirm         # Confirm CSV import (learns overrides)
GET    /api/transactions/debit                  # Debit transactions
GET    /api/transactions/credit                 # Credit transactions
PUT    /api/transactions/{id}/category          # Update category
POST   /api/transactions/suggest-category       # Get suggestions
GET    /api/transactions/other-review           # Proposed categories for Other txs
GET    /api/transactions/categories             # Categories list

GET    /api/analytics/monthly-summary           # Monthly overview
GET    /api/analytics/category-breakdown        # Category analysis
GET    /api/analytics/spending-trends           # Trend analysis
GET    /api/analytics/month-details/{month}     # Detailed month view
GET    /api/analytics/available-months          # Available months

GET    /api/agent/providers                                    # Configured LLM providers
GET    /api/agent/conversations                                # List chats
POST   /api/agent/conversations                                # Create chat
GET    /api/agent/conversations/{id}                           # Chat + messages
DELETE /api/agent/conversations/{id}                           # Delete chat
POST   /api/agent/conversations/{id}/messages                  # Send message
POST   /api/agent/conversations/{id}/messages/{mid}/suggestions # Accept/dismiss suggestion

GET      /api/health                    # Liveness probe
GET      /                              # API root

🏗 Architecture

📁 Project Structure

TrackIt/
├── backend/
│   ├── api/
│   │   ├── accounts.py              # Account CRUD
│   │   ├── agent.py                 # Finance agent conversations
│   │   ├── analytics.py             # Analytics and reporting
│   │   ├── auth.py                  # Google OAuth → JWT
│   │   ├── mappings.py              # Learned merchant rules
│   │   └── transactions.py          # Import, list, suggestions
│   ├── config/
│   │   └── constants.py             # Categories, RULES, thresholds
│   ├── core/
│   │   ├── agent/                   # Agent loop, tools, providers
│   │   ├── auth.py                  # JWT / current user
│   │   ├── categorizer.py           # Categorization engine
│   │   └── utils.py                 # CSV parsers (cached categorizer)
│   ├── db/
│   │   ├── database.py
│   │   ├── models.py
│   │   └── types.py
│   ├── deploy/                      # Dockerfile
│   ├── tests/
│   ├── main.py
│   ├── requirements.txt             # Runtime deps
│   └── requirements-dev.txt         # Pytest, ruff, httpx2
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── agent/               # Agent chat UI
│   │   │   ├── analytics/
│   │   │   ├── charts/
│   │   │   ├── monthly/
│   │   │   ├── onboarding/
│   │   │   ├── rules/               # Learned Rules UI
│   │   │   ├── shared/
│   │   │   ├── transactions/
│   │   │   └── widgets/             # Upload, create account
│   │   ├── composables/
│   │   ├── lib/                     # API client, auth, guest mode
│   │   ├── router/
│   │   ├── types/                   # Generated auto-import typings
│   │   ├── views/                   # Landing, Accounts, Transactions,
│   │   │                            # Analytics, Monthly, Rules, Agent
│   │   ├── App.vue
│   │   └── main.ts
│   ├── config/                      # Vite, ESLint, Prettier, Playwright
│   ├── deploy/                      # Dockerfile
│   ├── tests/                       # Vitest (unit/) + Playwright (e2e/)
│   ├── scripts/
│   ├── vercel.json
│   └── package.json
│
├── .github/workflows/               # CI + backend deploy
├── nginx/                           # Local TLS reverse proxy
├── docker-compose.yml
├── .env.example
├── LICENSE.md
└── README.md

🔍 SEO and indexing

Public pages: / and /docs/*. App shell routes (/transactions, /analytics, /monthly, /agent, /rules, /account) are noindex and disallowed in frontend/public/robots.txt.

After deploy, verify ownership in Google Search Console (HTML file upload into frontend/public/ or DNS), then submit the sitemap URL above. GitHub Actions builds and prerenders the frontend, then deploys that dist to Vercel (vercel deploy --prebuilt) and records the GitHub Production deployment. Vercel git auto-deploys are disabled so production always serves the CI prerendered HTML.

🔒 Security

🤝 Contributing

PRs welcome. Fork the repo, use a feature branch, and open a pull request against main.

Fork Create your fork

Create Feature branch

Commit Conventional commits

PR Open PR

📄 License

Copyright (c) 2026 Nandan Ramesh. This project is licensed under the GNU Affero General Public License v3.0 — see the LICENSE.md file for details.

_{Built with ❤️ by Nandan Ramesh}