Expense Flow

A RESTful API for tracking and managing personal expenses.

🛠️ Features

• 🔒 User Authentication: Secure authentication using JWT and bcrypt
• 💸 Expense Management: Create, update, or delete expenses
• 🔍 Data Retrieval: Fetch specific records by ID or list all transactions
• ⚡ 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.
• 🧪 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

Method	Endpoint	Description
POST	/signup	Create a new user
POST	/login	Authenticate user
POST	/expenses	Create an expense
GET	/expenses	List all expenses
GET	/expenses/{id}	Fetch expense by ID
PATCH	/expenses/{id}	Update expense
DELETE	/expenses/{id}	Delete expense

---

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

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

Edit .env 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 test_main.http), or
• FastAPI’s built-in OpenAPI documentation

Open your browser and visit Swagger UI on:

http://localhost:8000/docs

License

MIT