# igorpacheco1/easy-finance architecture

> Architecture diagram of the GitHub repository igorpacheco1/easy-finance, 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/igorpacheco1/easy-finance
- Repository: https://github.com/igorpacheco1/easy-finance

## Overview

Easy Finance is a personal-finance PWA backed by a Spring REST API. A user records income or expenses with a category and date; the app submits them to the API, which applies transaction and category rules and persists them. The app also supports month summaries, paginated history, filtered search, category management, and offline queued submissions. The README documents PostgreSQL, IndexedDB, and background sync; unsampled subsystems are represented by their exact directories or listed files, with only documented relationships shown.

Main entry points: [`web/src/api/cliente.ts`](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/api/cliente.ts) (HTTP client), [`backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java`](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java) (Transaction endpoints), [`backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java`](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java) (Transaction rules), [`backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java`](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java) (Category data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["PWA experience"]
  node_launch["Record entry<br/>[LancarPagina.tsx]"]
  node_webclient["HTTP client<br/>[cliente.ts]"]
  node_webtypes["API types<br/>[tipos.ts]"]
  node_month["Month view<br/>[useDadosDoMes.ts]"]
  node_monthsummary["Category summary<br/>[useResumoDoMes.ts]"]
  node_search["Transaction search<br/>[useBusca.ts]"]
  node_categoryui["Category management<br/>[useCategorias.ts]"]
  node_dates["Date formatting<br/>[datas.ts]"]
end

subgraph group_offline["Offline support"]
  node_queuehook["Queue coordinator<br/>[useFila.ts]"]
  node_queue[("Offline queue<br/>[banco.ts]")]
  node_sender["Queue sender<br/>[envio.ts]"]
  node_background["Background sync<br/>[sw.ts]"]
end

subgraph group_api["REST API"]
  node_transactionapi["Transaction endpoints"]
  node_categoryapi["Category endpoints"]
  node_summaryapi["Summary endpoints"]
  node_balanceapi["Balance endpoints"]
end

subgraph group_domain["Finance domain"]
  node_transactionlogic["Transaction rules"]
  node_transactiondata[("Transaction data")]
  node_categorylogic["Category rules"]
  node_categorydata[("Category data")]
  node_categorymodel["Category model<br/>[Categoria.java]"]
end

subgraph group_shared["API support"]
  node_errors["Error responses"]
end

node_person(("User"))
node_postgres[("PostgreSQL")]

node_person -->|"records"| node_launch
node_launch -->|"submits via"| node_webclient
node_webclient -->|"HTTP JSON"| node_transactionapi
node_webclient -->|"HTTP JSON"| node_categoryapi
node_month -->|"requests data"| node_webclient
node_monthsummary -->|"requests summary"| node_webclient
node_search -->|"requests matches"| node_webclient
node_categoryui -->|"loads categories"| node_webclient
node_month -->|"gets period"| node_dates
node_queuehook -->|"reads and writes"| node_queue
node_queuehook -->|"invokes"| node_sender
node_sender -.->|"submits queued entries"| node_transactionapi
node_background -.->|"uses queue"| node_queue
node_background -.->|"background submission"| node_transactionapi
node_transactionapi -->|"delegates"| node_transactionlogic
node_categoryapi -->|"delegates"| node_categorylogic
node_summaryapi -->|"requests summary"| node_transactionlogic
node_balanceapi -->|"requests balance"| node_transactionlogic
node_transactionlogic -->|"queries and saves"| node_transactiondata
node_transactionlogic -->|"loads category"| node_categorydata
node_categorylogic -->|"queries and saves"| node_categorydata
node_categorydata -->|"maps entity"| node_categorymodel
node_transactiondata -.->|"persists"| node_postgres
node_categorydata -.->|"persists"| node_postgres
node_transactionapi -.->|"formats failures"| node_errors
node_categoryapi -.->|"formats failures"| node_errors

click node_launch "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/paginas/LancarPagina.tsx"
click node_webclient "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/api/cliente.ts"
click node_webtypes "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/api/tipos.ts"
click node_month "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/mes/useDadosDoMes.ts"
click node_monthsummary "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/mes/useResumoDoMes.ts"
click node_search "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/busca/useBusca.ts"
click node_categoryui "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/categorias/useCategorias.ts"
click node_dates "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/formatacao/datas.ts"
click node_queuehook "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/useFila.ts"
click node_queue "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/banco.ts"
click node_sender "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/envio.ts"
click node_background "https://github.com/igorpacheco1/easy-finance/blob/main/web/src/sw.ts"
click node_transactionapi "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java"
click node_categoryapi "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaController.java"
click node_summaryapi "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/ResumoController.java"
click node_balanceapi "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/SaldoController.java"
click node_transactionlogic "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java"
click node_transactiondata "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoRepository.java"
click node_categorylogic "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaService.java"
click node_categorydata "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java"
click node_categorymodel "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/Categoria.java"
click node_errors "https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/shared/TratadorGlobalDeErros.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_launch,node_webclient,node_webtypes,node_month,node_monthsummary,node_search,node_categoryui,node_dates,node_person toneBlue
class node_queuehook,node_queue,node_sender,node_background,node_postgres toneAmber
class node_transactionapi,node_categoryapi,node_summaryapi,node_balanceapi toneMint
class node_transactionlogic,node_transactiondata,node_categorylogic,node_categorydata,node_categorymodel toneRose
class node_errors toneIndigo
```

## Components

### PWA experience

- [Record entry](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/paginas/LancarPagina.tsx): `web/src/paginas/LancarPagina.tsx`
- [HTTP client](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/api/cliente.ts): `web/src/api/cliente.ts`
- [API types](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/api/tipos.ts): `web/src/api/tipos.ts`
- [Month view](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/mes/useDadosDoMes.ts): `web/src/mes/useDadosDoMes.ts`
- [Category summary](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/mes/useResumoDoMes.ts): `web/src/mes/useResumoDoMes.ts`
- [Transaction search](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/busca/useBusca.ts): `web/src/busca/useBusca.ts`
- [Category management](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/categorias/useCategorias.ts): `web/src/categorias/useCategorias.ts`
- [Date formatting](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/formatacao/datas.ts): `web/src/formatacao/datas.ts`

### Offline support

- [Queue coordinator](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/useFila.ts): `web/src/fila/useFila.ts`
- [Offline queue](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/banco.ts): `web/src/fila/banco.ts`
- [Queue sender](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/fila/envio.ts): `web/src/fila/envio.ts`
- [Background sync](https://github.com/igorpacheco1/easy-finance/blob/main/web/src/sw.ts): `web/src/sw.ts`

### REST API

- [Transaction endpoints](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java`
- [Category endpoints](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaController.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaController.java`
- [Summary endpoints](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/ResumoController.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/ResumoController.java`
- [Balance endpoints](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/SaldoController.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/SaldoController.java`

### Finance domain

- [Transaction rules](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java`
- [Transaction data](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoRepository.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoRepository.java`
- [Category rules](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaService.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaService.java`
- [Category data](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java`
- [Category model](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/Categoria.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/Categoria.java`

### API support

- [Error responses](https://github.com/igorpacheco1/easy-finance/blob/main/backend/src/main/java/io/github/igorpacheco1/easyfinance/shared/TratadorGlobalDeErros.java): `backend/src/main/java/io/github/igorpacheco1/easyfinance/shared/TratadorGlobalDeErros.java`

### Other components

- **User**
- **PostgreSQL**

## Connections

- User → Record entry: records
- Record entry → HTTP client: submits via (evidence: `web/src/paginas/LancarPagina.tsx`)
- HTTP client → Transaction endpoints: HTTP JSON
- HTTP client → Category endpoints: HTTP JSON
- Month view → HTTP client: requests data (evidence: `web/src/mes/useDadosDoMes.ts`)
- Category summary → HTTP client: requests summary (evidence: `web/src/mes/useResumoDoMes.ts`)
- Transaction search → HTTP client: requests matches (evidence: `web/src/busca/useBusca.ts`)
- Category management → HTTP client: loads categories (evidence: `web/src/categorias/useCategorias.ts`)
- Month view → Date formatting: gets period (evidence: `web/src/mes/useDadosDoMes.ts`)
- Queue coordinator → Offline queue: reads and writes (evidence: `web/src/fila/useFila.ts`)
- Queue coordinator → Queue sender: invokes (evidence: `web/src/fila/useFila.ts`)
- Queue sender → Transaction endpoints: submits queued entries
- Background sync → Offline queue: uses queue
- Background sync → Transaction endpoints: background submission
- Transaction endpoints → Transaction rules: delegates (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoController.java`)
- Category endpoints → Category rules: delegates (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaController.java`)
- Summary endpoints → Transaction rules: requests summary (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/ResumoController.java`)
- Balance endpoints → Transaction rules: requests balance (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/SaldoController.java`)
- Transaction rules → Transaction data: queries and saves (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java`)
- Transaction rules → Category data: loads category (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/transacao/TransacaoService.java`)
- Category rules → Category data: queries and saves (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaService.java`)
- Category data → Category model: maps entity (evidence: `backend/src/main/java/io/github/igorpacheco1/easyfinance/categoria/CategoriaRepository.java`)
- Transaction data → PostgreSQL: persists
- Category data → PostgreSQL: persists
- Transaction endpoints → Error responses: formats failures
- Category endpoints → Error responses: formats failures