Expense Tracker API

Initial expense tracker with a small browser frontend and FastAPI backend.

What is included

• FastAPI app with a browser UI, health, and CRUD endpoints
• SQLAlchemy models and session management
• PostgreSQL-ready database configuration
• pytest test coverage for the API slice
• Docker and GitHub Actions setup

Local development

Python 3.11 or newer is required. The application uses SQLite by default, so a separate database server is not required for local development.

Windows PowerShell

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
uvicorn app.main:app --reload

POSIX shells

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
cp .env.example .env
uvicorn app.main:app --reload

The .env copy is optional because the checked-in example contains the application defaults. Open http://127.0.0.1:8000 for the frontend or http://127.0.0.1:8000/docs for the API docs.

Configuration

Settings are read from environment variables or a local .env file. The application uses:

Variable	Default	Purpose
APP_NAME	Expense Tracker API	Application name shown in generated API metadata and metrics labels
DATABASE_URL	sqlite:///./expense_tracker.db	SQLAlchemy database connection URL

Do not commit .env files containing credentials. Docker Compose supplies its own PostgreSQL connection URL to the API container.

Database initialization

The application creates missing tables automatically when FastAPI starts. With the default configuration, it creates expense_tracker.db in the project root. Docker Compose performs the same initialization against its PostgreSQL service. There is currently no separate migration or manual initialization command.

Import sample data

Start the application, open http://127.0.0.1:8000, and use Import expenses to upload tests/fixtures/sample_expenses.csv. To generate the equivalent Excel fixture, run:

python scripts/create_sample_xlsx.py

Then upload tests/fixtures/sample_expenses.xlsx through the same form.

Tests

pytest

Linting and formatting

ruff check .
ruff format --check .

Apply Ruff formatting with:

ruff format .

Docker

docker compose up --build

Follow API logs or stop the stack with:

docker compose logs -f api
docker compose down

Prometheus and Grafana

This project exposes Prometheus metrics at http://localhost:8000/metrics.

When you run docker compose up --build, the stack also starts:

• Prometheus at http://localhost:9090
• Grafana at http://localhost:3000

Grafana is preconfigured to use Prometheus as its default data source.

To confirm that Prometheus can reach the API, open http://localhost:9090/targets and check that the expense-api target is UP.

The stack provisions an Expense API Overview dashboard under the Expense Tracker folder. Open Grafana at http://localhost:3000, log in, and select Dashboards > Expense Tracker > Expense API Overview. The dashboard shows API availability, request and error rates, response status, and p95 latency by normalized route.

Login for Grafana:

• Username: admin
• Password: admin

These credentials are intended for local development only. To generate dashboard traffic, use the browser UI or make requests to endpoints such as http://localhost:8000/health and http://localhost:8000/expenses, then wait for one or two 15-second scrape intervals.

To inspect metrics directly, query http_requests_total or http_request_latency_seconds_bucket in Prometheus.