Skip to content

🧩 Khata App — Expenses & Cashflow Service

khata-app is the OpenAPI-first backend for tracking expenses and cashflow. It ingests bank statements (PDF, CSV, XLSX, email, LlamaParse), runs rule-driven enrichment to identify payees and tags, and exposes everything through a spec-driven FastAPI service on MongoDB.

Doc model: this wiki is written for humans — how-to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine-readable bundle under docs/mcp/.

🚀 Key Features

  • 🗂 OpenAPI-first routing — the openapi.yaml spec drives every route via opendapi-first's OpenAPIFirstApp; handlers are thin and matched by operationId
  • 🏛 Strict three-layer architecture — interface → domain → infra, one-way data flow, zero backflow
  • 📥 Multi-source extraction — PDF heuristics, CSV/XLSX tabular parsing, email ingestion, and llama-cloud OCR via the hexa pipeline families
  • 🧠 Rule-driven enrichment — entity resolution and tag assignment from YAML pattern registries, wired through dagpipe
  • 🔄 Fetch request pipeline — poll → extract → enrich → persist, coordurally by the worker with SSE progress events and ambiguity pauses
  • 🗃 MongoDB via mongo-ops — generic repos with in-memory caching and foreign-key population (x-fk)
  • ⚡ Redis-backed caching — HTTP cache and repo reads with TTL control

📦 Installation

1
2
3
4
5
# Local development
pip install -e ".[dev]"

# App dependencies (from pyproject.toml)
pip install -e .

Requires Python ≥ 3.9 (development venv runs 3.13) and a running MongoDB + optional Redis.

📁 Documentation Structure

Section Description
Overview What Khata is and how it fits the stack
Architecture Layers, data flow, and lifecycle rules
Components The domain, interfaces, and infra building blocks
Domain Resources Users, entities, accounts, tags, expenses, uploads
Enrichment Entity resolution and tag assignment pipelines
Extraction Pipelines PDF/CSV/XLSX/email/llama extraction families
Fetch Request Workflow Worker, SSE, CLI, orchestration
Reports & Caching Reports service, HTTP cache, Redis
Running The Service Boot, config, seed scripts
Development Environment, testing, docstrings, docs builds
  • Source repo: git@git.aetoskia.com:apps/khata-app.git
  • Library reference (lib): built into site/lib/ from GSDFC docstrings
  • MCP bundles: docs/mcp/{domain,infra,interfaces,pipelines}/ — machine-readable API reference
  • API reference (OpenAPI): built into site/api/ from openapi.yaml

© Aetoskia Internal — khata-app 0.1.0