Skip to content

Home

Jump to bottom
symonbaikov edited this page Apr 23, 2026 · 2 revisions

Lumio — Overview

Open-source financial data platform for importing, processing, and analyzing bank statements.

Documentation: symonbaikov.github.io/lumio/

What is Lumio?

Lumio turns unstructured financial documents (PDFs, CSVs, email receipts, scanned images) into clean, queryable data. It is self-hosted, open-source, and built for finance teams, accountants, and developers who need full control over their financial data pipeline without proprietary SaaS lock-in.

Core Capabilities

Capability Description
Multi-format Import PDF, CSV, XLSX, and image files. Native parsers for Kaspi Bank and Bereke Bank. Generic AI PDF parser for any other bank.
OCR Tesseract.js text extraction from scanned documents and photos.
Idempotent Uploads SHA-256 file hashing prevents duplicate imports.
Transaction Deduplication Fingerprint-based duplicate detection with confidence scoring, merge, and mark-as-duplicate workflows.
AI Auto-Categorization Gemini / OpenRouter-backed categorization with per-workspace learning rules.
Multi-Tenant Workspaces Unlimited workspaces with invitation flows and per-workspace data isolation.
Granular RBAC Roles: owner, admin, member, viewer. Per-user permission overrides.
Dashboard & Reports Cash flow, top categories, trends, custom report builder with CSV/XLSX export.
Audit Log Complete event trail with one-click rollback for supported operations.
Docker Ready One-command deployment with Docker Compose.

Tech Stack

Layer Technology
Backend NestJS (TypeScript), TypeORM, PostgreSQL, Redis
Frontend Next.js (TypeScript), MUI, TanStack Query, ECharts
AI / ML Google Gemini, OpenRouter, Tesseract.js
Realtime Socket.IO
Auth JWT (HttpOnly cookies), refresh token rotation
Infra Docker Compose, Railway

Architecture

Lumio follows Clean Architecture with strict layer separation:

  • Domain — business entities and repository interfaces (no framework dependencies)
  • Application — use cases and service logic, communicates via DTOs
  • Infrastructure — TypeORM repositories, external API clients, configuration
  • Interface — NestJS controllers, WebSocket gateways, input validation via class-validator

Quick Start

# Clone the repository
git clone https://github.com/symonbaikov/lumio.git
cd lumio

# Start everything in one command
make quick-dev

Services start at:

Key Standards

  • Security — HttpOnly JWT cookies, AES-256 encryption at rest, strict CORS, Helmet.js headers, rate limiting on sensitive endpoints.
  • Idempotency — All critical write operations use idempotency keys and SHA-256-based duplicate guards.
  • Financial Integrity — Immutable ledger records; corrections via reversal entries only; optimistic locking on balance updates.
  • Observability — Structured JSON logs, correlation IDs, Prometheus metrics, Grafana dashboards, /health and /ready endpoints.
  • Database — Migrations only (no direct schema edits), foreign key constraints, soft deletes (deletedAt).

Deployment

# Production (Docker Compose)
docker compose up -d --build

# Railway — push to main, Railway deploys automatically

See RAILWAY.md for step-by-step Railway deployment.

Documentation

Resource Link
Full Documentation symonbaikov.github.io/lumio/
Contributing Guide CONTRIBUTING.md
Security Policy SECURITY.md
Changelog CHANGELOG.md
Feature Plans docs/plans/
API Docs (Swagger) http://localhost:3001/api/docs (local)

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Run make lint and make test — both must pass
  4. Commit using Conventional Commits
  5. Open a Pull Request against main

License

MIT — see LICENSE.

Clone this wiki locally