Skip to content

About

A personal finance management REST API in Python. It targets a real market pain in Brazil: PIX made transactions faster and more fragmented, and most people have lost track of where their money goes; household debt remains high, and the market splits between manual spreadsheets and closed consumer apps.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SmartBudget API

A personal finance REST API for tracking transactions, categorising spending, and enforcing monthly budgets with threshold alerts.

Built with Python, FastAPI and PostgreSQL, using a layered architecture and documented architectural decisions.

Status: in development. Progress is tracked in docs/ROADMAP.md.


The problem

Instant payments changed how Brazilians spend money. In 2025, Pix moved R$ 35.36 trillion across 79.8 billion transactions — a 33.6% jump over 2024 — and now regularly clears more than 300 million transfers in a single day. Spending stopped being a handful of monthly card statements and became hundreds of small, scattered, instant transfers.

Household finances did not keep up. The CNC's Peic survey put the share of Brazilian families carrying debt at 80.4% in March 2026, the highest in the series since 2010, with 29.6% holding overdue debt.

The tooling splits into two unsatisfying halves: manual spreadsheets, which are accurate but abandoned within weeks, and closed consumer apps, which hold your data and expose no programmable interface.

SmartBudget API is the missing middle: an open, well-tested back-end that owns the hard part — categorisation, aggregation and budget rules — and leaves the interface open to whatever consumes it.

Features

Feature Sprint
☐ Users and JWT authentication S3
☐ Transaction tracking (income / expense) S2
☐ Categories and categorisation rules S2
☐ Monthly report with per-category aggregation S2
☐ Budgets with alerts at 80% and 100% of a category limit S3
☐ Savings goals stretch

Tech stack

Concern Choice
Language Python 3.11
Web framework FastAPI
Database PostgreSQL
ORM / migrations SQLAlchemy + Alembic
Auth JWT
Tests pytest
Lint / format ruff
Type checking mypy (strict)
Dependencies pip, with uv as the resolver
Containers Docker + docker-compose
CI GitHub Actions

Architecture

Four layers, one direction of dependency:

router  →  service  →  repository  →  PostgreSQL
(HTTP)     (rules)     (persistence)

Two rules keep the structure honest:

  • Business rules live only in the service layer. Not in routers, not in repositories.
  • Repositories are injected via Depends, never instantiated inside a service.

The reasoning, the alternatives that were rejected, and the conditions under which this should be reconsidered are recorded in ADR-001.

Project structure

app/
├── api/            routers — HTTP in, HTTP out
│   ├── health.py   liveness and readiness probes (unversioned, on purpose)
│   └── v1/         versioned domain routers
├── services/       business rules — the only place they may live
├── repositories/   database access — no rules
├── models/         SQLAlchemy models (database shape)
├── schemas/        Pydantic schemas (API contract shape)
├── core/           settings and cross-cutting concerns
└── main.py         application factory
docs/adr/           architecture decision records
tests/

Getting started

Requires Python 3.11+.

git clone https://github.com/GabrielBarros0602/SmartBudget_API.git
cd SmartBudget_API

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

pip install -r requirements-dev.txt
Copy-Item .env.example .env

docker compose up -d db
alembic upgrade head

uvicorn app.main:app --reload

Migrations are not applied when the API starts. Run alembic upgrade head yourself, once and after every pull that brings a new one, so a restart never changes the schema (ADR-004).

The API is then available at http://127.0.0.1:8000, with interactive docs at http://127.0.0.1:8000/docs.

# health check
curl http://127.0.0.1:8000/health

# tests and linting
pytest
ruff check .
ruff format .
mypy

Changing dependencies

Edit requirements.in or requirements-dev.in, never the .txt files, and regenerate the lockfiles with the commands in CONTRIBUTING.md. Installation stays on pip; uv is only the resolver, because development happens on Windows while the runtime is Linux.

Roadmap

Development is governed by docs/ROADMAP.md — a sprint checklist, written in Portuguese as a working instrument, where every architectural decision is an item that closes only once its ADR is committed.

Contributing conventions

Commit format, scopes, ADR references, branches and pull requests are in CONTRIBUTING.md.

Sources

License

MIT


SmartBudget API (Português)

Uma API REST de finanças pessoais para registrar transações, categorizar gastos e controlar orçamentos mensais com alertas de limite.

Construída com Python, FastAPI e PostgreSQL, em arquitetura em camadas e com decisões arquiteturais documentadas.

O problema

O pagamento instantâneo mudou a forma como o brasileiro gasta. Em 2025, o Pix movimentou R$ 35,36 trilhões em 79,8 bilhões de transações — alta de 33,6% sobre 2024 — e já ultrapassa 300 milhões de transferências em um único dia. O gasto deixou de ser algumas faturas mensais e virou centenas de transferências pequenas, instantâneas e dispersas.

O controle financeiro não acompanhou. A Peic/CNC registrou 80,4% das famílias brasileiras endividadas em março de 2026, o maior patamar da série histórica iniciada em 2010, com 29,6% com dívidas em atraso.

As ferramentas se dividem entre planilhas manuais — precisas, mas abandonadas em poucas semanas — e aplicativos fechados, que retêm os dados do usuário e não oferecem interface programável.

A SmartBudget API ocupa esse espaço: um back-end aberto e testado que resolve a parte difícil (categorização, agregação e regras de orçamento) e deixa a interface livre para quem for consumi-la.

Arquitetura

Quatro camadas, uma única direção de dependência:

router  →  service  →  repository  →  PostgreSQL
(HTTP)     (regras)    (persistência)

Duas regras sustentam a estrutura:

  • Regras de negócio existem apenas na camada de serviço — nunca em routers ou repositórios.
  • Repositórios são injetados via Depends, nunca instanciados dentro do serviço.

O raciocínio completo, as alternativas descartadas e os critérios para reavaliar a decisão estão em ADR-001.

Como rodar

Requer Python 3.11+.

git clone https://github.com/GabrielBarros0602/SmartBudget_API.git
cd SmartBudget_API

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

pip install -r requirements-dev.txt
Copy-Item .env.example .env

docker compose up -d db
alembic upgrade head

uvicorn app.main:app --reload

As migrations não rodam quando a API sobe: alembic upgrade head é um passo seu, uma vez e depois de cada pull que trouxer migration nova.

Documentação interativa em http://127.0.0.1:8000/docs.

Status

Em desenvolvimento. O andamento fica em docs/ROADMAP.md, um checklist por sprint onde cada decisão arquitetural só fecha quando o ADR correspondente está commitado.

Mais informações

Esta seção cobre o essencial. O restante está na versão em inglês, no topo deste arquivo — incluindo as fontes das estatísticas citadas acima:

Features por sprint · Stack completa · Estrutura de pastas · Roadmap · Convenções de contribuição · Fontes

About

A personal finance management REST API in Python. It targets a real market pain in Brazil: PIX made transactions faster and more fragmented, and most people have lost track of where their money goes; household debt remains high, and the market splits between manual spreadsheets and closed consumer apps.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages