How joycejsm/hackathon-ada-extrato-popular works
1. Visão geral
O repositório é uma API REST de gestão financeira pessoal construída com Spring Boot 3.3 / Java 21, seguindo uma organização próxima de Clean Architecture. O fluxo central é: HTTP controllers → use cases/services de aplicação → domínio/persistência/integrations → resposta DTO.
2. Camada de entrada HTTP
Tudo que expõe a API fica em interfaces/controller: AuthController, TransacaoController, OrcamentoController, ChatController, RelatorioController e AiController. Eles aceitam DTOs de interfaces/dto, chamam os casos de uso e retornam respostas já modeladas para o cliente. GlobalExceptionHandler padroniza as falhas da aplicação em respostas HTTP consistentes.
3. Autenticação e segurança
A segurança é um subsistema próprio em infrastructure/security, com Spring Security + JWT. JwtAuthenticationFilter intercepta as requisições protegidas, JwtService emite/valida tokens e SecurityUtils fornece o usuário autenticado para o restante da aplicação. O userId não é confiado ao cliente; ele é derivado do token, o que sustenta o isolamento entre usuários.
4. Cadastros e perfil
Os casos de uso RegisterUserUseCase, LoginUserUseCase e GetUserProfileUseCase concentram o ciclo de vida do usuário. Eles operam sobre a entidade domain/model/User e o UserRepository, garantindo que autenticação, persistência e regras como e-mail único fiquem fora dos controllers.
5. Ingestão de transações
A importação de extratos é um pipeline separado: TransacaoController recebe arquivo em lote, IngestaoTransacoesUseCase coordena o processo, e os parsers em infrastructure/parser tratam CSV e OFX/QFX. Os registros brutos viram TransacaoRaw/ParseResult, passam por categorização automática e deduplicação por hash antes de persistirem como domain/model/Transacao.
6. Regras de negócio de transações
HashService cria a assinatura usada para impedir duplicatas; CategorizacaoService classifica despesas por palavras-chave; ResumoTransacoesUseCase e InsightsTransacoesUseCase agregam os dados para resumo mensal e análises. Esse bloco transforma transações individuais em indicadores financeiros, como receitas, despesas, saldo, gastos por categoria e médias.
7. Orçamentos e alertas
OrcamentoUseCase administra o CRUD de orçamentos sobre domain/model/Orcamento via OrcamentoRepository. O resumo financeiro cruza transações e orçamentos para gerar alertas de limite, com níveis definidos em domain/enums/NivelAlerta. Essa integração é o ponto onde gastos reais viram sinais de controle orçamentário.
8. Otimização financeira
O cálculo de sugestões fica em application/service/otimizacao, com Strategy Pattern. OtimizacaoStrategyFactory escolhe entre KnapsackOtimizacaoStrategy, GulosaOtimizacaoStrategy e RoiOtimizacaoStrategy, produzindo ResultadoOtimizacao. O OtimizacaoUseCase expõe isso para a API, permitindo recomendar cortes e economias a partir do perfil de gasto do usuário.
9. Pipeline de IA / RAG
A parte de IA combina contexto financeiro + prompt + LLM. FinancialContextService e sua implementação FinancialContextServiceImpl montam o contexto dos últimos 90 dias, limitando volume e tamanho. Em cima disso, ChatFinanceService, ReportFinanceService, ChatService e RelatorioService orquestram chamadas ao Spring AI ChatClient e à OpenAI API. O objetivo é responder perguntas e gerar relatórios com base apenas nos dados do próprio usuário.
10. Camada de infraestrutura
infrastructure/config reúne configuração de Swagger e IA; infrastructure/ai/OpenAiClient encapsula a integração externa; infrastructure/persistence contém os repositórios Spring Data JPA para User, Transacao e Orcamento. O ambiente usa H2 no desenvolvimento e está preparado para PostgreSQL em produção, o que afeta apenas a persistência, não as regras de negócio.
11. Domínio e contratos
O pacote domain concentra as entidades, enums e exceções do sistema. Os enums modelam categorias, tipo de transação, origem da importação e nível de alerta; as exceções tipadas representam cenários como arquivo inválido, transação duplicada, orçamento duplicado, credenciais inválidas e falhas de IA. Isso mantém o vocabulário de negócio consistente entre use cases, controllers e handlers.
12. Fluxos principais de dados
Há quatro fluxos arquiteturais dominantes:
• Login/cadastro: controller → use case → repositório → JWT.
• Importação: upload → parser → categorização/hash → persistência → resumo.
• Análise/orçamento: transações + orçamentos → agregação → alertas/otimização.
• IA/RAG: usuário autenticado → contexto financeiro → prompt → OpenAI → resposta.
13. Testes e confiabilidade
A base de testes é extensa e cobre unitários, integração de controllers, segurança, parsers, IA e estratégias de otimização. Isso indica que a arquitetura foi desenhada para validar as fronteiras entre camadas, especialmente autenticação, isolamento multi-tenant, parsing de extratos e comportamento do pipeline de IA.
14. Resumo para diagrama
Se for desenhar a arquitetura, os blocos mais importantes são: HTTP/API, segurança JWT, casos de uso, domínio, persistência JPA, parsers de arquivo, motor de otimização, pipeline RAG/OpenAI e tratamento global de erros. O sistema é essencialmente uma API financeira monolítica modularizada, com integrações externas restritas a autenticação, banco de dados e IA.
Main entry points: controller Controllers · persistence JPA repositories · Transacao.java Transacao/Orcamento · IngestaoTransacoesUseCase.java Import flow
Components 18
HTTP API
Controllers, DTOs and exception mapping exposed to clients.
- Controllers · Auth, transactions, budgets, chat, reports and AI endpoints.
src/main/java/com/extratoPopular/interfaces/controller - DTOs · Request and response models exchanged with clients.
src/main/java/com/extratoPopular/interfaces/dto - Errors · Converts domain and application failures into consistent responses.
src/main/java/com/extratoPopular/interfaces/handler/GlobalExceptionHandler.java
Application
Use cases and orchestration services.
- Auth flow · Register, login and profile retrieval use cases.
src/main/java/com/extratoPopular/application/usecase - Import flow · Batch import, parsing, deduplication and categorization of statements.
src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java - Analysis · Monthly summaries and financial insights from transactions.
src/main/java/com/extratoPopular/application/usecase/ResumoTransacoesUseCase.java - Budgets · Budget CRUD and alert generation over spending.
src/main/java/com/extratoPopular/application/usecase/OrcamentoUseCase.java - Optimization · Chooses and runs financial optimization strategies.
src/main/java/com/extratoPopular/application/usecase/OtimizacaoUseCase.java - AI use cases · High-level chat and report services that call the AI pipeline.
src/main/java/com/extratoPopular/application/usecase/ChatFinanceService.java - Rules · Category, transaction type, import source, alert level, hash and categorization logic.
src/main/java/com/extratoPopular/application/service - Strategies · Knapsack, greedy and ROI optimization implementations.
src/main/java/com/extratoPopular/application/service/otimizacao
Domain
Core entities, enums and business exceptions.
- User · Authenticated user and registration profile.
src/main/java/com/extratoPopular/domain/model/User.java - Transacao/Orcamento · Core financial records used by analysis and budgeting.
src/main/java/com/extratoPopular/domain/model/Transacao.java
Infrastructure
Security, persistence, parsing, AI and external integrations.
- JWT security · JWT filter, token service and security utilities.
src/main/java/com/extratoPopular/infrastructure/security - JPA repositories · Spring Data repositories for users, transactions and budgets.
src/main/java/com/extratoPopular/infrastructure/persistence - File parsers · Extracts raw transactions from CSV and OFX/QFX files.
src/main/java/com/extratoPopular/infrastructure/parser - OpenAI client · Configures and wraps the OpenAI/Spring AI integration.
src/main/java/com/extratoPopular/infrastructure/ai/OpenAiClient.java
Finance AI
RAG and OpenAI-backed chat/report generation.
- RAG services · Builds financial context and prompts for chat and reports.
src/main/java/com/extratoPopular/application/rag
Connections 27
- Controllers → Auth flow: auth/profile · Controllers delegate registration, login and profile requests to application use cases.
- Controllers → Import flow: import · Transaction endpoints pass uploaded files into the ingestion pipeline.
- Controllers → Analysis: summary/insights · Controllers expose aggregated transaction views to clients.
- Controllers → Budgets: budgets · Budget endpoints delegate CRUD and alert calculations.
- Controllers → Optimization: optimize · Optimization requests are handled by the optimization use case.
- Controllers → AI use cases: chat/report · Chat and report controllers invoke the AI orchestration layer.
- Controllers → DTOs: request/response · Controllers consume and return API DTOs.
- Errors → Controllers: errors · Exception handler standardizes failures raised by controllers and downstream layers.
- Auth flow → User: user rules · Authentication and registration operate on the User entity.
- Auth flow → JPA repositories: users · User lifecycle uses the user repository for persistence and lookup.
- Auth flow → JWT security: jwt · Login issues tokens and profile access depends on authenticated identity.
- Import flow → File parsers: raw import · Ingestion uses CSV and OFX parsers to extract raw statement rows.
- Import flow → Rules: dedupe/categorize · Pipeline applies hash-based deduplication and category assignment.
- Import flow → Transacao/Orcamento: persist transactions · Parsed and cleaned transactions are stored as domain entities.
- Import flow → JPA repositories: store · Ingestion persists transactions through repository adapters.
- Analysis → Transacao/Orcamento: aggregate · Summaries and insights are computed from transaction data.
- Budgets → Transacao/Orcamento: budget data · Budget management uses transaction and budget entities.
- Budgets → JPA repositories: budget repo · Budgets are stored and queried via repositories.
- Budgets → Rules: alerts · Alert levels and budget checks are derived from domain rules.
- Optimization → Strategies: strategy select · The use case selects the optimization algorithm through a factory.
- Optimization → Transacao/Orcamento: recommendations · Optimization is based on spending and financial entities.
- AI use cases → RAG services: context/prompt · Chat and report services assemble context and prompts before calling the model.
- RAG services → OpenAI client: LLM call · Prompted requests are sent through the OpenAI integration.
- RAG services → Transacao/Orcamento: financial context · RAG builds context from recent user financial data.
- JWT security → JPA repositories: authenticate · JWT and security utilities rely on user persistence for identity resolution.
- JPA repositories → User: users · Repository layer stores and loads user entities.
- JPA repositories → Transacao/Orcamento: transactions/budgets · Repository layer stores and loads financial entities.