Sobre o Monii

Plataforma web focada em organização financeira pessoal, permitindo registrar transações, planejar categorias, acompanhar relatórios consolidados e administrar preferências em uma experiência responsiva integrada ao back-end Java.

Stacks e Tecnologias

• Front-end: React 18 + TypeScript, Vite, TailwindCSS, Radix UI primitives, Lucide icons, Zustand-like context próprio, Bun para scripts.
• Back-end: Spring Boot 3, Java, Spring Security/JWT, JPA/Hibernate, DTO pattern para relatórios/exportações, Gradle.
• Infra: Docker/Docker Compose, Nginx como edge, MariaDB 11.4, phpMyAdmin para suporte operacional.

Demonstração

• Tela inicial (mobile): demonstração da tela inicial em um celular, respeitando margens e tudo mais.

  

• Autenticação: tela de login com campos para e-mail e senha e opções de "Login"/"Registrar".

  

• Tela inicial (Desktop): cards de saldo total, receitas, despesas e seções "Análise/Gestão/Agilidade", além da lista de transações recentes com ícones de categoria.

  

• Dashboard: filtros rápidos (30/90 dias, ano atual, personalizado), KPI de taxa de economia, cards de maiores gastos/ganhos e evolução mensal com barras de progresso.

  

• Transações: formulário lateral com seletor de tipo, categoria, valor e data, seguido da lista detalhada (descrição, categoria e valor) pronta para CRUD.

  

• Categorias: abas "Despesas/Receitas" exibindo cards com orçamento, gasto, estado (Disponível/Excedido) e cores configuradas por categoria (pelo usuário).

  

• Relatórios: filtros de período com campos de data, cartões de resumo (total, média, maior gasto), evolução mensal e distribuição por categoria com percentuais.

  

• Configurações: módulo de preferências (tema, moeda, idioma) - idioma e moeda não foram implementados para serem alterados, apenas o tema - painel de gerenciamento de dados com botões para exportar, importar e limpar completamente o backup local.

  

• phpMyAdmin: visão do banco monii_dev mostrando as tabelas categories, transactions e users, com estruturas e campos destacados para consultas administrativas.

  

Componentes e responsáveis

Pessoa / Área	Componentes ligados	Hooks citados	Breve nota
Enzo Vieira – Transações	pages/Transactions.tsx, components/finance/TransactionForm.tsx, components/finance/TransactionList.tsx	useTransactions coordena CRUD online/offline; useFinancialSummary resume impactos; além de useState/useEffect para formular e paginar.	Responsável por toda a etapa de cadastro, edição e exibição de lançamentos, garantindo sincronização com o back-end e feedback imediato.
Moisés – Home/Navegação	pages/Home.tsx, components/common/Header.tsx, components/common/MobileNav.tsx, components/NavLink.tsx	useDashboardSummary abastece cards; useMobile detecta breakpoints para alternar entre botões e drawer; useAuth expõe sessão no menu; useMemo filtra destaques.	Entrega a experiência inicial e a navegação primária (desktop e mobile), mantendo métricas em tempo real logo na página de entrada.
Pedro – Configurações & Preferências	pages/Settings.tsx, components/settings/PreferenceToggleList.tsx, components/settings/DataManagementPanel.tsx, components/common/PrivateRoute.tsx	useFinance aplica preferências (tema) e dispara refresh; useAuth mantém o gate de rotas; useRef/useCallback conduzem import/export; useToast informa o usuário.	Centraliza preferências, exportação/importação de dados e limpeza segura, garantindo persistência em localStorage e sincronização pós-backup.
Jandeson – Categorias	pages/Categories.tsx, components/finance/CategoryForm.tsx, components/finance/CategoryCard.tsx	useCategories abastece e ordena categorias; useState dirige formulários; useEffect atualiza listas quando o back-end responde.	Define como o usuário planeja orçamentos e organizações visuais de despesas/receitas.
Davi – Relatórios	pages/Reports.tsx, components/reports/ReportFilters.tsx, components/reports/ReportTransactionsTable.tsx, components/finance/BalanceCard.tsx	useFinancialSummary gera fallback local; useDashboardSummary alimenta KPIs; useAuth trata expiradas; useMemo/useCallback/useRef sustentam filtros, exportação CSV e histórico.	Cuida da análise completa (tabelas, filtros, CSV) e garante consistência entre períodos aplicados e métricas exibidas.

Páginas e responsáveis

