Skip to content

🧭 Overview

Khata is an internal expenses and cashflow service. It manages users, entities, accounts, tags, expenses, uploads, and fetch requests on MongoDB, ingesting bank statements from several file formats and turning them into normalized expense records enriched with payee entities and tags.

🎯 What It Does

  • Statement ingestion — a fetch request declares a source (PDF file, email, CSV/XLSX upload, or llama-cloud document); a background worker executes the extraction, enrichment, and persistence pipeline.
  • Normalized expenses — expenses carry amount, balance, a kind (debit/credit/transfer), mcc, memo, date, an optional tag, and an optional entity (the payee).
  • Enrichment — rule registries map raw payee/memo patterns to canonical entities and tags; pipelines run depth-first through dagpipe.
  • Tag & entity reconciliation — entities, tags, and accounts are created on demand and linked by name-based resolution.
  • Progress visibility — the pipeline emits ProgressEvents over SSE; ambiguity pauses are stored for later resolution.

🧩 Where It Lives

Khata is the read/write service in the wider stack: other services query expenses and tags downstream, while Khata itself pulls documents and external OCR. The domain knows only its own models and ports; all adapters (Mongo, Redis, HTTP, OpenAI-compatible LLM, email, LlamaParse) live in infra.

📌 Notable Trade-offs

Decision Rationale
OpenAPI-first routing Single source of truth for the HTTP surface; handlers are thin
no plain __init__ factories Entrypoints wire the object graph explicitly in init.py
In-memory LRU + Redis Hot entity/account lookups avoid Mongo round-trips during enrichment
x-fk cross-collection population Repos resolve referenced ids with explicit filters instead of Mongo joins
YAML pattern registries Rule changes require no code deploy

🗺 Roadmap Notes

  • The ambiguity resolver currently returns None in worker._maybe_create_resolver — LLM-assisted resolution is stubbed behind LLM_API_KEY.
  • infra/llm (OpenAI / OpenRouter pools, prompt policies) is the substrate for future resolver work.
  • The XLSX/CSV tabular families cover Axis and ICICI layouts first.

Architecture · Components · Running The Service · Development