# joycejsm/hackathon-ada-extrato-popular architecture

> Architecture diagram of the GitHub repository joycejsm/hackathon-ada-extrato-popular, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joycejsm/hackathon-ada-extrato-popular
- Repository: https://github.com/joycejsm/hackathon-ada-extrato-popular

## Overview

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: [`src/main/java/com/extratoPopular/interfaces/controller`](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/interfaces/controller) (Controllers), [`src/main/java/com/extratoPopular/infrastructure/persistence`](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/persistence) (JPA repositories), [`src/main/java/com/extratoPopular/domain/model/Transacao.java`](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/domain/model/Transacao.java) (Transacao/Orcamento), [`src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java`](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java) (Import flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["HTTP API"]
  node_interfaces_controller["Controllers<br/>REST entrypoints"]
  node_interfaces_dto["DTOs<br/>API contracts"]
  node_global_exception_handler["Errors<br/>HTTP mapping"]
end

subgraph group_application["Application"]
  node_auth_usecases["Auth flow<br/>user lifecycle"]
  node_transacao_pipeline["Import flow<br/>transaction ingestion"]
  node_analise_transacoes["Analysis<br/>aggregation"]
  node_orcamento_usecase["Budgets<br/>budget management"]
  node_otimizacao_usecase["Optimization<br/>strategy orchestration"]
  node_ai_usecases["AI use cases<br/>chat/report orchestration"]
  node_business_rules{{"Rules<br/>domain services/enums"}}
  node_optim_strategies{{"Strategies<br/>optimization algorithms"}}
end

subgraph group_domain["Domain"]
  node_user_domain(("User<br/>entity<br/>[User.java]"))
  node_finance_domain(("Transacao/Orcamento<br/>entities<br/>[Transacao.java]"))
end

subgraph group_infrastructure["Infrastructure"]
  node_security["JWT security<br/>auth filter/service"]
  node_persistence[("JPA repositories<br/>data access")]
  node_parsers["File parsers<br/>csv/ofx ingestion"]
  node_ai_infra["OpenAI client<br/>external AI integration<br/>[OpenAiClient.java]"]
end

subgraph group_finance_ai["Finance AI"]
  node_rag_services["RAG services<br/>prompt/context orchestration"]
end

node_interfaces_controller -->|"auth/profile"| node_auth_usecases
node_interfaces_controller -->|"import"| node_transacao_pipeline
node_interfaces_controller -->|"summary/insights"| node_analise_transacoes
node_interfaces_controller -->|"budgets"| node_orcamento_usecase
node_interfaces_controller -->|"optimize"| node_otimizacao_usecase
node_interfaces_controller -->|"chat/report"| node_ai_usecases
node_interfaces_controller -->|"request/response"| node_interfaces_dto
node_global_exception_handler -->|"errors"| node_interfaces_controller
node_auth_usecases -->|"user rules"| node_user_domain
node_auth_usecases -->|"users"| node_persistence
node_auth_usecases -->|"jwt"| node_security
node_transacao_pipeline -->|"raw import"| node_parsers
node_transacao_pipeline -->|"dedupe/categorize"| node_business_rules
node_transacao_pipeline -->|"persist transactions"| node_finance_domain
node_transacao_pipeline -->|"store"| node_persistence
node_analise_transacoes -->|"aggregate"| node_finance_domain
node_orcamento_usecase -->|"budget data"| node_finance_domain
node_orcamento_usecase -->|"budget repo"| node_persistence
node_orcamento_usecase -->|"alerts"| node_business_rules
node_otimizacao_usecase -->|"strategy select"| node_optim_strategies
node_otimizacao_usecase -->|"recommendations"| node_finance_domain
node_ai_usecases -->|"context/prompt"| node_rag_services
node_rag_services -->|"LLM call"| node_ai_infra
node_rag_services -->|"financial context"| node_finance_domain
node_security -->|"authenticate"| node_persistence
node_persistence -->|"users"| node_user_domain
node_persistence -->|"transactions/budgets"| node_finance_domain

click node_interfaces_controller "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/interfaces/controller"
click node_interfaces_dto "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/interfaces/dto"
click node_global_exception_handler "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/interfaces/handler/GlobalExceptionHandler.java"
click node_auth_usecases "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/usecase"
click node_transacao_pipeline "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java"
click node_analise_transacoes "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/ResumoTransacoesUseCase.java"
click node_orcamento_usecase "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/OrcamentoUseCase.java"
click node_otimizacao_usecase "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/OtimizacaoUseCase.java"
click node_rag_services "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/rag"
click node_ai_usecases "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/ChatFinanceService.java"
click node_user_domain "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/domain/model/User.java"
click node_finance_domain "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/domain/model/Transacao.java"
click node_business_rules "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/service"
click node_security "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/security"
click node_persistence "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/persistence"
click node_parsers "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/parser"
click node_ai_infra "https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/infrastructure/ai/OpenAiClient.java"
click node_optim_strategies "https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/service/otimizacao"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interfaces_controller,node_interfaces_dto,node_global_exception_handler toneBlue
class node_auth_usecases,node_transacao_pipeline,node_analise_transacoes,node_orcamento_usecase,node_otimizacao_usecase,node_ai_usecases,node_business_rules,node_optim_strategies toneAmber
class node_user_domain,node_finance_domain toneMint
class node_security,node_persistence,node_parsers,node_ai_infra toneRose
class node_rag_services toneIndigo
```

## Components

### HTTP API

Controllers, DTOs and exception mapping exposed to clients.

- [Controllers](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/interfaces/controller): REST entrypoints · Auth, transactions, budgets, chat, reports and AI endpoints. · `src/main/java/com/extratoPopular/interfaces/controller`
- [DTOs](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/interfaces/dto): API contracts · Request and response models exchanged with clients. · `src/main/java/com/extratoPopular/interfaces/dto`
- [Errors](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/interfaces/handler/GlobalExceptionHandler.java): HTTP mapping · 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](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/usecase): user lifecycle · Register, login and profile retrieval use cases. · `src/main/java/com/extratoPopular/application/usecase`
- [Import flow](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java): transaction ingestion · Batch import, parsing, deduplication and categorization of statements. · `src/main/java/com/extratoPopular/application/usecase/IngestaoTransacoesUseCase.java`
- [Analysis](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/ResumoTransacoesUseCase.java): aggregation · Monthly summaries and financial insights from transactions. · `src/main/java/com/extratoPopular/application/usecase/ResumoTransacoesUseCase.java`
- [Budgets](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/OrcamentoUseCase.java): budget management · Budget CRUD and alert generation over spending. · `src/main/java/com/extratoPopular/application/usecase/OrcamentoUseCase.java`
- [Optimization](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/OtimizacaoUseCase.java): strategy orchestration · Chooses and runs financial optimization strategies. · `src/main/java/com/extratoPopular/application/usecase/OtimizacaoUseCase.java`
- [AI use cases](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/application/usecase/ChatFinanceService.java): chat/report orchestration · High-level chat and report services that call the AI pipeline. · `src/main/java/com/extratoPopular/application/usecase/ChatFinanceService.java`
- [Rules](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/service): domain services/enums · Category, transaction type, import source, alert level, hash and categorization logic. · `src/main/java/com/extratoPopular/application/service`
- [Strategies](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/service/otimizacao): optimization algorithms · Knapsack, greedy and ROI optimization implementations. · `src/main/java/com/extratoPopular/application/service/otimizacao`

### Domain

Core entities, enums and business exceptions.

- [User](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/domain/model/User.java): entity · Authenticated user and registration profile. · `src/main/java/com/extratoPopular/domain/model/User.java`
- [Transacao/Orcamento](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/domain/model/Transacao.java): entities · 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](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/security): auth filter/service · JWT filter, token service and security utilities. · `src/main/java/com/extratoPopular/infrastructure/security`
- [JPA repositories](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/persistence): data access · Spring Data repositories for users, transactions and budgets. · `src/main/java/com/extratoPopular/infrastructure/persistence`
- [File parsers](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/infrastructure/parser): csv/ofx ingestion · Extracts raw transactions from CSV and OFX/QFX files. · `src/main/java/com/extratoPopular/infrastructure/parser`
- [OpenAI client](https://github.com/joycejsm/hackathon-ada-extrato-popular/blob/main/src/main/java/com/extratoPopular/infrastructure/ai/OpenAiClient.java): external AI integration · 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](https://github.com/joycejsm/hackathon-ada-extrato-popular/tree/main/src/main/java/com/extratoPopular/application/rag): prompt/context orchestration · Builds financial context and prompts for chat and reports. · `src/main/java/com/extratoPopular/application/rag`

## Connections

- 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.