Página (arquivo)	Responsável	Escopo funcional	Integrações/Operações
Auth (pages/Auth.tsx)	Enzo Vieira	Tela tabulada de login/registro com validação, loading state e redirecionamento automático quando o usuário já está autenticado.	Usa useAuth/authService para POST /api/auth/login e POST /api/auth/register, persiste o JWT retornado, consulta perfil via GET /api/auth/me e renova sessão com POST /api/auth/refresh.
Home (pages/Home.tsx)	Moisés – Navegação	Landing responsiva com hero, CTAs para transações/dashboard, BalanceCard e TransactionList limitada aos últimos lançamentos.	BalanceCard consome useDashboardSummary (GET /api/dashboard/summary), enquanto TransactionList lê o cache vivo de useTransactions (GET /api/transactions).
Dashboard (pages/Dashboard.tsx)	Moisés & Davi	Painel completo com filtros rápidos/personalizados, KPIs, top categorias e evolução mensal, mantendo fallback local caso o back-end esteja indisponível.	useDashboardSummary consulta /api/dashboard/summary e /api/dashboard/summary/monthly, enviando startDate/endDate/months. Quando a API falha, useFinancialSummary reconstrói o resumo a partir do estado do FinanceContext.
Transactions (pages/Transactions.tsx)	Enzo Vieira – Transações	CRUD principal de receitas/despesas com formulário validado e lista paginada que reflete pendências offline.	TransactionForm e TransactionList operam financeService (POST/PUT/DELETE /api/transactions); ao ficar offline, o offlineQueue gera IDs locais sincronizados depois via FinanceContext.
Categories (pages/Categories.tsx)	Jandeson – Categorias	Tabs para receitas/despesas, diálogos de criação/edição, confirmação de exclusão e botão de sincronização manual.	useCategories chama GET /api/categories e delega POST/PUT/DELETE para financeService, validando ownership e exibindo feedback via toast.
Reports (pages/Reports.tsx)	Davi & Enzo Vieira – Relatórios	KPIs detalhados, filtros com debounce, histórico mensal e exportação CSV baseada em seleção de período.	Usa financeService.fetchReport (GET /api/reports?startDate&endDate) e financeService.exportReport (GET /api/reports/export). Em caso de 401, chama useAuth.logout() e redireciona.
Settings (pages/Settings.tsx)	Pedro – Preferências	Ajustes de tema/notificações, painel de backup/import/limpeza e contadores locais.	PreferenceToggleList persiste em localStorage + FinanceContext; DataManagementPanel integra com /api/data/export, /api/data/import e DELETE /api/data, recarregando os dados após cada operação.

Endpoints do back-end e integrações

Autenticação (/api/auth)

• POST /register: cria usuários; authService.register envia { name, email, password }, recebe token + perfil e já persiste em localStorage.
• POST /login: valida credenciais; authService.login trata erros do back-end e popula useAuth.
• GET /me: useAuth.checkAuth e FinanceContext usam para hidratar o usuário ao recarregar a página.
• POST /refresh: chamado pelo authService.refreshToken para manter a sessão ativa sem forçar novo login.

Transações (/api/transactions)

• GET /api/transactions: carregado pelo FinanceContext e useTransactions para preencher listas e resumo local; a API entrega categoria normalizada para evitar buscas extras.
• POST /api/transactions: TransactionForm envia payload serializado (type uppercase, date em yyyy-MM-dd). Caso o app esteja offline, o item entra no offlineQueue e é sincronizado assim que FinanceContext detecta conexão.
• PUT /api/transactions/{id}: usado na edição inline da lista.
• DELETE /api/transactions/{id}: remove lançamentos e dispara refreshFinancialSummary() para manter o saldo correto.

Categorias (/api/categories)

• GET /api/categories: popula tabs de Categories e uma cópia no FinanceContext para referência cruzada nas transações.
• POST /api/categories: CategoryForm cria categorias, garantindo tipo uppercase e orçamento opcional.
• PUT /api/categories/{id} / DELETE /api/categories/{id}: edição/exclusão com confirmação; erros como "categoria vinculada a transações" são exibidos via toast.

Dashboard (/api/dashboard/summary e /api/dashboard/summary/monthly)

• GET /summary: retorna FinancialSummary (totais, savings rate, top categorias) filtrável por startDate/endDate. Esse payload abastece BalanceCard, Home e Dashboard.
• GET /summary/monthly: histórico de até 12 meses, usado por dashboards e relatórios para montar gráficos/listas; aceita months, startDate, endDate.
• O hook useDashboardSummary memoiza filtros (SummaryPreset) e faz fallback para useFinancialSummary quando a API falha ou o usuário está offline.

Relatórios (/api/reports)

• GET /api/reports: entrega ReportResponse com summary, monthly e transactions. A página Reports aplica filtros e salva o período aplicado para rótulos.
• GET /api/reports/export: retorna CSV pronto; financeService.exportReport baixa como Blob e dispara download com nome contextual (relatorio-AAAA-MM-DD.csv).

Gerenciamento de dados (/api/data)

• GET /api/data/export: DataManagementPanel baixa um DataBackupPayload (metadados + categorias + transações) e o salva em JSON.
• POST /api/data/import: envia o JSON selecionado; após sucesso, offlineQueue.clearAll() e refreshFinanceData() reidratam o app.
• DELETE /api/data: limpeza total de dados do usuário, usada como último recurso nas Configurações.

