Your personal finance command center — Transform messy Excel exports into a beautiful, insightful financial dashboard.
Ledger Sync is a self-hosted personal finance application that syncs your transaction data from Excel files (exported from Money Manager Pro or similar apps) and provides comprehensive analytics for your financial life.
Live: sagargupta.online/ledger-sync | API: ledger-sync.onrender.com
- Drag-and-drop Excel uploads with beautiful hero UI
- Intelligent duplicate detection using SHA-256 hashing
- Idempotent syncing — re-upload anytime without duplicates
- Real-time toast notifications for upload status
- 50/30/20 Budget Rule — Track Needs (50%), Wants (30%), and Savings (20%)
- Category and subcategory breakdown with treemaps
- Year-over-year spending comparisons
- Recurring transaction detection
- 4 Investment Categories: FD/Bonds, Mutual Funds, PPF/EPF, Stocks
- Track both inflows (investments) and outflows (redemptions)
- Net investment calculations per category
- Asset allocation visualization
- Interactive Sankey diagrams showing money flow
- Income to Expenses/Savings breakdown
- Monthly and yearly views
- Financial Health Score with 8 metrics across 4 pillars (Spend, Save, Borrow, Plan)
- Income vs Expense trends and forecasting
- Tax planning for India FY (April-March)
- Net Worth tracking across all accounts
- Anomaly detection and review
- Budget tracking and goals
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript 5.9, Vite 7, Tailwind CSS 4, Recharts 3, Framer Motion 12 |
| Auth | OAuth 2.0 (Google, GitHub), JWT tokens (PyJWT) |
| Backend | Python 3.11+, FastAPI, SQLAlchemy 2, Alembic |
| Database | SQLite (dev), Neon PostgreSQL 17 (prod) |
| State | TanStack Query 5, Zustand 5 |
| Deployment | GitHub Pages (frontend), Render (backend), Neon (database) |
| CI/CD | GitHub Actions (lint, type-check, build, deploy) |
| Package Mgmt | pnpm 10 (frontend), uv (backend) |
View Mermaid source (for editing)
Diagrams generated from .mmd files in docs/images/ using:
npx -y @mermaid-js/mermaid-cli -i docs/images/<name>.mmd -o docs/images/<name>.svg -b transparentFor detailed architecture docs, see docs/architecture.md.
# Clone the repository
git clone https://github.com/Sagargupta16/ledger-sync.git
cd ledger-sync
# Install root dependencies
pnpm install
# Setup backend + frontend in parallel
pnpm run setup
# Start both servers
pnpm run devAccess the app:
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
ledger-sync/
├── backend/ # Python FastAPI backend
│ ├── src/ledger_sync/ # Main application
│ │ ├── api/ # REST endpoints
│ │ ├── core/ # Business logic (reconciler, sync, analytics)
│ │ ├── db/ # Database models & session
│ │ ├── ingest/ # Excel processing pipeline
│ │ └── schemas/ # Pydantic request/response models
│ └── tests/ # pytest tests
├── frontend/ # React + TypeScript frontend
│ └── src/
│ ├── pages/ # 22 page components (split into subdirectories)
│ │ ├── settings/ # Settings sections (20 files)
│ │ ├── goals/ # Goals sub-components (13 files)
│ │ ├── comparison/ # Comparison sub-components (13 files)
│ │ └── subscription-tracker/ # Subscription sub-components (13 files)
│ ├── components/ # UI & analytics components (60+)
│ ├── hooks/ # React Query hooks & custom hooks
│ ├── constants/ # Colors, chart tokens, animations
│ ├── store/ # Zustand global stores
│ ├── services/ # API client (Axios)
│ ├── lib/ # Utility functions
│ └── types/ # Shared TypeScript types
├── .github/workflows/ # CI pipeline
└── CHANGELOG.md # Version history
| Page | Description |
|---|---|
| Home | Landing page |
| Dashboard | Overview with KPIs, sparklines, and quick insights |
| Upload & Sync | Drag-and-drop upload with sample format preview |
| Transactions | Full transaction list with filters and search |
| Spending Analysis | 50/30/20 rule, treemap, top merchants, subcategories |
| Income Analysis | Income sources, growth tracking, breakdown |
| Comparison | Period-over-period financial comparison |
| Trends & Forecasts | Trend lines, rolling averages, cash flow forecast |
| Cash Flow | Sankey diagram of money flow |
| Investment Analytics | Portfolio across 4 categories |
| Mutual Fund Projection | SIP calculator and projections |
| Returns Analysis | Investment returns tracking |
| Tax Planning | India FY-based tax insights and slab breakdown |
| Net Worth | Assets, liabilities, and credit card health |
| Budget | Budget tracking and monitoring |
| Goals | Financial goal setting and progress |
| Insights | Advanced analytics (velocity, stability, milestones) |
| Anomaly Review | Flag and review unusual transactions |
| Year in Review | Annual financial summary |
| Subscription Tracker | Recurring expense detection, confirm/add manually |
| Bill Calendar | Monthly calendar view of upcoming bills |
| Settings | Preferences, account mappings, categories |
The app is deployed for free using three services:
| Service | Platform | Details |
|---|---|---|
| Frontend | GitHub Pages | Auto-deploys on push via GitHub Actions |
| Backend | Render (free tier) | FastAPI on Python 3.12, ~30s cold start after idle |
| Database | Neon PostgreSQL | Free tier, 0.5 GB, Singapore region |
See Deployment Guide for full setup instructions.
Ledger Sync uses OAuth 2.0 for authentication — no passwords to manage.
- Google Sign-In and GitHub Sign-In buttons on the login page
- Backend exchanges OAuth codes for user info, then issues JWT tokens
- OAuth providers are configurable via environment variables
- Buttons only appear for providers that are configured
- Create OAuth apps at Google Cloud Console and/or GitHub Developer Settings
- Set redirect URIs to
http://localhost:5173/auth/callback/googleandhttp://localhost:5173/auth/callback/github - Add credentials to
backend/.env:
LEDGER_SYNC_GOOGLE_CLIENT_ID=your-google-client-id
LEDGER_SYNC_GOOGLE_CLIENT_SECRET=your-google-secret
LEDGER_SYNC_GITHUB_CLIENT_ID=your-github-client-id
LEDGER_SYNC_GITHUB_CLIENT_SECRET=your-github-secret
LEDGER_SYNC_FRONTEND_URL=http://localhost:5173LEDGER_SYNC_DATABASE_URL=sqlite:///./ledger_sync.db # Local dev (SQLite)
LEDGER_SYNC_ENVIRONMENT=development # development | production
LEDGER_SYNC_GOOGLE_CLIENT_ID=... # OAuth (optional)
LEDGER_SYNC_GOOGLE_CLIENT_SECRET=...
LEDGER_SYNC_GITHUB_CLIENT_ID=...
LEDGER_SYNC_GITHUB_CLIENT_SECRET=...
LEDGER_SYNC_FRONTEND_URL=http://localhost:5173 # OAuth redirect base URLVITE_API_BASE_URL=http://localhost:8000 # Set in GitHub Actions variable for production- Changelog — Version history and release notes
- Architecture — System design and data flow
- API Reference — REST endpoint documentation
- Database Schema — Models and migrations
- Development Guide — Setup and workflow
- Testing Guide — Test strategies
- Deployment Guide — Production deployment
Contributions are welcome! Please read the Development Guide first.
MIT License - see LICENSE for details.