{"id":50103657,"url":"https://github.com/shubhamjain2998/expense-tracking-backend","last_synced_at":"2026-05-23T09:03:13.451Z","repository":{"id":345242954,"uuid":"1183456272","full_name":"shubhamjain2998/expense-tracking-backend","owner":"shubhamjain2998","description":"FastAPI backend for tracking monthly expenses against an annual budget — PDF ingestion, fuzzy auto-categorisation, expense splitting, and analytics","archived":false,"fork":false,"pushed_at":"2026-05-22T02:45:49.000Z","size":339,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T05:39:06.184Z","etag":null,"topics":["expense-tracker","fastapi","finance","pandas","pdfplumber","postgresql","python","rapidfuzz","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shubhamjain2998.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-16T16:16:04.000Z","updated_at":"2026-05-22T02:45:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shubhamjain2998/expense-tracking-backend","commit_stats":null,"previous_names":["shubhamjain2998/expense-tracking-backend"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/shubhamjain2998/expense-tracking-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain2998%2Fexpense-tracking-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain2998%2Fexpense-tracking-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain2998%2Fexpense-tracking-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain2998%2Fexpense-tracking-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shubhamjain2998","download_url":"https://codeload.github.com/shubhamjain2998/expense-tracking-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain2998%2Fexpense-tracking-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33389229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"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":["expense-tracker","fastapi","finance","pandas","pdfplumber","postgresql","python","rapidfuzz","sqlalchemy"],"created_at":"2026-05-23T09:03:07.052Z","updated_at":"2026-05-23T09:03:13.438Z","avatar_url":"https://github.com/shubhamjain2998.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Expense Tracker — Backend\n\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/fastapi-0.115-009688.svg)](https://fastapi.tiangolo.com/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Conventional Commits](https://img.shields.io/badge/conventional%20commits-1.0.0-fa6673.svg)](https://www.conventionalcommits.org)\n\n\u003e FastAPI backend for a personal finance app that ingests Indian bank-statement PDFs, auto-categorises transactions with fuzzy matching, supports expense splits between people, and exposes analytics for monthly and year-to-date spend against an annual budget.\n\n---\n\n## What is this?\n\nA self-hosted REST API for tracking personal expenses against an **annual** budget. It is built for one user at a time (multi-tenant by `user_id`, but no team features) and is opinionated for the Indian context — INR-aware amounts, financial-year period mode (April → March), and parsers tuned for HDFC / Axis / SBI statement formats.\n\nIt is the backend half of a two-repository project. The frontend lives at **[shubhamjain2998/expense-tracking-frontend](https://github.com/shubhamjain2998/expense-tracking-frontend)** — see [Companion frontend](#companion-frontend) below.\n\n## Highlights\n\n- **PDF ingestion** — uploads are parsed in memory with `pdfplumber`; no statement file is ever written to disk.\n- **Duplicate guard** — SHA-256 of the file body is recorded so the same statement cannot be imported twice.\n- **Fuzzy auto-categorisation** — `RapidFuzz` matches each transaction description against learned `category_mappings` at ≥ 80% similarity.\n- **Expense splits** — every processed transaction can be shared between people by percentage or fixed amount; per-share settlement is tracked.\n- **Period-aware analytics** — endpoints accept `period_mode=calendar|fy` so the same `(year, month)` parameters work for both Jan–Dec and Apr–Mar reporting.\n- **Cookie-first auth** — `httpOnly` cookie is the preferred path; `Authorization: Bearer` is still accepted for backwards compatibility.\n- **Soft delete + restore** — raw transactions are never hard-deleted, so import history is auditable and recoverable.\n\n## Tech stack\n\n| Layer | Tool | Version |\n|---|---|---|\n| Web framework | FastAPI | `0.115.6` |\n| ASGI server | Uvicorn | `0.32.1` |\n| ORM | SQLAlchemy | `2.0.36` |\n| Migrations | Alembic | `1.14.0` |\n| Database | PostgreSQL (Supabase) | 15+ |\n| PDF parsing | pdfplumber | `0.11.4` |\n| Fuzzy matching | RapidFuzz | `3.10.1` |\n| Validation | Pydantic | `2.10.3` |\n| Auth | PyJWT + bcrypt | `2.12.1` / `4.2.1` |\n| Tests | pytest | `8+` |\n| Lint / format | flake8 + black | `7.3` / `25.11` |\n\nPython 3.11 or newer is required.\n\n## Quick start\n\n```bash\ngit clone git@github.com:shubhamjain2998/expense-tracking-backend.git\ncd expense-tracking-backend\npython -m venv venv \u0026\u0026 source venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env       # then edit DATABASE_URL + SUPABASE_JWT_SECRET\nalembic upgrade head\npython server.py           # http://localhost:8000\n```\n\nSwagger UI is then available at \u003chttp://localhost:8000/docs\u003e, ReDoc at \u003chttp://localhost:8000/redoc\u003e, and a health probe at \u003chttp://localhost:8000/health\u003e.\n\nSee [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the full local-development walkthrough.\n\n## Repository tour\n\n```\n.\n├── app/                   # FastAPI application package\n│   ├── main.py            #   entry point + middleware + router wiring\n│   ├── config.py          #   pydantic-settings (env vars)\n│   ├── database.py        #   SQLAlchemy engine + session factory\n│   ├── models.py          #   all SQLAlchemy table definitions\n│   ├── schemas.py         #   all Pydantic request / response models\n│   ├── auth.py            #   JWT dependency (cookie or bearer)\n│   ├── routers/           #   one file per domain (auth, budget, …)\n│   └── services/          #   pdf_parser, text_parser, normalizer, period helpers\n├── alembic/               # database migrations (versions/ holds the chain)\n├── tests/                 # pytest suite + fixtures\n├── scripts/               # one-off maintenance scripts\n├── docs/                  # architecture, API, database, deployment, etc.\n├── server.py              # uvicorn launcher for local dev\n└── requirements.txt       # production dependencies\n```\n\n## How it works\n\n```\nSetup (once/year)   →   Ingest (monthly)   →   Process       →   Analyse\nConfigure budget        Upload PDF              Auto + manual     Dashboard\n```\n\n**Setup** — Define an annual budget: a list of categories (Groceries, Rent, Travel, …) with allocated monthly amounts, stored once in `budget_plans`.\n\n**Ingest** — Accept a PDF bank or card statement, parse it in memory with `pdfplumber`, extract rows (date · description · amount), and save them to `raw_transactions` with `status=pending`.\n\n**Process** — Review the raw table and soft-delete non-expense rows; then `POST /transactions/auto-categorise` runs RapidFuzz over learned mappings and pre-fills matches ≥ 80%; manually assign the rest with `POST /transactions/process`, optionally saving the mapping so it auto-applies next month.\n\n**Analyse** — `/dashboard/*` returns budget vs. actual per category, monthly trend, year-to-date totals, and a split ledger showing each person's share of shared expenses.\n\nA full architecture diagram lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n## Companion frontend\n\nThis API is consumed by the React + TypeScript SPA at **[shubhamjain2998/expense-tracking-frontend](https://github.com/shubhamjain2998/expense-tracking-frontend)**.\n\n```\n┌─────────────────────────┐      HTTPS / JSON      ┌─────────────────────────┐\n│  Frontend (Vercel)      │ ─────────────────────▶ │  Backend (Render)       │\n│  React + Vite + TS      │                        │  FastAPI + SQLAlchemy   │\n└─────────────────────────┘                        └────────────┬────────────┘\n                                                                │\n                                                                ▼\n                                                   ┌─────────────────────────┐\n                                                   │  Database (Supabase)    │\n                                                   │  PostgreSQL             │\n                                                   └─────────────────────────┘\n```\n\nThe two repositories are versioned independently. CORS is configured per the `FRONTEND_ORIGIN` env var, and auth tokens are exchanged via `httpOnly` cookies (preferred) or `Authorization: Bearer` (legacy).\n\n## Documentation\n\n| Document | What's inside |\n|---|---|\n| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | System design, module breakdown, request lifecycle, key design decisions. |\n| [`docs/API.md`](docs/API.md) | Curated endpoint reference grouped by domain; sample requests and responses. Points to Swagger for the full schema. |\n| [`docs/DATABASE.md`](docs/DATABASE.md) | Mermaid ERD, table-by-table description, migrations workflow. |\n| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Render + Supabase setup; env var reference; troubleshooting. |\n| [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | Local dev walkthrough; how to add an endpoint / model / migration. |\n| [`docs/TESTING.md`](docs/TESTING.md) | pytest layout, fixtures, coverage expectations. |\n| [`docs/ROADMAP.md`](docs/ROADMAP.md) | What's shipped, what's in-flight, what's planned. |\n| [`docs/FAQ.md`](docs/FAQ.md) | Recurring questions a new contributor would ask. |\n| [`docs/GLOSSARY.md`](docs/GLOSSARY.md) | Domain terms (raw vs. processed transaction, mapping, share, settlement, …). |\n| [`docs/examples/api.http`](docs/examples/api.http) | Runnable requests for VS Code REST Client / JetBrains HTTP client. |\n| [`CHANGELOG.md`](CHANGELOG.md) | Release history. |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Commit conventions, branch naming, PR checklist. |\n| [`SECURITY.md`](SECURITY.md) | Vulnerability reporting policy. |\n| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Community standards. |\n\n## Project status\n\nTagged `v1.0.0` is the latest release. Active development continues — see [`docs/ROADMAP.md`](docs/ROADMAP.md) for what's planned. Issues and discussions are open; see [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a PR.\n\n## License\n\n[MIT](LICENSE) © 2026 Shubham Jain.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamjain2998%2Fexpense-tracking-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshubhamjain2998%2Fexpense-tracking-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamjain2998%2Fexpense-tracking-backend/lists"}