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
-
Website
- NextJS App Router
- Amazon Web Services for backend functionality with
EC2
- Support for
S3
File Storage, andLambda
Container image based Functions - Edge runtime-ready
-
AWS Infrastructure
- Amazon S3/Minio Utilized for image storage.
- AWS Lambda for processing JSON and filtering required data
- Amazon EC2 for provisioning VM instances
- Amazon ECR for privately hosting container images
-
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
- 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.
.
├── 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.
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.
-
Clone the repository locally. Add the environment variables as per the
.env.example
into the.env
file within thedeployment
directory.git clone https://github.com/sourasishbasu/ledgerly.git cd ledgerly/deployment touch .env
-
Install Docker. Run the containers with
Docker Compose
.docker compose up -f docker-compose.local.yml --build --pull missing -d
-
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
-
-
Copy the contents of
deployment/ledgerly.sql
into the SQL Query Editor within any database tool after connecting to the postgres database container. -
Install Node v22 and Bun. Run the development server for the frontend.
cd ../frontend/ledgerly/frontend bun dev
$ 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
Note
Detailed API docs along with examples and template data can be found at Scalar Docs.
Backend API: http://localhost:5000
Web Dashboard: http://localhost:3000
Minio Dashboard: http://localhost:9001
demo.mp4
Ledgerly Demo
Landing Page
Dashboard
This project was made for Project Wing 2025 by MLSAKIIT.
- Sourasish Basu (@SourasishBasu) - MLSA KIIT
Version | Date | Comments |
---|---|---|
1.0 | May 21st, 2025 | Revised release |