# kaiquegeraldo/controle-financeiro architecture

> Architecture diagram of the GitHub repository kaiquegeraldo/controle-financeiro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaiquegeraldo/controle-financeiro
- Repository: https://github.com/kaiquegeraldo/controle-financeiro

## Overview

This is a personal-finance and life-tracking SaaS with a Next.js frontend and Spring Boot modular-monolith API. A user authenticates, can prepare an onboarding draft, and then records and reviews financial activity; separate product areas cover cards, planning, investments, goals, habits, and reporting. The sampled transaction path shows a controller delegating to a transactional service, while the README documents broader capabilities. Several subsystem links are dashed because their implementation or wiring was not sampled.

Main entry points: [`controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java`](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java) (Cash ledger), [`controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java`](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java) (Auth service), [`controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java`](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java) (Draft handling), [`controle-financeiro-frontend/src/screens/public/auth/authScreen.tsx`](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/screens/public/auth/authScreen.tsx) (Auth screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_auth_ui["Auth screen<br/>[authScreen.tsx]"]
  node_auth_hook["Auth workflow<br/>[useAuth.ts]"]
  node_auth_client["Auth client<br/>[authService.ts]"]
  node_api_proxy["API proxy<br/>[route.ts]"]
end

subgraph group_identity["Identity and onboarding"]
  node_api["REST API"]
  node_auth_controller["Auth endpoints"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_token_service["JWT tokens<br/>[TokenService.java]"]
  node_email_service["Recovery email<br/>[EmailService.java]"]
  node_onboarding_controller["Onboarding API"]
  node_onboarding_draft["Draft handling"]
  node_onboarding_apply["Draft completion"]
  node_onboarding_state[("Onboarding state")]
end

subgraph group_ledger["Financial records"]
  node_transactions_api["Transaction endpoints"]
  node_transactions["Cash ledger"]
  node_accounts[("Accounts<br/>[Account.java]")]
  node_categories[("Categories<br/>[Category.java]")]
  node_cards["Cards and invoices"]
  node_investments["Investments"]
  node_reporting["Coverage reporting"]
end

subgraph group_life_insights["Planning and life tracking"]
  node_planning["Monthly planning"]
  node_annual_summary["Annual summary"]
  node_goals["Goals and checklist<br/>[GoalService.java]"]
  node_habits["Habit tracking"]
  node_dashboard["Dashboard"]
end

node_person(("User"))
node_postgres[("PostgreSQL")]
node_market_data["Brapi market data"]

node_person -->|"uses"| node_auth_ui
node_auth_ui -.->|"starts auth"| node_auth_hook
node_auth_hook -->|"calls"| node_auth_client
node_auth_client -.->|"requests"| node_api_proxy
node_api_proxy -.->|"forwards requests"| node_api
node_auth_controller -.->|"delegates"| node_auth_service
node_auth_service -->|"creates tokens"| node_token_service
node_auth_service -->|"sends recovery"| node_email_service
node_onboarding_controller -.->|"handles drafts"| node_onboarding_draft
node_onboarding_draft -->|"reads and writes"| node_onboarding_state
node_onboarding_draft -->|"delegates completion"| node_onboarding_apply
node_onboarding_apply -->|"persists preparation"| node_onboarding_state
node_transactions_api -->|"delegates"| node_transactions
node_transactions -.->|"updates ledger"| node_accounts
node_transactions -.->|"uses category"| node_categories
node_transactions -.->|"persists records"| node_postgres
node_person -.->|"records activity"| node_transactions_api
node_person -.->|"manages cards"| node_cards
node_person -.->|"tracks assets"| node_investments
node_investments -.->|"gets quotes"| node_market_data
node_person -.->|"plans month"| node_planning
node_person -.->|"tracks goals"| node_goals
node_person -.->|"logs habits"| node_habits
node_person -.->|"reviews year"| node_annual_summary
node_dashboard -.->|"shows coverage"| node_reporting

click node_auth_ui "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/screens/public/auth/authScreen.tsx"
click node_auth_hook "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/hooks/useAuth.ts"
click node_auth_client "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/services/authService.ts"
click node_api_proxy "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/app/api/%5B...path%5D/route.ts"
click node_api "https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api"
click node_auth_controller "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AuthController.java"
click node_auth_service "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java"
click node_token_service "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/security/TokenService.java"
click node_email_service "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/mail/EmailService.java"
click node_onboarding_controller "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/OnboardingController.java"
click node_onboarding_draft "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java"
click node_onboarding_apply "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingApplicationService.java"
click node_onboarding_state "https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/onboarding"
click node_transactions_api "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/TransactionController.java"
click node_transactions "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java"
click node_accounts "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/account/Account.java"
click node_categories "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/category/Category.java"
click node_cards "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/CreditCardService.java"
click node_investments "https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/investment"
click node_reporting "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/ReportingCoverageService.java"
click node_planning "https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/planning"
click node_annual_summary "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AnnualSummaryController.java"
click node_goals "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/GoalService.java"
click node_habits "https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/habit"
click node_dashboard "https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/DashboardController.java"

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_auth_ui,node_auth_hook,node_auth_client,node_api_proxy,node_person toneBlue
class node_api,node_auth_controller,node_auth_service,node_token_service,node_email_service,node_onboarding_controller,node_onboarding_draft,node_onboarding_apply,node_onboarding_state,node_postgres toneAmber
class node_transactions_api,node_transactions,node_accounts,node_categories,node_cards,node_investments,node_reporting,node_market_data toneMint
class node_planning,node_annual_summary,node_goals,node_habits,node_dashboard toneRose
```

## Components

### Web experience

- [Auth screen](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/screens/public/auth/authScreen.tsx): `controle-financeiro-frontend/src/screens/public/auth/authScreen.tsx`
- [Auth workflow](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/hooks/useAuth.ts): `controle-financeiro-frontend/src/hooks/useAuth.ts`
- [Auth client](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/services/authService.ts): `controle-financeiro-frontend/src/services/authService.ts`
- [API proxy](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-frontend/src/app/api/%5B...path%5D/route.ts): `controle-financeiro-frontend/src/app/api/[...path]/route.ts`

### Identity and onboarding

- [REST API](https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api`
- [Auth endpoints](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AuthController.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AuthController.java`
- [Auth service](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java`
- [JWT tokens](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/security/TokenService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/security/TokenService.java`
- [Recovery email](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/mail/EmailService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/infra/mail/EmailService.java`
- [Onboarding API](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/OnboardingController.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/OnboardingController.java`
- [Draft handling](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java`
- [Draft completion](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingApplicationService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingApplicationService.java`
- [Onboarding state](https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/onboarding): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/onboarding`

### Financial records

- [Transaction endpoints](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/TransactionController.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/TransactionController.java`
- [Cash ledger](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java`
- [Accounts](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/account/Account.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/account/Account.java`
- [Categories](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/category/Category.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/category/Category.java`
- [Cards and invoices](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/CreditCardService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/CreditCardService.java`
- [Investments](https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/investment): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/investment`
- [Coverage reporting](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/ReportingCoverageService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/ReportingCoverageService.java`

### Planning and life tracking

- [Monthly planning](https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/planning): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/planning`
- [Annual summary](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AnnualSummaryController.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/AnnualSummaryController.java`
- [Goals and checklist](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/GoalService.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/GoalService.java`
- [Habit tracking](https://github.com/kaiquegeraldo/controle-financeiro/tree/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/habit): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/domain/habit`
- [Dashboard](https://github.com/kaiquegeraldo/controle-financeiro/blob/main/controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/DashboardController.java): `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/DashboardController.java`

### Other components

- **User**
- **PostgreSQL**
- **Brapi market data**

## Connections

- User → Auth screen: uses (evidence: `README.md`)
- Auth screen → Auth workflow: starts auth
- Auth workflow → Auth client: calls (evidence: `controle-financeiro-frontend/src/hooks/useAuth.ts`)
- Auth client → API proxy: requests
- API proxy → REST API: forwards requests
- Auth endpoints → Auth service: delegates
- Auth service → JWT tokens: creates tokens (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java`)
- Auth service → Recovery email: sends recovery (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/AuthService.java`)
- Onboarding API → Draft handling: handles drafts
- Draft handling → Onboarding state: reads and writes (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java`)
- Draft handling → Draft completion: delegates completion (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingDraftService.java`)
- Draft completion → Onboarding state: persists preparation (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/onboarding/OnboardingApplicationService.java`)
- Transaction endpoints → Cash ledger: delegates (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/controller/TransactionController.java`)
- Cash ledger → Accounts: updates ledger (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java`)
- Cash ledger → Categories: uses category (evidence: `controle-financeiro-backend/src/main/java/com/controlefinanceiro/api/service/TransactionService.java`)
- Cash ledger → PostgreSQL: persists records
- User → Transaction endpoints: records activity
- User → Cards and invoices: manages cards
- User → Investments: tracks assets
- Investments → Brapi market data: gets quotes (evidence: `README.md`)
- User → Monthly planning: plans month (evidence: `README.md`)
- User → Goals and checklist: tracks goals (evidence: `README.md`)
- User → Habit tracking: logs habits (evidence: `README.md`)
- User → Annual summary: reviews year (evidence: `README.md`)
- Dashboard → Coverage reporting: shows coverage