See where every rupee goes. Import your bank statements, get instant insights, and finally understand your money -- all from a single, self-hosted dashboard you actually own.
No subscriptions. No data harvesting. Just a focused set of analytics pages built from your own Excel exports, running on your own infrastructure.
Live: sagargupta.online/ledger-sync | Demo: Try it now | API: ledger-sync-api.vercel.app
- Chat with your financial data -- floating widget in the bottom-right corner, ask any question about your spending, trends, tax, or goals
- Two modes:
- App mode (default) -- zero setup, works immediately for every new user. Uses the server's shared Bedrock key, rate-limited to 10 messages/day (configurable via
LEDGER_SYNC_AI_DAILY_MESSAGE_LIMIT) - BYOK mode -- paste your own OpenAI / Anthropic / AWS Bedrock key in Settings for unlimited use; your key is encrypted at rest with AES-256-GCM and per-user daily/monthly token caps are available
- App mode (default) -- zero setup, works immediately for every new user. Uses the server's shared Bedrock key, rate-limited to 10 messages/day (configurable via
- Tool calling (not context stuffing) -- the bot has 15 read-only tools (
search_transactions,get_monthly_summary,get_net_worth,get_fy_summary,get_category_spending,list_recurring,list_goals,get_investment_holdings, and more) and picks what to call based on your question. Works across OpenAI, Anthropic, and Bedrock with a shared tool schema - Latest models -- OpenAI (O3, O4 Mini, GPT-4.1, GPT-4o), Anthropic (Claude Opus 4.7, Sonnet 4.6, Haiku 4.5), AWS Bedrock (same Claude models)
- Usage tracking -- every round-trip is logged (tokens in/out, estimated USD); today / month-to-date / all-time rollups visible in the chat widget badge
- User-scoped -- every tool is enforced at the FastAPI dependency level with
CurrentUser; the LLM cannot see another user's data - Hidden in demo mode -- chat widget only appears when you're logged in
- Try before you sign up - Click "Try Demo" on the landing page or visit
/demodirectly - Explore the full dashboard with ~500 realistic sample transactions (Indian household model)
- All 23 pages render with pre-computed analytics data, zero backend calls
- Floating banner with quick sign-up and exit options
- Mutations (upload, settings, budgets, goals) are gracefully blocked with toast notifications
- Drag-and-drop Excel (.xlsx, .xls) and CSV uploads with beautiful hero UI
- Client-side parsing via SheetJS -- files never leave your browser, only structured data is sent to the server
- Browser-native SHA-256 hashing for intelligent duplicate detection
- Idempotent syncing -- re-upload anytime without duplicates
- Four-phase upload UX: Parsing (client) -> Processing (server) -> Uploading -> Computing Analytics
- 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
- India FY tax estimation -- old vs new regime comparison, slab breakdown, surcharge, cess
- Salary-based projections -- input your CTC structure, RSU grants, and growth assumptions to project multi-year tax liability
- FIRE Calculator -- compute FIRE number, Coast FIRE, years to FIRE, and savings rate from your actual spending data; Lean / Barista / Standard / Fat FIRE variants with adjustable SWR, real return, retirement horizon, and part-time-income slider (for soft-landing planning)
- Retirement corpus calculator -- inflation-adjusted corpus, monthly SIP needed, lump-sum alternative, with projection chart
- Financial Health Score with 8 metrics across 4 pillars (Spend, Save, Borrow, Plan)
- Income vs Expense trends and forecasting
- Net Worth tracking across all accounts
- Anomaly detection and review
- Budget tracking and goals
- 15 supported currencies -- USD, EUR, GBP, JPY, CAD, AUD, CHF, SGD, AED, and more
- Live exchange rates from the European Central Bank (via frankfurter.app), cached 24 hours
- Quick-switch currency from the sidebar or set a default in Settings
- All amounts convert instantly across every page -- no reload needed
- Auto-derives number format, symbol, and symbol position from your currency choice
- Account classification - Automatically categorizes accounts by keyword (EPF/PPF/MF/FD/Stocks to Investments, HDFC/SBI/ICICI to Bank Accounts, etc.)
- Income classification - Auto-assigns Salary/Freelance to Taxable, Dividends/Interest to Investment Returns, Cashbacks to Non-taxable
- Investment mapping - Auto-maps investment accounts to types (Groww MF to Mutual Funds, PPF Account to PPF/EPF, etc.)
| 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), Vercel (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/CSV processing (CLI path; web uploads parsed client-side)
│ │ └── schemas/ # Pydantic request/response models
│ └── tests/ # pytest tests
├── frontend/ # React + TypeScript frontend
│ └── src/
│ ├── pages/ # 23 page components (split into subdirectories)
│ │ ├── settings/ # Settings sections (21 files, incl. SalaryStructureSection)
│ │ ├── goals/ # Goals sub-components (13 files)
│ │ ├── comparison/ # Comparison sub-components (13 files)
│ │ └── subscription-tracker/ # Subscription sub-components (3 files)
│ ├── components/ # UI & analytics components (60+)
│ ├── hooks/ # React Query hooks & custom hooks
│ ├── constants/ # Colors, chart tokens, animations, column mappings
│ ├── store/ # Zustand global stores
│ ├── services/ # API client (Axios)
│ ├── lib/ # Utility functions (file parser, formatters, tax/projection calculators)
│ │ └── demo/ # Demo mode (data generators, cache seeder)
│ └── types/ # Shared TypeScript types
├── .github/workflows/ # CI pipeline
└── CHANGELOG.md # Version history
Every page focuses on a specific question you'd ask about your money. A one-line summary is below; for the detailed data catalog -- what each page shows, where the numbers come from, and what decisions it helps you make -- see docs/PAGES.md.
| Page | Answers |
|---|---|
| Home / Dashboard | "What happened this month at a glance?" |
| Transactions | "Give me the raw ledger." |
| Cash Flow (Sankey) | "Where did my income actually go?" |
| Expense Analysis | "Am I overspending, and on what?" (50/30/20, treemap, top merchants) |
| Income Analysis | "Where does my money come from?" (by tax bucket) |
| Comparison | "How does this month / FY compare to last?" |
| Year in Review | "Full-year retrospective" (Spotify-Wrapped-style) |
| Net Worth | "What am I actually worth today?" (assets vs liabilities, trend) |
| Trends & Forecasts | "Where is my wealth trending?" (regression + projection) |
| Investment Analytics | "How is my portfolio doing?" (across 8 investment types) |
| SIP Projections | "What will my SIPs be worth later?" |
| Returns Analysis | "Which holdings are winners?" (XIRR + CAGR ranking) |
| Recurring / Subscriptions | "What's auto-draining my account?" (detected + user-confirmed) |
| Bill Calendar | "What's due when?" (month grid with paid/missed indicators) |
| Budgets | "Am I staying within limits this month?" |
| Goals | "How close am I to my savings goals?" |
| FIRE Calculator | "When can I retire?" (Lean / Barista / Standard / Fat variants) |
| Anomaly Review | "Did anything weird happen?" |
| Income Tax Planning | "What will I owe this FY?" (Old vs New regime, multi-year projection) |
| GST Analysis | "What indirect tax did I pay?" |
| Upload & Sync | "How do I add more data?" |
| Settings | "Configure the app." (11 sections; all collapsed by default) |
The app is deployed for free using three services:
| Service | Platform | Details |
|---|---|---|
| Frontend | GitHub Pages | Auto-deploys on push via GitHub Actions |
| Backend | Vercel (serverless) | FastAPI via Mangum adapter, zero cold starts |
| Database | Neon PostgreSQL | Free tier, 0.5 GB, Singapore region (Vercel integration) |
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 with granular release notes
- Architecture - System design and data flow
- Calculations & Data Processing - How every metric, chart, and derived number is computed
- 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.