FinPulse 💰

Aplicação fullstack de controle financeiro pessoal

---

📋 Sobre o Projeto

O FinPulse é uma aplicação web fullstack de gerenciamento financeiro pessoal, desenvolvida com foco em boas práticas de arquitetura de software e segurança de APIs REST.

O back-end foi construído com Java 17 e Spring Boot 3, seguindo uma arquitetura em camadas (Controller → Service → Repository), com autenticação stateless via JWT, isolamento de dados por usuário, e regras de negócio transacionais garantindo consistência total dos dados financeiros.

O front-end foi desenvolvido em React 18 com Vite, utilizando Tailwind CSS para estilização com tema escuro estilo fintech, e Recharts para visualização de dados em gráficos interativos.

---

🖥️ Visão Geral da Interface

Tela de Login / Cadastro

Layout split: branding à esquerda, formulário à direita. Autenticação com validação em tempo real e feedback de erro.

---

Dashboard Principal

Cards de resumo financeiro + gráfico de pizza (despesas por categoria) + gráfico de barras (receitas por categoria). Dados calculados em tempo real a partir das transações do mês atual.

---

Tela de Transações

Listagem de todos os lançamentos financeiros com data, valor, conta e categoria. Formulário inline para criação de novas transações com seleção de conta e categoria.

---

Tela de Metas Financeiras

Cards de metas com barra de progresso animada, percentual de conclusão e funcionalidade de aporte incremental.

---

Tela de Contas

Grid de contas financeiras com ícones por tipo (corrente, cartão, investimento, poupança), saldo individual e saldo total consolidado.

---

✨ Funcionalidades

• 🔐 Autenticação JWT stateless — cadastro, login e proteção de todas as rotas da API
• 🏦 Múltiplas contas financeiras — corrente, cartão de crédito, investimento, poupança e dinheiro
• 🏷️ Categorias personalizadas — receitas e despesas com cor customizável para os gráficos
• 💸 Registro de transações — lançamentos com atualização automática e atômica do saldo da conta
• 🎯 Metas financeiras — definição de objetivos com prazo, valor atual e histórico de aportes
• 📊 Dashboard com gráficos — resumo mensal, gráfico de pizza por categoria de despesa e gráfico de barras por receita
• 🔒 Isolamento de dados — cada usuário acessa exclusivamente seus próprios dados (prevenção de IDOR)

---

🏗️ Arquitetura do Projeto

finpulse/
├── docker-compose.yml              ← sobe tudo com um único comando
├── README.md
├── backend/
│   └── finpulse-api/
│       ├── Dockerfile
│       ├── pom.xml
│       └── src/main/java/com/enzo/finpulse/
│           ├── controller/        ← endpoints HTTP REST (19 endpoints)
│           ├── service/           ← regras de negócio (@Transactional)
│           ├── repository/        ← acesso ao banco (Spring Data JPA)
│           ├── model/             ← entidades JPA (5 tabelas)
│           ├── dto/               ← objetos de entrada/saída da API
│           ├── security/          ← JWT: geração, filtro, autenticação
│           ├── config/            ← Spring Security, CORS
│           └── exception/         ← tratamento global de erros
└── frontend/
    ├── Dockerfile
    ├── nginx.conf
    └── src/
        ├── pages/                 ← Login, Dashboard, Transações, Metas, Contas
        ├── components/            ← Layout, Sidebar
        ├── context/               ← AuthContext (estado global)
        └── services/              ← axios com interceptors JWT

---

🛠️ Tecnologias Utilizadas

Back-end

Tecnologia	Versão	Uso
Java	17	Linguagem principal
Spring Boot	3.3	Framework web e IoC
Spring Security	6.x	Autenticação e autorização
Spring Data JPA	3.x	ORM (mapeamento objeto-relacional)
PostgreSQL	16	Banco de dados relacional
JWT (jjwt)	0.11.5	Tokens de autenticação stateless
Lombok	latest	Redução de boilerplate
Maven	3.9	Gerenciamento de dependências

Front-end

Tecnologia	Versão	Uso
React	18	Biblioteca de interface
Vite	5	Bundler e servidor de desenvolvimento
Tailwind CSS	3	Estilização utility-first
Recharts	2	Gráficos interativos
Axios	1.7	Cliente HTTP com interceptors JWT
React Router	6	Roteamento com rotas protegidas
Lucide React	0.383	Biblioteca de ícones

DevOps

