Ledger

Actions, revenue, loyalty, and reports - one store console.

Comment

Username: downtown Password: demo123

Inspiration

Indian kiranas and small stores sit on years of invoice data - CSV dumps, PDFs, scanned bills - but almost none of it turns into decisions. Dashboards show charts; owners still guess what to reorder before Diwali, which SKUs to bundle, or which VIP customers are going quiet. We wanted something that feels like a ledger book for actions, not another analytics wall: ranked, quantified next steps from the bills they already have, tuned for Indian retail (festival calendars, phone loyalty, POS push) - without wrapping an LLM around every recommendation.

What it does

Ledger is a store app that turns invoice history into a daily Action Center.

  1. Ingest - CSV/JSON POS exports, text PDFs, or OCR’d scans → one normalized database (plus live ![POST /api/v1/invoices] with an API key).
  2. Understand - ML over that data: demand forecast, basket bundles, price elasticity, ABC inventory signals, anomalies, RFM/loyalty segments, festival stock-up / offer prep.
  3. Act - A deterministic insight engine scores actions (impact × confidence × urgency × weight) into plain Indian-English recommendations: reorder, clear dead stock, bundle SKUs, win back dormant buyers, prep for Diwali, etc.
  4. Learn - Store owners mark actions useful / not useful; rule weights adjust over time. Monthly reports include MoM deltas and forecast MAPE. Pilot tools measure before/after outcomes and backtest threshold tuning. The UI covers Action Center, Revenue (D/W/M), Intelligence (ML tables), Loyalty, Reports, and Admin (subscription, POS key, monitoring, pilot).

How we built it

Four phases on one shared SQLAlchemy DB (SQLite locally, Postgres-ready):

Piece Stack / role ![invoice-pipeline/] Adapters (CSV/JSON/PDF/OCR), cleaning, dedup, live POS ingest, loyalty, festival seed, subscriptions ![ml-models/] Forecasting, basket, elasticity, inventory, customers, festivals, anomalies, nightly refresh ![insight-engine/] YAML rules → scored/deduped insights; feedback learning; pilot backtest/tune - no Anthropic/OpenAI ![dashboard/] FastAPI APIs + single-file “Ledger” frontend (vanilla JS + Chart.js) Report generate runs ML → insight engine → snapshot. Nightly jobs refresh by plan; monitoring watches MAPE drift and ingest error rates.

Challenges we ran into

  • Messy real invoices - Layouts and field names vary; PDF/OCR are heuristic. We isolated failures per file/invoice, logged validation errors, and used configurable field mappings instead of crashing batches.
  • Honest ML on thin data - On synthetic test data, day-level forecast MAPE was weak (~74%); basket/elasticity signals were noisy because the fixtures had no real affinity. We moved forecast to weekly grain, tied confidence to backtest MAPE, and documented limits instead of hiding them.
  • Actions vs charts - Ranking without an LLM meant careful scoring, product-level conflict rules (e.g. reorder vs clear dead stock), and templates that still read as store advice.
  • Proving value - Correlation isn’t causation. Pilot outcomes and backtests give directional evidence; we pair them with Action Center feedback rather than claiming magic ROI.

Accomplishments that we're proud of

  • End-to-end path: invoice in → ranked action out, including live POS ingest and OCR.
  • Deterministic, auditable recommendations (same DB + rules → same list) with a feedback loop - no black-box chat layer.
  • India-first product details: festival calendar, phone loyalty with festival multipliers, Indian-English action copy, kirana-oriented pilot defaults.
  • A full store surface (auth, Action Center, revenue, ML, loyalty, reports, admin/monitoring/pilot) without a heavy frontend build.
  • Automation : nightly ML refresh, health checks, and job/alert visibility for a pilot store.

What we learned

  • Retail ML is only as good as purchase affinity and volume in the data - synthetic noise doesn’t teach real bundles or elasticity.
  • Store owners need one prioritized list, not ten model tables; scoring and conflict resolution matter as much as the models.
  • Confidence and MAPE as first-class signals beat “the model ran successfully.”
  • Keeping insights deterministic makes feedback, tuning, and pilot measurement tractable.
  • Ingestion reliability (idempotency, per-invoice transactions, error logs) is the foundation everything else sits on.

What's next for Ledger

  • Pilot on real multi-month POS history for one or more stores; retune rules.yaml with Action Center feedback and pilot backtests.
  • Harden PDF/OCR adapters against actual bill layouts from partner stores.
  • Deeper customer modules where phone/customer_id linkage is solid (churn, offers already scaffolded).
  • Wire forecast confidence more tightly into inventory/reorder urgency.
  • Optional multi-store benchmarking for chains; subscription/plan polish for production deploy.
  • Keep the no-LLM core; only add generative copy later if owners want it - never as the source of truth for actions.
Share this project:

Updates