Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
285 changes: 126 additions & 159 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,190 +1,157 @@
<div align="center">

# 📒 Khata

### Money clarity for everyday India

Khata auto-logs your UPI spends from SMS, keeps your *udhaar* (lending) straight by
person, splits trips with friends, flags recurring bills before they hit, and shows you
where the money actually goes — all in an installable PWA.

[![Version](https://img.shields.io/badge/version-0.11.0-1f6feb)](apps/web/package.json)
![PWA](https://img.shields.io/badge/PWA-installable-5a3fc0)
![React](https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=white)
![Convex](https://img.shields.io/badge/Convex-backend-f3502c)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-v4-38bdf8?logo=tailwindcss&logoColor=white)
![Vite](https://img.shields.io/badge/Vite-6-646cff?logo=vite&logoColor=white)
![Capacitor](https://img.shields.io/badge/Capacitor-native%20wrapper-119eff?logo=capacitor&logoColor=white)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

---

## 📱 Screenshots


<table>
<tr>
<td align="center">
<!-- docs/screenshots/web-expenses.png -->
<img src="https://placehold.co/390x844/1f6feb/ffffff?text=Web+%E2%80%94+Expenses" width="240" alt="Web — Expenses" /><br/>
<sub><b>Web</b> — Expenses</sub>
</td>
<td align="center">
<!-- docs/screenshots/pwa-install.png -->
<img src="https://placehold.co/390x844/5a3fc0/ffffff?text=PWA+%E2%80%94+Installed" width="240" alt="PWA — Installed" /><br/>
<sub><b>PWA</b> — Installed</sub>
</td>
<td align="center">
<!-- docs/screenshots/mobile-home.png -->
<img src="https://placehold.co/390x844/119eff/ffffff?text=Mobile+%E2%80%94+Home" width="240" alt="Mobile — Home" /><br/>
<sub><b>Mobile</b> — Home</sub>
</td>
</tr>
<tr>
<td align="center">
<!-- docs/screenshots/web-insights.png -->
<img src="https://placehold.co/390x844/0d1117/8b949e?text=Insights" width="240" alt="Insights" /><br/>
<sub>Insights — trends &amp; charts</sub>
</td>
<td align="center">
<!-- docs/screenshots/web-udhaar.png -->
<img src="https://placehold.co/390x844/0d1117/8b949e?text=Udhaar" width="240" alt="Udhaar ledger" /><br/>
<sub>Udhaar — person ledger</sub>
</td>
<td align="center">
<!-- docs/screenshots/mobile-sms.png -->
<img src="https://placehold.co/390x844/0d1117/8b949e?text=UPI+SMS" width="240" alt="Auto-logged UPI SMS" /><br/>
<sub>Auto-logged UPI SMS</sub>
</td>
</tr>
</table>

---

## ✨ Features

- **Auto-log UPI from SMS** — On Android (via Capacitor), Khata reads UPI transaction
SMS and logs them automatically. It captures the underlying UPI handle so garbled or
truncated merchant/person names get cleaned up — name a handle once and every future
transaction from it is labelled correctly.
- **Udhaar ledger that tracks a *person*, not a string** — A contact can have many
handles (phone numbers, VPAs, name spellings); their balance rolls up across all of
them. Record cash lending/repayment by hand, and **merge** duplicate people.
- **Trip splitter** — Split group expenses and settle up, with a one-tap
*"everyone's settled"* close that records remaining transfers as paid and silences
reminders.
- **Recurring-bill radar** — Detects monthly billers (rent, mess, Spotify, recharge)
from your spend history and reminds you a few days before they're due.
- **Per-category budgets** — Set spend caps and see safe-to-spend at a glance.
- **Insights** — Month-over-month trends, projected month-end, top-merchant drill-down,
and real donut/line charts.
- **Installable PWA** — Works offline-friendly, installs to your home screen. Amounts
are stored in **paise** (integers) to avoid floating-point errors.

---

## 🧱 Tech stack

| Layer | Tech |
|---|---|
| Frontend | Vite 6 + React 19 PWA (`vite-plugin-pwa`) |
| Styling | Tailwind CSS v4 (CSS custom-property theme tokens) |
| Backend | [Convex](https://convex.dev) — queries, mutations, actions, crons |
| Auth | `better-auth` + Convex adapter (Google Sign-In) |
| Native wrapper | Capacitor (UPI SMS reading, push notifications) |
| Tests | Vitest + `convex-test` |

---

## 📂 Project layout
<p align="center">
<img src="apps/web/public/favicon.svg" alt="Khata logo" width="88" height="88" />
</p>

```
Khata/
├── apps/
│ ├── web/ # Vite + React PWA — primary target, active development
│ └── mobile/ # Expo / React Native app — abandoned, left in place
├── convex/ # Convex backend (schema, queries, mutations, actions, crons)
├── docs/ # PRDs and screenshots
└── plan.md # Milestone source of truth
```
<h1 align="center">Khata</h1>

> **Pivot note:** `apps/mobile/` (Expo) is abandoned; all active work targets
> `apps/web/`. UPI SMS uses a thin Capacitor wrapper around the same web app.
<p align="center">
A personal expense tracker for India, built around UPI.<br />
It logs spends from bank SMS, tracks udhaar by person, and splits trips with friends.
</p>

---
<p align="center">
<a href="https://khata.raja-dev.me">Open the web app</a>
·
<a href="https://github.com/Anuraj-dev/Khata/releases/download/v0.14.1-debug/Khata-debug-84b5aae.apk">Download the Android APK</a>
·
<a href="#android">Install on Android</a>
·
<a href="#documentation">Docs</a>
</p>

## 🚀 Getting started
Khata reads the bank and UPI texts on your phone and logs each payment as an expense, so you don't type them in. Anything it can't read with confidence waits in a review queue. Udhaar, the money you lend and borrow, is tracked per person across all of that person's phone numbers and UPI IDs. Trips get their own splits and a single settle-up.

**Prerequisites:** [Bun](https://bun.sh) and a [Convex](https://convex.dev) account.
The web app is a Vite and React PWA on a Convex backend. You sign in with Google. The Android app wraps the same web build in Capacitor and adds native code for SMS, fingerprint confirmation and push notifications.

```bash
# 1. Install dependencies
bun install
## What you get

# 2. Configure env — copy the example and fill in your values
cp apps/web/.env.example apps/web/.env.local
# VITE_GOOGLE_CLIENT_ID — your Google OAuth web client ID
# VITE_APP_URL — public origin for trip-invite links (optional in dev)
- **Expenses from bank SMS on Android.** A background receiver posts each incoming text to the `/sms/ingest` route. Texts with a clear amount and direction are logged right away. The UPI reference becomes the expense's client ID, so a text that arrives twice is logged once.
- **A review queue for the rest.** Bank texts without a clear amount or direction wait in a review queue, and a push notification tells you to look. Pending and failed payments never get logged.
- **Udhaar by person.** A contact can own several handles, such as phone numbers and UPI IDs. Balances add up across all of them. Once you tag a payment to a contact, later payments from that contact's handles count automatically. Merge duplicate contacts when the same person shows up twice.
- **Trip splits with one settle-up.** Split each trip expense equally or by custom amounts. Settle all records the remaining transfers as paid and closes the trip. Invite a member with a link or QR code, and that member can read the trip, read-only, for seven days.
- **Recurring-bill radar.** A payee seen in three different months with consistent amounts gets suggested as a recurring bill. Confirm it to track it, or dismiss it so it never comes back. A push at 8:00 IST warns you about bills due within three days.
- **Budgets that alert once.** Set a monthly limit and optional per-category caps. You get a push at 80% and again at 100% of the limit, once each per month. Each category cap alerts once a month.
- **Your rows stay with your account.** Google sign-in is the only login. Every expense, contact and budget is stored under your account ID, and the backend filters queries by it. Trip invites are the one exception. Clearing all expenses or trips requires a typed confirmation, and on Android also a fingerprint or device PIN.
- **Offline writes that sync later.** The app shell is precached by a service worker, so it opens without a connection. An expense added offline waits in a retry queue in local storage, retries with backoff, and gives up after five attempts.

## Installation

| Platform | How to get it |
| --- | --- |
| **Web** | Open [khata.raja-dev.me](https://khata.raja-dev.me) and sign in. |
| **Android** | Sideload the [debug APK from v0.14.1-debug](https://github.com/Anuraj-dev/Khata/releases/download/v0.14.1-debug/Khata-debug-84b5aae.apk). |

### Web

Open the site and sign in with Google. To keep Khata on your home screen, use your browser's install option. The installed app opens in its own window. SMS reading only runs in the Android app, so on the web you add expenses by hand.

# 3. Start the Convex backend (in one terminal)
### Android

The Android build is a debug APK. It is signed for sideloading, not for the Play Store. Download it from the release, allow installs from your browser or file manager when Android asks, and open it.

Khata asks for permission to read and receive SMS. Without that permission, Android doesn't deliver texts to Khata, and SMS logging stops. With it, the background receiver posts every incoming text to your Khata backend. The backend keeps only bank and UPI messages and drops the rest.

## Run your own copy

You need Bun, a Convex account and a Google OAuth web client.

```sh
bun install
cp apps/web/.env.example apps/web/.env.local
bunx convex dev
```

`bunx convex dev` asks you to log in and pick a project the first time. Leave it running, then start the web app in a second terminal:

# 4. Start the web app (in another terminal)
```sh
bun run web:dev
```

Open the printed local URL. The app boots → Google Sign-In → connects to Convex. In
Chrome you can **Install app** to run it as a PWA.
Open the local URL Vite prints. Set `VITE_CONVEX_URL` in `apps/web/.env.local` to your deployment URL. Without it, the app connects to the author's development deployment.

> Browser-exposed env vars are prefixed `VITE_`. SMS reading is gated behind native
> platforms — on the web you log expenses manually.
### Configuration

---
Web app, in `apps/web/.env.local`:

## ☁️ Backend & deploy
| Variable | Purpose |
| --- | --- |
| `VITE_GOOGLE_CLIENT_ID` | Google OAuth web client ID used for sign-in. |
| `VITE_CONVEX_URL` | Convex deployment the build talks to. Production builds log an error when it is missing. |
| `VITE_CONVEX_SITE_URL` | Optional. The `.convex.site` origin. Derived from `VITE_CONVEX_URL` when unset. |
| `VITE_APP_URL` | Public origin for trip invite links and QR codes. Defaults to the current origin. |

Convex functions, schema, and crons live in `convex/`. Schema changes and scheduled
jobs register automatically on deploy.
Convex deployment environment variables. Set them with `bunx convex env set NAME value`, or in the Convex dashboard under Settings, then Environment Variables.

```bash
bunx convex dev # local/dev deployment with live reload + codegen
bunx convex deploy # push schema, functions, and crons to your deployment
| Variable | Purpose |
| --- | --- |
| `GOOGLE_OAUTH_CLIENT_ID` | Google OAuth client ID for sign-in. Required. |
| `GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth client secret. Required. |
| `SITE_URL` | Origin where the web app runs. Added to Better Auth's trusted origins. Defaults to `http://localhost:5173`. |
| `FIREBASE_SERVICE_ACCOUNT` | Firebase service account JSON. Push notifications stay off without it. |

```sh
bunx convex env set GOOGLE_OAUTH_CLIENT_ID your-client-id.apps.googleusercontent.com
bunx convex env set GOOGLE_OAUTH_CLIENT_SECRET your-client-secret
```

Releases for the web PWA are automated via `release-please`
(`.github/workflows/release-please.yml`); version source is `apps/web/package.json`.
In the Google OAuth client, add `https://<your-deployment>.convex.site/api/auth/callback/google` as an authorized redirect URI.

---
### Scripts

## 🛠️ Scripts
| Script | What it does |
| --- | --- |
| `bun run web:dev` | Starts the Vite dev server. |
| `bun run web:build` | Typechecks, then builds the production PWA. |
| `bun run web:preview` | Serves the production build locally. |
| `bun run web:typecheck` | Runs `tsc --noEmit` on the web app. |
| `bun run test` | Runs the Vitest suites once, for the Convex backend and the web app. |
| `bun run test:watch` | Runs Vitest in watch mode. |

Run from the repo root:
### Android build

| Script | Description |
|---|---|
| `bun run web:dev` | Start the web PWA dev server |
| `bun run web:build` | Production build of the web PWA |
| `bun run web:preview` | Preview the production build |
| `bun run web:typecheck` | Type-check the web app (`tsc --noEmit`) |
| `bun run test` | Run the test suite once (Vitest) |
| `bun run test:watch` | Run tests in watch mode |
Java 21 and the Android SDK are required. Set `VITE_GOOGLE_CLIENT_ID`, `VITE_CONVEX_URL` and `VITE_APP_URL` in `apps/web/.env.local` first. Then run:

---
```sh
bun run web:build
cd apps/web
bunx cap sync android
cd android
./gradlew assembleDebug
```

## 🧪 Testing
The APK lands at `apps/web/android/app/build/outputs/apk/debug/app-debug.apk`. Push notifications need your own `google-services.json` from Firebase at `apps/web/android/app/google-services.json`. The file is gitignored. Without it, the build still succeeds, and push notifications don't work.

```bash
bun run test # 33 tests across the Convex backend (Vitest + convex-test)
bun run web:typecheck
```
### Backend deploys

The backend lives in `convex/`. Code there runs only after it is deployed, so a frontend that calls newer functions than the deployment has will fail. Merges to `main` that touch `convex/` deploy to production through `.github/workflows/convex-deploy.yml`, which needs a `CONVEX_DEPLOY_KEY` repository secret.

The web build is a static site. `apps/web/vercel.json` sets the build command, the output directory and a single-page rewrite for Vercel.

## How it works

The SMS parser is one file, `convex/smsParser.ts`, and two code paths use it. The Convex route parses texts from the Android receiver. The web app imports the same file for its foreground poller, so both paths agree on what counts as a transaction. Money stays in integer paise from parse to storage, so sums never drift from floating-point rounding, and the backend rejects any amount above ₹1 crore.

Recurring-bill detection is a Convex query over the last 125 days of debits. Reminders and nudges run as daily cron jobs in `convex/crons.ts`, timed to IST.

## Repository layout

| Path | What it is |
| --- | --- |
| `apps/web/` | Vite and React PWA. The primary target, and the source of the Android app. |
| `convex/` | Convex backend: schema, queries, mutations, crons and the SMS ingest route. |
| `apps/mobile/` | Expo app. Abandoned and kept for reference. |
| `docs/` | Product notes and the PRD. |

## Documentation

- [Udhaar contacts and fixes PRD](docs/prd/udhaar-contacts-and-fixes.md)
- [Milestone plan](plan.md)
- [Web app changelog](apps/web/CHANGELOG.md)

Convex modules are tested with [`convex-test`](https://docs.convex.dev/testing/convex-test),
which runs queries/mutations against an in-memory deployment.
## Contributing

---
Run the checks CI runs before you open a pull request: `bun run web:typecheck`, `bun run web:build` and `bun run test`. Use Conventional Commits. release-please reads them to cut releases and write the changelog.

## 📄 License
## License

Released under the [MIT License](LICENSE) © 2026 Anuraj Jit Saikia.
Khata is released under the [MIT License](LICENSE).
Loading