Finance Wallet API

API REST para gestão financeira pessoal com autenticação JWT, categorias, recorrências, transações e resumo financeiro por período.

Stack

• Node.js 20
• TypeScript
• Fastify
• Drizzle ORM
• PostgreSQL
• Zod
• Docker + Docker Compose
• Node test runner com tsx

Funcionalidades

• Cadastro e login com JWT
• Categorias separadas por tipo: income e expense
• Políticas de recorrência semanais e mensais
• Transações com chave de idempotência
• Resumo financeiro consolidado com filtro por período
• Isolamento por usuário autenticado
• Validação de payloads com mensagens claras
• Documentação interativa com Swagger

Regras de domínio aplicadas

• O usuário autenticado é a fonte de verdade para userId
• Categorias, recorrências e transações são sempre filtradas por usuário
• Uma recorrência só pode ser criada usando categoria do próprio usuário
• Uma transação só pode usar categoria do próprio usuário
• O tipo da transação ou recorrência precisa combinar com o tipo da categoria
• Se recurrenceId for informado na transação, ele precisa pertencer ao mesmo usuário, mesma categoria e mesmo tipo
• endDate de recorrência não pode ser menor que startDate
• idempotencyKey é única por usuário

Estrutura

src/
  app.ts
  server.ts
  db/
  modules/
    auth/
    categories/
    recurrences/
    transactions/
  shared/
  types/
tests/
drizzle/

Variáveis de ambiente

Copie .env.example para .env e preencha:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/finance_wallet
JWT_SECRET=uma_chave_segura
DB_USER=postgres
DB_PASSWORD=postgres
DB_DATABASE=finance_wallet

Como rodar localmente

Sem Docker

pnpm install
pnpm db:migrate
pnpm dev

Com Docker

docker compose up --build

Se você adicionar ou atualizar dependências, prefira subir novamente com rebuild:

docker compose up --build

Se o volume de dependências do container estiver desatualizado, recrie os containers:

docker compose down -v
docker compose up --build

Documentação da API

Com a aplicação em execução, a documentação interativa fica disponível em:

http://localhost:3000/docs

Ela inclui autenticação via Bearer token e exemplos de contrato para as rotas principais.

Scripts

pnpm dev
pnpm build
pnpm start
pnpm lint
pnpm format
pnpm format:check
pnpm test
pnpm test:watch
pnpm db:migrate

Rotas principais

Auth

• POST /auth/signup
• POST /auth/signin

Categories

• GET /categories
• GET /categories/:id
• POST /categories
• PATCH /categories/:id
• DELETE /categories/:id

Recurrences

• GET /recurrences
• GET /recurrences/:id
• POST /recurrences
• PATCH /recurrences/:id
• DELETE /recurrences/:id

Transactions

• GET /transactions
• GET /transactions/:id
• POST /transactions
• DELETE /transactions/:id

Financial

• GET /financial/summary

Exemplos de payload

Criar categoria

{
  "name": "Salario",
  "type": "income"
}

Criar recorrência

{
  "categoryId": "uuid-da-categoria",
  "amount": 1500,
  "description": "Aluguel",
  "type": "expense",
  "frequency": "monthly",
  "step": 1,
  "startDate": "2026-04-01",
  "endDate": "2026-12-01"
}

Criar transação

{
  "categoryId": "uuid-da-categoria",
  "recurrenceId": "uuid-da-recorrencia",
  "amount": 1500,
  "description": "Aluguel abril",
  "type": "expense",
  "transactionDate": "2026-04-05",
  "idempotencyKey": "expense-rent-2026-04"
}

Consultar resumo financeiro

GET /financial/summary?startDate=2026-04-01&endDate=2026-04-30
Authorization: Bearer <token>

Qualidade

• Build TypeScript
• Testes automatizados para contrato e proteção de rota
• Padronização de resposta com { success, data | error }
• Migrações versionadas com Drizzle
• Swagger/OpenAPI em /docs

Próximos passos

• Adicionar paginação e filtros por período
• Expor resumo mensal de receitas, despesas e saldo
• Criar seed de dados de demonstração
• Adicionar testes de integração com banco dedicado

Decisões técnicas

• Fastify foi escolhido pela simplicidade e performance para APIs
• Drizzle deixa o schema explícito no código e facilita versionamento com SQL
• Zod mantém validação próxima do contrato HTTP
• A separação por módulos ajuda a escalar a API por domínio