ClearLedger

ClearLedger is a full-stack personal finance application for importing, managing, and analyzing transaction data. It combines a FastAPI and PostgreSQL backend with a React dashboard.

Current features

• Create, view, filter, paginate, and delete transactions from the dashboard
• Register, sign in, restore sessions, and log out through the React interface
• Protect financial data with Argon2 password hashing and JWT authentication
• Isolate transactions, imports, and analytics by user account
• Import CSV statements with row-level validation and duplicate detection
• Normalize common bank statement merchant names and fill missing categories
• Filter transactions by merchant, category, and date range
• View transaction totals, average spending, and category breakdowns
• Compare spending totals across months
• Set monthly category budgets and track spending progress
• Validate API requests and responses with Pydantic
• Manage the PostgreSQL schema with Alembic migrations
• Run isolated backend tests and frontend builds through GitHub Actions
• Use a responsive React and TypeScript interface on desktop and mobile

Tech stack

• React, TypeScript, and Vite
• Python 3.13
• FastAPI and Pydantic
• PostgreSQL
• SQLAlchemy 2.0
• Alembic
• pytest
• GitHub Actions

Project structure

backend/
├── main.py
├── database.py
├── models.py
├── processing.py
├── schemas.py
├── security.py
└── routers/
    ├── auth.py
    ├── transactions.py
    ├── budgets.py
    └── analytics.py
frontend/
├── src/
│   ├── components/
│   ├── api.ts
│   ├── App.tsx
│   └── types.ts
└── package.json
alembic/
tests/
sample_data/

Local setup

Backend

1. Clone the repository and enter the project directory.

   git clone https://github.com/eldhothomas1/ClearLedger.git
   cd ClearLedger

2. Create and activate a virtual environment.

   python -m venv venv
   .\venv\Scripts\Activate.ps1

3. Install the Python dependencies.

   python -m pip install -r requirements.txt

4. Copy .env.example to .env and enter your PostgreSQL password.

   Copy-Item .env.example .env

   Generate a JWT secret and save the result as JWT_SECRET_KEY in .env.

   python -c "import secrets; print(secrets.token_hex(32))"

5. Create a PostgreSQL database named clearledger and apply the migrations.

   python -m alembic upgrade head

6. Start the API.

   uvicorn backend.main:app --reload --port 8001

The API documentation is available at http://127.0.0.1:8001/docs.

Frontend

Open another PowerShell terminal from the project root.

cd frontend
npm install
npm run dev

Open the dashboard at http://127.0.0.1:5173.

CSV format

CSV files must contain date, merchant, and amount columns. The category column is optional. Dates use the YYYY-MM-DD format.

date,merchant,amount,category
2026-10-15,Trader Joe's,48.37,Groceries
2026-10-16,Spotify,11.99,Entertainment

Common statement descriptors for Amazon, Chipotle, Spotify, Trader Joe's, Whole Foods, and Uber are normalized during creation and import. A default category is added only when the category field is empty.

API overview

Method	Endpoint	Purpose
GET	/health	Check API availability
POST	/auth/register	Create an account
POST	/auth/login	Sign in and receive an access token
GET	/auth/me	Retrieve the signed-in user
POST	/transactions	Create a transaction
GET	/transactions	List and filter transactions
POST	/transactions/import	Import transactions from CSV
GET	/transactions/{id}	Retrieve one transaction
PATCH	/transactions/{id}	Update selected fields
DELETE	/transactions/{id}	Delete a transaction
GET	/analytics/summary	Get totals and category breakdowns
GET	/analytics/monthly	Get monthly spending totals
GET	/budgets	List monthly budgets with spending progress
PUT	/budgets	Create or update a category budget
DELETE	/budgets/{id}	Delete a budget

Tests

Run the backend tests from the project root.

python -m pytest

Run a production frontend build from the frontend directory.

npm run build

Roadmap

• Configurable categorization rules
• Containerized local environment and cloud deployment