# sjtecnologia/equili architecture

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

- Interactive diagram: https://gitdiagram.com/sjtecnologia/equili
- Repository: https://github.com/sjtecnologia/equili

## Overview

Equili is a family-finance application: users authenticate, record income, debts, accounts and transactions, then review dashboards, reports and AI-assisted plans or chat. The React client routes users through those workflows and communicates with a FastAPI API; route handlers operate on persisted finance data. Additional branches cover investments, invoices, lists, voice, push alerts and account administration. The map follows documented routes and cited imports; some UI-to-API and unsampled feature connections remain dashed because their call paths were not shown.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/router.py) (API router), [`backend/app/models`](https://github.com/sjtecnologia/equili/tree/main/backend/app/models) (Finance models), [`backend/app/main.py`](https://github.com/sjtecnologia/equili/blob/main/backend/app/main.py) (FastAPI runtime), [`frontend/src/services/api.ts`](https://github.com/sjtecnologia/equili/blob/main/frontend/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_webapp["React app<br/>[App.tsx]"]
  node_financeui["Finance screens"]
  node_reportsui["Reports screens<br/>[RelatoriosPage.tsx]"]
  node_clientapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_apirouter["API router<br/>[router.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_users["User management<br/>[usuarios.py]"]
end

subgraph group_finance["Finance workflows"]
  node_income["Income<br/>[rendas.py]"]
  node_debts["Debt management<br/>[dividas.py]"]
  node_payables["Payables<br/>[contas_pagar.py]"]
  node_receivables["Receivables<br/>[contas_receber.py]"]
  node_accounts["Bank accounts"]
  node_transactions["Account transactions"]
  node_cards["Card transactions"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_reports["Financial reports<br/>[relatorio.py]"]
  node_investments["Investments<br/>[investimentos.py]"]
end

subgraph group_assist["Assistance and alerts"]
  node_ai["AI plan and chat<br/>[plano_acao.py]"]
  node_chat["AI chat<br/>[chat.py]"]
  node_voice["Voice assistant<br/>[voz.py]"]
  node_invoices["Invoice capture<br/>[nfs.py]"]
  node_lists["Finance lists<br/>[listas.py]"]
  node_push["Push notifications<br/>[notificacoes.py]"]
  node_scheduler["Due-date alerts<br/>[alertas.py]"]
end

subgraph group_infra["Persistence and runtime"]
  node_postgres[("PostgreSQL")]
  node_session["DB sessions<br/>[session.py]"]
  node_models["Finance models"]
  node_server["FastAPI runtime<br/>[main.py]"]
  node_rastro["Rastro telemetry<br/>[rastro_client.py]"]
end

node_user(("Finance user"))
node_githubmodels["GitHub Models"]

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_financeui
node_webapp -.->|"calls"| node_clientapi
node_financeui -.->|"requests data"| node_clientapi
node_reportsui -.->|"requests reports"| node_clientapi
node_clientapi -.->|"HTTP API"| node_server
node_server -->|"mounts"| node_apirouter
node_apirouter -->|"registers"| node_auth
node_apirouter -->|"registers"| node_users
node_apirouter -->|"registers"| node_income
node_apirouter -->|"registers"| node_debts
node_apirouter -->|"registers"| node_payables
node_apirouter -->|"registers"| node_receivables
node_apirouter -->|"registers"| node_accounts
node_apirouter -->|"registers"| node_transactions
node_apirouter -->|"registers"| node_cards
node_apirouter -->|"registers"| node_dashboard
node_apirouter -->|"registers"| node_reports
node_apirouter -->|"registers"| node_investments
node_apirouter -->|"registers"| node_ai
node_apirouter -->|"registers"| node_chat
node_apirouter -->|"registers"| node_voice
node_apirouter -->|"registers"| node_invoices
node_apirouter -->|"registers"| node_lists
node_apirouter -->|"registers"| node_push
node_auth -->|"reads/writes"| node_models
node_debts -->|"reads/writes"| node_models
node_payables -->|"reads/writes"| node_models
node_dashboard -->|"reads"| node_models
node_chat -->|"queries"| node_githubmodels
node_chat -->|"reads"| node_models
node_scheduler -->|"reads due items"| node_models
node_server -->|"starts"| node_scheduler
node_scheduler -.->|"sends alerts"| node_push
node_models -.->|"uses sessions"| node_session
node_session -->|"persists data"| node_postgres
node_server -->|"reports events"| node_rastro

click node_webapp "https://github.com/sjtecnologia/equili/blob/main/frontend/src/App.tsx"
click node_financeui "https://github.com/sjtecnologia/equili/tree/main/frontend/src/pages"
click node_reportsui "https://github.com/sjtecnologia/equili/blob/main/frontend/src/pages/relatorios/RelatoriosPage.tsx"
click node_clientapi "https://github.com/sjtecnologia/equili/blob/main/frontend/src/services/api.ts"
click node_apirouter "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/router.py"
click node_auth "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/auth.py"
click node_users "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/usuarios.py"
click node_income "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/rendas.py"
click node_debts "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/dividas.py"
click node_payables "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_pagar.py"
click node_receivables "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_receber.py"
click node_accounts "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_bancarias.py"
click node_transactions "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/lancamentos_conta.py"
click node_cards "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/lancamentos_cartao.py"
click node_dashboard "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/dashboard.py"
click node_reports "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/relatorio.py"
click node_investments "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/investimentos.py"
click node_ai "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/plano_acao.py"
click node_chat "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/chat.py"
click node_voice "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/voz.py"
click node_invoices "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/nfs.py"
click node_lists "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/listas.py"
click node_push "https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/notificacoes.py"
click node_scheduler "https://github.com/sjtecnologia/equili/blob/main/backend/app/tasks/alertas.py"
click node_session "https://github.com/sjtecnologia/equili/blob/main/backend/app/db/session.py"
click node_models "https://github.com/sjtecnologia/equili/tree/main/backend/app/models"
click node_server "https://github.com/sjtecnologia/equili/blob/main/backend/app/main.py"
click node_rastro "https://github.com/sjtecnologia/equili/blob/main/backend/app/core/rastro_client.py"

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_webapp,node_financeui,node_reportsui,node_clientapi,node_user toneBlue
class node_apirouter,node_auth,node_users toneAmber
class node_income,node_debts,node_payables,node_receivables,node_accounts,node_transactions,node_cards,node_dashboard,node_reports,node_investments toneMint
class node_ai,node_chat,node_voice,node_invoices,node_lists,node_push,node_scheduler toneRose
class node_postgres,node_session,node_models,node_server,node_rastro,node_githubmodels toneIndigo
```

## Components

### Client experience

- [React app](https://github.com/sjtecnologia/equili/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Finance screens](https://github.com/sjtecnologia/equili/tree/main/frontend/src/pages): `frontend/src/pages`
- [Reports screens](https://github.com/sjtecnologia/equili/blob/main/frontend/src/pages/relatorios/RelatoriosPage.tsx): `frontend/src/pages/relatorios/RelatoriosPage.tsx`
- [API client](https://github.com/sjtecnologia/equili/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and identity

- [API router](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/auth.py): `backend/app/api/v1/routes/auth.py`
- [User management](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/usuarios.py): `backend/app/api/v1/routes/usuarios.py`

### Finance workflows

- [Income](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/rendas.py): `backend/app/api/v1/routes/rendas.py`
- [Debt management](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/dividas.py): `backend/app/api/v1/routes/dividas.py`
- [Payables](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_pagar.py): `backend/app/api/v1/routes/contas_pagar.py`
- [Receivables](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_receber.py): `backend/app/api/v1/routes/contas_receber.py`
- [Bank accounts](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/contas_bancarias.py): `backend/app/api/v1/routes/contas_bancarias.py`
- [Account transactions](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/lancamentos_conta.py): `backend/app/api/v1/routes/lancamentos_conta.py`
- [Card transactions](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/lancamentos_cartao.py): `backend/app/api/v1/routes/lancamentos_cartao.py`
- [Dashboard](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/dashboard.py): `backend/app/api/v1/routes/dashboard.py`
- [Financial reports](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/relatorio.py): `backend/app/api/v1/routes/relatorio.py`
- [Investments](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/investimentos.py): `backend/app/api/v1/routes/investimentos.py`

### Assistance and alerts

- [AI plan and chat](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/plano_acao.py): `backend/app/api/v1/routes/plano_acao.py`
- [AI chat](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/chat.py): `backend/app/api/v1/routes/chat.py`
- [Voice assistant](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/voz.py): `backend/app/api/v1/routes/voz.py`
- [Invoice capture](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/nfs.py): `backend/app/api/v1/routes/nfs.py`
- [Finance lists](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/listas.py): `backend/app/api/v1/routes/listas.py`
- [Push notifications](https://github.com/sjtecnologia/equili/blob/main/backend/app/api/v1/routes/notificacoes.py): `backend/app/api/v1/routes/notificacoes.py`
- [Due-date alerts](https://github.com/sjtecnologia/equili/blob/main/backend/app/tasks/alertas.py): `backend/app/tasks/alertas.py`

### Persistence and runtime

- **PostgreSQL**
- [DB sessions](https://github.com/sjtecnologia/equili/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Finance models](https://github.com/sjtecnologia/equili/tree/main/backend/app/models): `backend/app/models`
- [FastAPI runtime](https://github.com/sjtecnologia/equili/blob/main/backend/app/main.py): `backend/app/main.py`
- [Rastro telemetry](https://github.com/sjtecnologia/equili/blob/main/backend/app/core/rastro_client.py): `backend/app/core/rastro_client.py`

### Other components

- **Finance user**
- **GitHub Models**

## Connections

- Finance user → React app: uses (evidence: `README.md`)
- React app → Finance screens: routes to (evidence: `frontend/src/App.tsx`)
- React app → API client: calls
- Finance screens → API client: requests data
- Reports screens → API client: requests reports
- API client → FastAPI runtime: HTTP API
- FastAPI runtime → API router: mounts (evidence: `backend/app/main.py`)
- API router → Authentication: registers (evidence: `backend/app/api/v1/router.py`)
- API router → User management: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Income: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Debt management: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Payables: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Receivables: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Bank accounts: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Account transactions: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Card transactions: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Dashboard: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Financial reports: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Investments: registers (evidence: `backend/app/api/v1/router.py`)
- API router → AI plan and chat: registers (evidence: `backend/app/api/v1/router.py`)
- API router → AI chat: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Voice assistant: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Invoice capture: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Finance lists: registers (evidence: `backend/app/api/v1/router.py`)
- API router → Push notifications: registers (evidence: `backend/app/api/v1/router.py`)
- Authentication → Finance models: reads/writes (evidence: `backend/app/api/v1/routes/auth.py`)
- Debt management → Finance models: reads/writes (evidence: `backend/app/api/v1/routes/dividas.py`)
- Payables → Finance models: reads/writes (evidence: `backend/app/api/v1/routes/contas_pagar.py`)
- Dashboard → Finance models: reads (evidence: `backend/app/api/v1/routes/dashboard.py`)
- AI chat → GitHub Models: queries (evidence: `backend/app/api/v1/routes/chat.py`)
- AI chat → Finance models: reads (evidence: `backend/app/api/v1/routes/chat.py`)
- Due-date alerts → Finance models: reads due items (evidence: `backend/app/tasks/alertas.py`)
- FastAPI runtime → Due-date alerts: starts (evidence: `backend/app/main.py`)
- Due-date alerts → Push notifications: sends alerts
- Finance models → DB sessions: uses sessions
- DB sessions → PostgreSQL: persists data (evidence: `backend/app/db/session.py`)
- FastAPI runtime → Rastro telemetry: reports events (evidence: `backend/app/main.py`)