LedgerMind

An AI-powered personal finance ledger that intelligently categorizes transactions, provides natural language insights, and gives you full control over your money — all running locally with complete privacy.

🚀 Features

• AI Transaction Categorization – Local Ollama LLM (default: lightweight llama3.2:3b) automatically categorizes transactions.
• Natural Language Insights – Ask questions in plain English directly in the dashboard.
• Interactive Dashboard – Streamlit UI with spending charts, transaction management, and CSV import.
• Basic Authentication – Protected API and app access (default: admin / supersecretpassword).
• Full Privacy – No data leaves your machine.
• CSV Import – Bulk upload bank statements.
• Adminer GUI – Easy database browsing at http://localhost:8080.

🏗️ Architecture Overview

LedgerMind is designed as a modular, containerized system, with clear separation of concerns across UI, API, AI, and data layers.

High-Level Architecture Diagram

graph TB
    subgraph "LedgerMind Application"
        subgraph "User Interface Layer"
            Frontend[Frontend Container<br/>Streamlit App<br/>Port: 8501]
        end

        subgraph "Application Layer"
            API[API Container<br/>FastAPI Service<br/>Port: 8000]
        end

        subgraph "AI/ML Layer"
            Ollama[Ollama Container<br/>LLM Service<br/>Port: 11434]
        end

        subgraph "Data Layer"
            DB[(PostgreSQL Database<br/>Port: 5432)]
            Adminer[Adminer<br/>DB Admin Interface<br/>Port: 8080]
        end

        subgraph "Persistent Storage"
            PGData[postgres_data volume]
            OllamaData[ollama_data volume]
        end
    end

    subgraph "External Access"
        User([User / Browser])
        DBAdmin([Database Admin])
    end

    User -->|HTTP :8501| Frontend
    DBAdmin -->|HTTP :8080| Adminer
    Frontend -->|REST API :8000| API
    API -->|SQL| DB
    API -->|LLM Requests :11434| Ollama
    Adminer -.->|Query| DB
    DB -->|Persist| PGData
    Ollama -->|Persist| OllamaData

Loading

🛠️ Tech Stack

• Backend: FastAPI + SQLAlchemy + Pydantic
• Frontend: Streamlit
• Database: PostgreSQL 15
• AI: Ollama (default model: llama3.2:3b for speed/privacy)
• Containerization: Docker + Docker Compose

📦 Quick Start

Prerequisites

• Docker & Docker Compose (v2+)
• uv (for package management)
• (Optional) NVIDIA GPU + drivers

1. Clone the repository

git clone https://github.com/KarthikUdyawar/ledgermind.git
cd ledgermind

2. Set up environment files

cp example.env .env.staging
cp frontend/example.env frontend/.env.staging

Default credentials (change in production!):

• API Auth: admin / supersecretpassword
• Default Ollama model: llama3.2:3b (lightweight & fast)

3. Launch the stack

chmod +x ./script/*
./script/setup.sh

The setup script:

• Builds & starts all containers
• Validates /health
• Seeds database categories
• Pulls Ollama model
• Fails fast on errors

Services:

Service	URL
Frontend	http://localhost:8501
API	http://localhost:8000
API Docs	http://localhost:8000/docs
Ollama API	http://localhost:11434
Adminer	http://localhost:8080

🗂️ Project Structure

ledgermind/
├── app/                      # Backend application (FastAPI)
│   ├── ai/                   # AI & LLM integration layer
│   │   ├── graph.py          # Defines AI execution flows / pipelines
│   │   ├── prompt.py         # Centralized prompt templates for categorization
│   │   └── schema.py         # Typed schemas for LLM input/output
│   ├── api/                  # API layer (HTTP interface)
│   │   ├── deps.py           # FastAPI dependencies (DB session, auth, context)
│   │   ├── exception_handlers.py  # Global API exception handling
│   │   ├── router.py         # Main router mounting all API routes
│   │   ├── routes/           # Feature-based route modules
│   │   │   ├── auth.py       # Authentication & authorization endpoints
│   │   │   ├── categories.py # Category CRUD endpoints
│   │   │   └── transactions.py # Transaction CRUD & CSV import endpoints
│   │   └── schemas/          # Pydantic request/response models
│   │       ├── auth.py       # Auth request/response schemas
│   │       ├── category.py   # Category API schemas
│   │       ├── common.py     # Shared schemas (pagination, base responses)
│   │       └── transaction.py# Transaction API schemas
│   ├── core/                 # Core infrastructure & configs
│   │   ├── config.py         # Environment variables & app settings
│   │   ├── context.py        # Request-scoped context (user info, trace IDs)
│   │   ├── errors.py         # Domain-level error definitions
│   │   ├── logging.py        # Centralized logging setup
│   │   └── security.py       # Security utilities (JWT, hashing)
│   ├── db/                   # Database utilities
│   │   ├── base.py           # Base declarative model for SQLAlchemy
│   │   └── session.py        # Database session management
│   ├── main.py               # FastAPI entrypoint
│   ├── middleware/           # Custom middleware
│   │   └── logging.py        # Request/response logging middleware
│   ├── models/               # Database models
│   │   ├── category.py       # Category table definition
│   │   └── transaction.py    # Transaction table definition
│   └── services/             # Business logic & service layer
│       └── categorizer.py    # Transaction categorization logic
├── docker/
│   └── Dockerfile            # Backend Dockerfile
├── docker-compose.yml        # Docker Compose orchestration file
├── example.env               # Example environment variables
├── frontend/                 # Streamlit frontend
│   ├── app.py                # Main Streamlit app
│   ├── config.py             # Frontend configuration
│   ├── Dockerfile            # Frontend Dockerfile
│   ├── example.env           # Frontend env example
│   └── requirements.txt      # Python dependencies
├── LICENSE                   # MIT License
├── logs/
│   └── ledgermind.log        # Central log file
├── main.py                   # Root entrypoint (optional)
├── pyproject.toml            # Project configuration for Python tooling
├── README.md                 # Project README
├── script/                   # Setup/teardown & utility scripts
│   ├── generate_mock_data.sh # Script to generate mock transactions
│   ├── seed_categories.sh    # Seed categories into PostgreSQL
│   ├── seed_ollama_models.sh# Seed Ollama models
│   ├── setup.sh              # Setup all services & health check
│   └── teardown.sh           # Tear down stack safely
├── upload/                   # Sample CSV files for testing
│   ├── sample_transactions.csv
│   └── test_transactions.csv
└── uv.lock                   # Dependency lock file

🛑 Teardown

./script/teardown.sh

Includes:

• Explicit warnings before stopping containers
• Optional volume deletion
• Optional image cleanup

⚙️ GPU Acceleration (Optional)

For faster AI with larger models:

1. Install NVIDIA Container Toolkit
2. Uncomment the deploy block under ollama in docker-compose.yml
3. Restart Ollama container

🤝 Contributing

Contributions welcome! Open issues or PRs for new features, better prompts, or UI improvements.

📄 License

MIT License — see LICENSE

---

Privacy-first, intelligent personal finance — fully local.

Made with ❤️ by Karthik Udyawar