Skip to content

SourasishBasu/ledgerly

Repository files navigation

banner

Ledgerly

An open source, self hostable expense tracking platform built with NextJS, Python
and AWS for the Lambda functions and S3 object storage.
Manage and gain insights from your expenses.

Features · Overview · AWS Setup · Backend Setup · Usage · Monitoring · Authors

Features

  • Website

    • NextJS App Router
    • Amazon Web Services for backend functionality with EC2
    • Support for S3 File Storage, and Lambda Container image based Functions
    • Edge runtime-ready
  • AWS Infrastructure

  • External

    • Prometheus, Grafana and GoAccess for extensive observability and monitoring of resources.
    • Gemini API for image to text extraction using Vision Model within free tier limits.
    • Github Actions CI pipelines to build, test and push application images from Github to various registries.
    • Traefik acts as a dynamic reverse proxy and automatically manages SSL/TLS certificates

Tech Stack

NextJs Python Uvicorn EC2 Docker ECR S3 Lambda Gemini GitHub Actions Grafana Traefik Ansible Prometheus Minio

Overview

AWS Architecture

  • The backend consists of 3 main services being the Python based REST API developed using FastAPI for serving requests, performing CRUD operations, a RDS Postgres database for data storage and retrieval and a S3 Bucket for image storage and hosting.
  • The other 5 services consist of Traefik as reverse proxy, utilized for automatic SSL provision, log creation and Prometheus, Grafana for resource usage collection and visualization using custom log exporters.
  • All of these services are run using Docker containers to ensure availability and performance.

Project Structure

.
├── AWS-setup.md
├── README.md
├── assets
├── deployment
│   ├── ansible
│   │   ├── inventory
│   │   ├── playbook.yml
│   │   └── roles
│   │       ├── common
│   │       │   └── tasks
│   │       │       └── main.yml
│   │       ├── docker
│   │       │   └── tasks
│   │       │       └── main.yml
│   │       ├── files
│   │       │   └── tasks
│   │       │       └── main.yml
│   │       └── tools
│   │           └── tasks
│   │               └── main.yml
│   ├── docker-compose.cloud.yml
│   ├── docker-compose.local.yml
│   ├── grafana
│   │   └── datasources.yml
│   ├── ledgerly.sql
│   └── prometheus
│       └── prometheus.yml
├───frontend
│   └─── ledgerly
│        ├─── app
│        │    └─── dashboard
│        ├─── bun.lock 
│        ├─── components
│        │    └─── ui
│        ├─── components.json
│        ├─── eslint.config.mjs
│        ├─── hooks
│        ├─── next.env.d.ts
│        ├─── next.config.ts
│        ├─── package.json
│        ├─── postcss.config.mjs
│        └─── tsconfig.json
└── services
    ├── backend
    │   ├── Dockerfile
    │   ├── app
    │   │   ├── __init__.py
    │   │   ├── app.py
    │   │   ├── core
    │   │   │   ├── __init__.py
    │   │   │   ├── config.py
    │   │   │   ├── db.py
    │   │   │   └── utils.py
    │   │   ├── db
    │   │   │   ├── __init__.py
    │   │   │   └── models.py
    │   │   ├── main.py
    │   │   └── routers
    │   │       ├── __init__.py
    │   │       ├── auth.py
    │   │       ├── deps.py
    │   │       └── receipts.py
    │   ├── pyproject.toml
    │   └── uv.lock
    └── receipt-ocr
        ├── Dockerfile
        └── app.py

Primary Services:

  • frontend/ledgerly: This subdirectory contains the frontend for the Ledgerly application dashboard.
  • services/backend: This subdirectory consists of the primary backend API for the entire application facilitating user registration, login, image upload and CRUD operations with the database.
  • services/receipt-ocr: This subdirectory consists of the helper application which extracts relevant data using an LLM from user submitted receipt images and adds these records into the database.
  • deployment/: This folder consists of all configurations required for the deploying the services and monitoring systems.

AWS Setup

Note

The default architecture is based on AWS services, however all of the services and tooling can be setup within any other cloud platform of choice or self hosted locally as well if required. Please refer to AWS Setup for setup instructions in the AWS cloud.

Local Setup

  1. Clone the repository locally. Add the environment variables as per the .env.example into the .env file within the deployment directory.

    git clone https://github.com/sourasishbasu/ledgerly.git
    cd ledgerly/deployment
    touch .env
  2. Install Docker. Run the containers with Docker Compose.

    docker compose up -f docker-compose.local.yml --build --pull missing -d
    
  3. Install the Minio Client and add it to PATH.

    • Run the following commands to setup a local S3 compatible object storage bucket named images.

      mc alias set local http://localhost:9000 minio minio123
      mc mb local/images
    • Configure a Webhook to listen for s3:ObjectCreated:PUT events in the bucket and automatically send event notifications to OCR service worker.

      mc admin config set local notify_webhook:trigger endpoint="http://worker:8000/event" && mc admin config set local notify_webhook:trigger format=json
      mc admin service restart local
      mc event add local/images arn:minio:sqs::trigger:webhook --event put --suffix .jpg
      mc event add local/images arn:minio:sqs::trigger:webhook --event put --suffix .jpeg
      mc event add local/images arn:minio:sqs::trigger:webhook --event put --suffix .png
    • To list images in Minio, run the following command.

      mc ls local/images
  4. Copy the contents of deployment/ledgerly.sql into the SQL Query Editor within any database tool after connecting to the postgres database container.

  5. Install Node v22 and Bun. Run the development server for the frontend.

    cd ../frontend/ledgerly/frontend
    bun dev
    

Expected Result

$ docker compose ps
NAME       IMAGE                        COMMAND                  SERVICE    CREATED          STATUS                    PORTS
api        ghcr.io/sourasishbasu/expense-tracker-api:latest   "fastapi run app/mai…"   api        48 minutes ago   Up 48 minutes (healthy)   0.0.0.0:5000->5000/tcp
minio      minio/minio                  "/usr/bin/docker-ent…"   minio      2 hours ago      Up 2 hours                0.0.0.0:9000-9001->9000-9001/tcp
postgres   postgres:latest              "docker-entrypoint.s…"   postgres   2 hours ago      Up 2 hours (healthy)      0.0.0.0:5432->5432/tcp
worker     ghcr.io/sourasishbasu/receipt-ocr:latest           "fastapi run app.py"     worker     48 minutes ago   Up 48 minutes (healthy)   0.0.0.0:8000->8000/tcp

Usage

Note

Detailed API docs along with examples and template data can be found at Scalar Docs.

Routes

Backend API: http://localhost:5000

Web Dashboard: http://localhost:3000

Minio Dashboard: http://localhost:9001

Demo

demo.mp4

Ledgerly Demo

Screenshots

Landing Page

Landing Page


Dashboard

Dashboard

Authors

This project was made for Project Wing 2025 by MLSAKIIT.

Version

Version Date Comments
1.0 May 21st, 2025 Revised release