Budget API

FastAPI backend for the Budget finance tracker. Provides REST endpoints for expenses and uses PostgreSQL with Alembic migrations.

Requirements

• Python 3.11+
• PostgreSQL (e.g. run with Docker: docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=budget postgres:16)

Setup

1. Create a virtualenv and install dependencies:

   python -m venv venv
   source venv/bin/activate   # or `venv\Scripts\activate` on Windows
   pip install -r requirements.txt

2. Copy .env.example to .env and set DATABASE_URL (and optionally PORT).

3. Run migrations:

   alembic upgrade head

4. Start the API:

   uvicorn app.main:app --reload --port 8000

• API docs: http://localhost:8000/docs
• OpenAPI JSON: http://localhost:8000/openapi.json

Running with Docker

From the repository root (parent of budget-api), use the project’s docker-compose.yml to run PostgreSQL and the API:

docker compose up --build

The API will be at http://localhost:8000; migrations run automatically on startup. To run the API image only (e.g. with your own Postgres), build and run from budget-api:

docker build -t budget-api .
docker run --rm -p 8000:8000 -e DATABASE_URL=postgresql://user:pass@host:5432/budget budget-api

Environment variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://postgres:postgres@localhost:5432/budget
PORT	Server port (for reference)	8000

API (MVP)

• GET /api/expenses – List expenses (query: limit, offset)
• POST /api/expenses – Create expense (body: amount, currency?, description?, category?)

Future work

• Auth (JWT or sessions)
• CRUD for categories, budgets, reports
• Pagination and filtering on GET /api/expenses