Expense Flow

A RESTful API for tracking and managing personal expenses.

This project also acts as a submission for Expense Tracker API project.

🛠️ Features

• 🔒 User Authentication: Secure authentication using JWT and bcrypt
• 💸 Expense Management: Create, update, or delete expenses
• 🏷️ Category Management: Organize expenses with categories (CRUD operations)
• 🔍 Data Retrieval: Fetch specific records by ID or list all transactions
• 🔎 Advanced Filtering: Filter expenses and categories by date, amount, and more
• 📊 Sorting & Pagination: Sort and paginate through expenses and categories efficiently
• 📈 Analytics: Get category-wise expenditure insights
• ⚡ Efficient Querying: Built with SQLAlchemy ORM for clean data access
• ✅ Type Safety & Validation: Static type checking with Pyright and runtime data validation using Pydantic
• 🗄️ Database & Migrations: PostgreSQL support with Alembic for schema versioning
• 🐳 Docker Support: Easy deployment with Docker and docker-compose
• 🧪 Testing: Included pre-configured HTTP requests
• 📖 Interactive API Docs: Auto-generated documentation via Swagger UI

💻 Tech Stack

• Language: Python
• Web Framework: FastAPI
• Database: PostgreSQL
• ORM: SQLAlchemy 2.0
• Migrations: Alembic
• Validation: Pydantic v2
• Type Checking: Pyright

📘 API Documentation

Authentication

All protected endpoints require a JWT token.

Authorization: Bearer <JWT_TOKEN>

---

Endpoints Overview

Authentication

Method	Endpoint	Description
POST	/signup	Create a new user
POST	/login	Authenticate user

Expenses

Method	Endpoint	Description
POST	/expenses	Create an expense
GET	/expenses	List all expenses (with filtering, sorting, pagination)
GET	/expenses/{id}	Fetch expense by ID
PATCH	/expenses/{id}	Update expense
DELETE	/expenses/{id}	Delete expense

Categories

Method	Endpoint	Description
POST	/categories	Create a new category
GET	/categories	List all categories (with filtering, sorting, pagination)
GET	/categories/{id}	Fetch category by ID
PATCH	/categories/{id}	Update category
DELETE	/categories/{id}	Delete category

Analytics

Method	Endpoint	Description
GET	/analytics	Get category-wise expenditure data

---

Example: Create Expense

curl -X POST http://localhost:8000/expenses \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Full Reference

Interactive OpenAPI documentation is available at: http://localhost:8000/docs

✅ 🚀 Setup & Installation

Option 1: Docker Setup (Recommended)

The easiest way to get started is using Docker and docker-compose.

Prerequisites

• Docker and Docker Compose installed

Steps

1. Configure environment variables

Create a .env.docker file in the project root:

cp .env.example .env.docker

Edit .env.docker with the following configuration:

DB_HOST=db
DB_PORT=5432
DB_USER=user
DB_PASSWORD=password
DB_NAME=mydatabase

JWT_ALGORITHM=HS256
JWT_EXPIRATION_TIME=3600
JWT_SECRET_TOKEN=<your-generated-secret>

Tip

Generate a secure JWT secret with: openssl rand -base64 32

2. Start the application

docker-compose up -d

This will:

• Start a PostgreSQL database container
• Run database migrations automatically
• Start the FastAPI application on port 8000

3. (Optional) Load seed data

To populate the database with sample data:

docker-compose exec db psql -U user -d mydatabase -f /app/seed.sql

4. Access the API

The API should now be running at http://localhost:8000

Visit the interactive documentation at: http://localhost:8000/docs

---

Option 2: Manual Setup

For local development without Docker:

Prerequisites

• Python 3.10+ with pip
• PostgreSQL 14+ running locally
• openssl (for generating JWT secrets)

---

1. Create the database and user

Connect to PostgreSQL and run:

CREATE USER expense_user WITH PASSWORD 'expense';
CREATE DATABASE expense_db OWNER expense_user;

---

2. Generate a JWT secret

Generate a secure JWT secret key:

openssl rand -base64 32

Copy the generated value — it will be used in the next step.

---

3. Configure environment variables

Copy the example environment file and update its values:

cp .env.example .env.local

Edit .env.local with the following configuration:

DB_HOST=localhost
DB_PORT=5432
DB_USER=expense_user
DB_PASSWORD=expense
DB_NAME=expense_db

JWT_ALGORITHM=HS256
JWT_EXPIRATION_TIME=3600
JWT_SECRET_TOKEN=<your-generated-secret>

---

4. Create a virtual environment and install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

---

5. Run database migrations

Apply the database schema using Alembic:

alembic upgrade head

Warning

If this step fails, ensure PostgreSQL is running and the database credentials in .env are correct.

---

6. Run the application

Start the FastAPI server:

fastapi run

The API should now be running locally.

---

7. Access the API and OpenAPI documentation

Once the server is running, you can interact with the API using either:

• Preconfigured HTTP requests (in the http/ directory), or
• FastAPI’s built-in OpenAPI documentation

Open your browser and visit Swagger UI on:

http://localhost:8000/docs

License

MIT