Healthcheck e segurança

• GET /api/health: endpoint público usado pelos healthchecks do Docker Compose e do Nginx.
• Toda outra rota /api/** é protegida pelo SecurityConfig: o JwtAuthenticationFilter lê o header Authorization, cria o contexto e aplica sessão stateless. O CORS permite http(s)://localhost:*, e apiService sempre envia credentials: 'include' + bearer token.
• Ao receber 401, apiService lança UnauthorizedError; hooks como useAuth, useTransactions, useDashboardSummary capturam esse erro, exibem aviso e deslogam o usuário para evitar loops.

Glossário rápido de termos

• KPI (Key Performance Indicator): métrica-chave que mostra rapidamente se um objetivo financeiro está sendo atingido (ex.: saldo, taxa de economia, número de categorias ativas).
• KPIs: plural de KPI; normalmente exibimos vários ao mesmo tempo em Dashboard/Reports para fornecer visão executiva.
• CRUD (Create, Read, Update, Delete): conjunto básico de operações de dados. Em Transactions e Categories, os formulários/listas implementam essas quatro ações contra o back-end.
• DTO (Data Transfer Object): objeto de transporte usado no back-end para formatar payloads/relatórios antes de enviá-los ao front (ex.: FinancialSummaryResponse). Ajuda a evitar expor entidades internas diretamente.
• JWT (JSON Web Token): token assinado que comprova autenticação. O authService guarda o JWT, envia via header Authorization: Bearer <token> e o JwtAuthenticationFilter valida assinaturas e expiração.
• CORS (Cross-Origin Resource Sharing): política que determina quais origens podem chamar a API. SecurityConfig libera http(s)://localhost:* para desenvolvimento e o Nginx filtra em produção.
• Fallback: estratégia de contingência usada quando o back-end está indisponível; por exemplo, useFinancialSummary gera KPIs localmente quando /api/dashboard/summary falha.
• Fila offline (offlineQueue): buffer local que armazena operações quando o usuário está sem conexão. Assim que a conexão volta, FinanceContext reenvia cada item garantindo que nenhuma edição seja perdida.

Hooks utilizados

• useAuth (hooks/useAuth.tsx): guarda quem está logado, renova o token quando precisa e oferece login/logout para o Header, menu mobile, rotas privadas e tela de configurações.
• useFinance (contexts/FinanceContext.tsx via useFinance): funciona como um “banco” único com transações, categorias, resumo e tema; conversa com a API e também salva tudo no localStorage para abrir rápido.
• useTransactions & useFinancialSummary (hooks/useTransactions.ts, useFinancialSummary.ts): fazem o download das transações, calculam totais e mantêm a lista sincronizada mesmo quando o usuário fica offline.
• useCategories: carrega, ordena e reaproveita as categorias para formulários e cards, evitando chamadas repetidas à API.
• useDashboardSummary: busca os KPIs e o gráfico mensal usados na Home, Dashboard e Relatórios, caindo para dados locais se a API falhar.
• useLocalStorage: abstrai salvar e ler preferências simples (tema, por exemplo) direto do navegador.
• useMobile: detecta se a tela está em modo mobile ou desktop e liga/desliga a navegação correta.
• useToast: dispara avisos rápidos (sucesso/erro) nas telas de Settings, Transações e Categorias sem reinventar componentes.

Hooks nativos do React e como usamos

• useReducer: é o motor do FinanceContext; recebe ações como “adicionar transação” e devolve o novo estado, mantendo tudo organizado e previsível.
• useState: controla valores simples como campos de formulário, loading ou se um modal está aberto, deixando a UI reagir na hora.
• useEffect: roda efeitos quando algo muda (ex.: filtros, usuário logado) para buscar dados, registrar listeners de rede e limpar recursos depois.
• useMemo: guarda resultados de contas pesadas (totais, listas filtradas) e só refaz quando as entradas realmente mudam.
• useCallback: mantém funções estáveis para passar a componentes filhos (botões, formulários), evitando renderizações extras e bugs com dependências.
• useRef: guarda referências para elementos reais (input de upload, lista scrollável) ou flags simples sem forçar re-render.

Banco de Dados e stack Docker

• Banco: MariaDB 11.4, armazenando usuários, categorias e transações; volume mariadb_data garante persistência. phpMyAdmin roda ao lado para inspeções administrativas.
• Compose stack:
  • db (MariaDB) com healthcheck e env compartilhado.
  • phpmyadmin conectado à mesma rede para suporte.
  • back-end (Spring Boot, Dockerfile dedicado) expondo API + health check.
  • frontend (Vite build/preview) consumindo VITE_API_URL.
  • nginx atuando como reverse proxy e servindo o bundle estático.
  • Todos os serviços ficam na rede monii-network, com dependências/healthchecks orquestrando a subida em cadeia.

Diagrama técnico (Apenas para visualização rápida do back-end e front-end)