{"id":47423045,"url":"https://github.com/Sagargupta16/ledger-sync","last_synced_at":"2026-04-04T23:00:31.210Z","repository":{"id":336783399,"uuid":"1131147651","full_name":"Sagargupta16/ledger-sync","owner":"Sagargupta16","description":"Ledger Sync — Transform messy Excel bank statements into beautiful financial dashboards with Sankey diagrams and anomaly detection","archived":false,"fork":false,"pushed_at":"2026-03-25T00:30:54.000Z","size":3828,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T06:47:27.885Z","etag":null,"topics":["dashboard","fastapi","finance","python","react","sqlite","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"https://sagargupta.online/ledger-sync/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sagargupta16.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T14:48:47.000Z","updated_at":"2026-03-22T01:04:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Sagargupta16/ledger-sync","commit_stats":null,"previous_names":["sagargupta16/ledger-sync"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Sagargupta16/ledger-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagargupta16%2Fledger-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagargupta16%2Fledger-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagargupta16%2Fledger-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagargupta16%2Fledger-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sagargupta16","download_url":"https://codeload.github.com/Sagargupta16/ledger-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagargupta16%2Fledger-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31418285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dashboard","fastapi","finance","python","react","sqlite","tailwindcss","typescript"],"created_at":"2026-03-21T18:00:31.269Z","updated_at":"2026-04-04T23:00:31.168Z","avatar_url":"https://github.com/Sagargupta16.png","language":"TypeScript","funding_links":[],"categories":["Open Source Projects"],"sub_categories":["New and Noteworthy"],"readme":"# Ledger Sync\n\n**Your personal finance command center** - Transform messy Excel exports into a beautiful, insightful financial dashboard.\n\nLedger 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.\n\n![Version](https://img.shields.io/badge/version-0.8.0-green.svg)\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Python](https://img.shields.io/badge/python-3.11+-blue.svg)\n![React](https://img.shields.io/badge/react-19-blue.svg)\n![TypeScript](https://img.shields.io/badge/typescript-5.9-blue.svg)\n\n**Live:** [sagargupta.online/ledger-sync](https://sagargupta.online/ledger-sync/) | **API:** [ledger-sync.onrender.com](https://ledger-sync.onrender.com/docs)\n\n## Features\n\n### Smart Upload \u0026 Sync\n\n- Drag-and-drop Excel uploads with beautiful hero UI\n- Intelligent duplicate detection using SHA-256 hashing\n- Idempotent syncing - re-upload anytime without duplicates\n- Real-time toast notifications for upload status\n\n### Spending Analysis\n\n- **50/30/20 Budget Rule** - Track Needs (50%), Wants (30%), and Savings (20%)\n- Category and subcategory breakdown with treemaps\n- Year-over-year spending comparisons\n- Recurring transaction detection\n\n### Investment Portfolio\n\n- **4 Investment Categories**: FD/Bonds, Mutual Funds, PPF/EPF, Stocks\n- Track both inflows (investments) and outflows (redemptions)\n- Net investment calculations per category\n- Asset allocation visualization\n\n### Cash Flow Visualization\n\n- Interactive Sankey diagrams showing money flow\n- Income to Expenses/Savings breakdown\n- Monthly and yearly views\n\n### Analytics \u0026 Insights\n\n- Financial Health Score with 8 metrics across 4 pillars (Spend, Save, Borrow, Plan)\n- Income vs Expense trends and forecasting\n- Tax planning for India FY (April-March)\n- Net Worth tracking across all accounts\n- Anomaly detection and review\n- Budget tracking and goals\n\n## Tech Stack\n\n| Layer            | Technology                                                                   |\n| ---------------- | ---------------------------------------------------------------------------- |\n| **Frontend**     | React 19, TypeScript 5.9, Vite 7, Tailwind CSS 4, Recharts 3, Framer Motion 12 |\n| **Auth**         | OAuth 2.0 (Google, GitHub), JWT tokens (PyJWT)                              |\n| **Backend**      | Python 3.11+, FastAPI, SQLAlchemy 2, Alembic                                |\n| **Database**     | SQLite (dev), Neon PostgreSQL 17 (prod)                                      |\n| **State**        | TanStack Query 5, Zustand 5                                                 |\n| **Deployment**   | GitHub Pages (frontend), Render (backend), Neon (database)                   |\n| **CI/CD**        | GitHub Actions (lint, type-check, build, deploy)                             |\n| **Package Mgmt** | pnpm 10 (frontend), uv (backend)                                            |\n\n## Architecture\n\n### System Overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/system-overview.svg\" alt=\"System Architecture\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n### Upload \u0026 Sync Pipeline\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/upload-pipeline.svg\" alt=\"Upload Pipeline\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n### Authentication Flow\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/auth-flow.svg\" alt=\"Authentication Flow\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n### Backend Layer Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/backend-layers.svg\" alt=\"Backend Layers\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eView Mermaid source (for editing)\u003c/summary\u003e\n\nDiagrams generated from `.mmd` files in `docs/images/` using:\n\n```bash\nnpx -y @mermaid-js/mermaid-cli -i docs/images/\u003cname\u003e.mmd -o docs/images/\u003cname\u003e.svg -b transparent\n```\n\n\u003c/details\u003e\n\nFor detailed architecture docs, see [docs/architecture.md](docs/architecture.md).\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/Sagargupta16/ledger-sync.git\ncd ledger-sync\n\n# Install root dependencies\npnpm install\n\n# Setup backend + frontend in parallel\npnpm run setup\n\n# Start both servers\npnpm run dev\n```\n\n**Access the app:**\n\n- Frontend: http://localhost:5173\n- Backend API: http://localhost:8000\n- API Docs: http://localhost:8000/docs\n\n## Project Structure\n\n```\nledger-sync/\n├── backend/                # Python FastAPI backend\n│   ├── src/ledger_sync/    # Main application\n│   │   ├── api/            # REST endpoints\n│   │   ├── core/           # Business logic (reconciler, sync, analytics)\n│   │   ├── db/             # Database models \u0026 session\n│   │   ├── ingest/         # Excel processing pipeline\n│   │   └── schemas/        # Pydantic request/response models\n│   └── tests/              # pytest tests\n├── frontend/               # React + TypeScript frontend\n│   └── src/\n│       ├── pages/          # 23 page components (split into subdirectories)\n│       │   ├── settings/       # Settings sections (20 files)\n│       │   ├── goals/          # Goals sub-components (13 files)\n│       │   ├── comparison/     # Comparison sub-components (13 files)\n│       │   └── subscription-tracker/  # Subscription sub-components (13 files)\n│       ├── components/     # UI \u0026 analytics components (60+)\n│       ├── hooks/          # React Query hooks \u0026 custom hooks\n│       ├── constants/      # Colors, chart tokens, animations\n│       ├── store/          # Zustand global stores\n│       ├── services/       # API client (Axios)\n│       ├── lib/            # Utility functions\n│       └── types/          # Shared TypeScript types\n├── .github/workflows/      # CI pipeline\n└── CHANGELOG.md            # Version history\n```\n\n## Pages\n\n| Page                       | Description                                         |\n| -------------------------- | --------------------------------------------------- |\n| **Home**                   | Landing page                                        |\n| **Dashboard**              | Overview with KPIs, sparklines, and quick insights  |\n| **Upload \u0026 Sync**          | Drag-and-drop upload with sample format preview     |\n| **Transactions**           | Full transaction list with filters and search       |\n| **Spending Analysis**      | 50/30/20 rule, treemap, top merchants, subcategories|\n| **Income Analysis**        | Income sources, growth tracking, breakdown          |\n| **Comparison**             | Period-over-period financial comparison              |\n| **Trends \u0026 Forecasts**     | Trend lines, rolling averages, cash flow forecast   |\n| **Cash Flow**              | Sankey diagram of money flow                        |\n| **Investment Analytics**   | Portfolio across 4 categories                       |\n| **Mutual Fund Projection** | SIP calculator and projections                      |\n| **Returns Analysis**       | Investment returns tracking                         |\n| **Tax Planning**           | India FY-based tax insights and slab breakdown      |\n| **Net Worth**              | Assets, liabilities, and credit card health         |\n| **Budget**                 | Budget tracking and monitoring                      |\n| **Goals**                  | Financial goal setting and progress                 |\n| **Insights**               | Advanced analytics (velocity, stability, milestones)|\n| **Anomaly Review**         | Flag and review unusual transactions                |\n| **Year in Review**         | Annual financial summary                            |\n| **Subscription Tracker**   | Recurring expense detection, confirm/add manually   |\n| **Bill Calendar**          | Monthly calendar view of upcoming bills             |\n| **Settings**               | Preferences, account mappings, categories           |\n\n## Deployment\n\nThe app is deployed for free using three services:\n\n| Service | Platform | Details |\n|---------|----------|---------|\n| Frontend | GitHub Pages | Auto-deploys on push via GitHub Actions |\n| Backend | Render (free tier) | FastAPI on Python 3.12, ~30s cold start after idle |\n| Database | Neon PostgreSQL | Free tier, 0.5 GB, Singapore region |\n\nSee [Deployment Guide](docs/DEPLOYMENT.md) for full setup instructions.\n\n## Authentication\n\nLedger Sync uses **OAuth 2.0** for authentication - no passwords to manage.\n\n- **Google Sign-In** and **GitHub Sign-In** buttons on the login page\n- Backend exchanges OAuth codes for user info, then issues JWT tokens\n- OAuth providers are configurable via environment variables\n- Buttons only appear for providers that are configured\n\n### Setting Up OAuth (Local Dev)\n\n1. Create OAuth apps at [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and/or [GitHub Developer Settings](https://github.com/settings/developers)\n2. Set redirect URIs to `http://localhost:5173/auth/callback/google` and `http://localhost:5173/auth/callback/github`\n3. Add credentials to `backend/.env`:\n\n```env\nLEDGER_SYNC_GOOGLE_CLIENT_ID=your-google-client-id\nLEDGER_SYNC_GOOGLE_CLIENT_SECRET=your-google-secret\nLEDGER_SYNC_GITHUB_CLIENT_ID=your-github-client-id\nLEDGER_SYNC_GITHUB_CLIENT_SECRET=your-github-secret\nLEDGER_SYNC_FRONTEND_URL=http://localhost:5173\n```\n\n## Configuration\n\n### Backend Environment (`backend/.env`)\n\n```env\nLEDGER_SYNC_DATABASE_URL=sqlite:///./ledger_sync.db    # Local dev (SQLite)\nLEDGER_SYNC_ENVIRONMENT=development                     # development | production\nLEDGER_SYNC_GOOGLE_CLIENT_ID=...                        # OAuth (optional)\nLEDGER_SYNC_GOOGLE_CLIENT_SECRET=...\nLEDGER_SYNC_GITHUB_CLIENT_ID=...\nLEDGER_SYNC_GITHUB_CLIENT_SECRET=...\nLEDGER_SYNC_FRONTEND_URL=http://localhost:5173          # OAuth redirect base URL\n```\n\n### Frontend Environment\n\n```env\nVITE_API_BASE_URL=http://localhost:8000                # Set in GitHub Actions variable for production\n```\n\n## Documentation\n\n- [Changelog](CHANGELOG.md) - Version history and release notes\n- [Architecture](docs/architecture.md) - System design and data flow\n- [API Reference](docs/API.md) - REST endpoint documentation\n- [Database Schema](docs/DATABASE.md) - Models and migrations\n- [Development Guide](docs/DEVELOPMENT.md) - Setup and workflow\n- [Testing Guide](docs/TESTING.md) - Test strategies\n- [Deployment Guide](docs/DEPLOYMENT.md) - Production deployment\n\n## Contributing\n\nContributions are welcome! Please read the [Development Guide](docs/DEVELOPMENT.md) first.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSagargupta16%2Fledger-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSagargupta16%2Fledger-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSagargupta16%2Fledger-sync/lists"}