Tecnologia	Uso
Docker	Containerização da aplicação
Docker Compose	Orquestração de múltiplos containers
Nginx	Servidor web para o frontend em produção

---

🗂️ Endpoints da API

Método	Rota	Descrição	Auth
POST	/api/auth/register	Cadastro de novo usuário	❌
POST	/api/auth/login	Login → retorna JWT	❌
GET	/api/accounts	Lista contas do usuário	✅
POST	/api/accounts	Cria nova conta	✅
PUT	/api/accounts/{id}	Atualiza conta	✅
DELETE	/api/accounts/{id}	Remove conta	✅
GET	/api/categories	Lista categorias	✅
POST	/api/categories	Cria categoria	✅
PUT	/api/categories/{id}	Atualiza categoria	✅
DELETE	/api/categories/{id}	Remove categoria	✅
GET	/api/transactions	Lista transações	✅
POST	/api/transactions	Registra transação	✅
DELETE	/api/transactions/{id}	Remove transação	✅
GET	/api/goals	Lista metas	✅
POST	/api/goals	Cria meta	✅
PUT	/api/goals/{id}	Atualiza meta	✅
PATCH	/api/goals/{id}/aporte	Registra aporte	✅
DELETE	/api/goals/{id}	Remove meta	✅
GET	/api/reports/dashboard	Resumo financeiro do período	✅

---

🐳 Rodando com Docker (Recomendado)

Esta é a forma mais simples de rodar o projeto. Com Docker Compose, toda a aplicação — backend, frontend e banco de dados PostgreSQL — é iniciada com um único comando.

Pré-requisitos

• Docker Desktop instalado e rodando

1. Clone o repositório

git clone https://github.com/enzonunestwd/finpulse.git
cd finpulse

2. Suba todos os containers

docker compose up --build

⏳ A primeira execução demora entre 3 e 5 minutos (build do backend Maven + download das imagens base). As execuções seguintes são muito mais rápidas pois o cache é reutilizado.

3. Acesse a aplicação

Serviço	URL
🖥️ Frontend	http://localhost:3000
⚙️ API	http://localhost:8080
🗄️ Banco	localhost:5432 (banco: finpulse, usuário: postgres, senha: finpulse123)

4. Cadastre-se e comece a usar

1. Acesse http://localhost:3000
2. Clique em "Criar conta" e preencha seus dados
3. Vá em Contas → crie pelo menos uma conta financeira
4. Vá em Categorias (via API ou Postman) → crie categorias de receita e despesa
5. Registre transações e veja o Dashboard atualizar em tempo real

Comandos úteis

# Parar todos os containers
docker compose down

# Parar e apagar os dados do banco
docker compose down -v

# Ver logs do backend em tempo real
docker compose logs -f backend

# Ver logs do frontend
docker compose logs -f frontend

---

🧪 Testando a API com Postman

1. Criar conta

POST http://localhost:8080/api/auth/register
Content-Type: application/json

{
  "nome": "Seu Nome",
  "email": "seuemail@email.com",
  "senha": "suasenha123"
}

2. Login (guarde o token retornado)

POST http://localhost:8080/api/auth/login
Content-Type: application/json

{
  "email": "seuemail@email.com",
  "senha": "suasenha123"
}

3. Criar categoria (use o token no header)

POST http://localhost:8080/api/categories
Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

{
  "nome": "Salário",
  "tipo": "RECEITA",
  "cor": "#00D4AA"
}

---

🔧 Rodando sem Docker (Desenvolvimento)

Backend

cd backend/finpulse-api

# Pré-requisitos: Java 17+, Maven 3.8+, PostgreSQL rodando
# Crie o banco: CREATE DATABASE finpulse;
# Configure as credenciais em src/main/resources/application.yml

./mvnw spring-boot:run
# API disponível em: http://localhost:8080

Frontend

cd frontend

npm install
npm run dev
# App disponível em: http://localhost:5173
# O proxy redireciona /api → localhost:8080 automaticamente

---

📁 Estrutura do Banco de Dados

users          → usuários da aplicação (email único, senha com hash BCrypt)
   ↓
accounts       → contas financeiras do usuário (corrente, cartão, etc.)
categories     → categorias de receita/despesa do usuário
goals          → metas financeiras do usuário
   ↓
transactions   → lançamentos financeiros (vinculados a account + category + user)

---

👨‍💻 Autor

Enzo Nunes Andrade

📬 Contato

• GitHub: @enzonunestwd
• LinkedIn: @enzonunesdf
• Email: enzonunestwd@gmail.com