# luccasphilot/valora architecture

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

- Interactive diagram: https://gitdiagram.com/luccasphilot/valora
- Repository: https://github.com/luccasphilot/valora

## Overview

Valora is a personal-finance app: Open Finance imports account data, while users can also record transactions manually and manage budgets, goals, bills, and planned entries. The backend exposes these capabilities through a Fastify API, with PostgreSQL persistence; the React frontend is present in the tree, though the README describes its screens as still in progress. The graph emphasizes documented routes, service calls, synchronization, and storage. Unsampled subsystems are included where the README or tree supports their existence, but their internal links are omitted when evidence is unavailable.

Main entry points: [`backend/src/app.ts`](https://github.com/luccasphilot/valora/blob/main/backend/src/app.ts) (API setup), [`backend/src/modules/dashboard/dashboard.service.ts`](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/dashboard/dashboard.service.ts) (Dashboard), [`backend/src/db/database.ts`](https://github.com/luccasphilot/valora/blob/main/backend/src/db/database.ts) (Database access), [`backend/src/modules/sync/sync.service.ts`](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/sync/sync.service.ts) (Sync orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and overview"]
  node_app["API setup<br/>[app.ts]"]
  node_dashboard["Dashboard"]
  node_frontend["React frontend<br/>[main.tsx]"]
end

subgraph group_finance["Finance features"]
  node_accounts["Accounts"]
  node_transactions["Transactions"]
  node_categories["Categories"]
  node_budgets["Budgets<br/>[budgets.service.ts]"]
  node_bills["Card bills"]
  node_goals["Goals<br/>[goals.service.ts]"]
  node_planned["Planned entries"]
  node_projection["Projection"]
  node_alerts["Alerts<br/>[alerts.module.ts]"]
end

subgraph group_sync["Open Finance sync"]
  node_connections["Connections"]
  node_sync["Sync orchestration<br/>[sync.service.ts]"]
  node_pluggy{{"Meu Pluggy"}}
end

subgraph group_data["Persistence"]
  node_database["Database access<br/>[database.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
  node_postgres[("PostgreSQL")]
end

node_user(("Person"))

node_user -->|"uses API"| node_app
node_app -->|"registers routes"| node_accounts
node_app -->|"registers routes"| node_connections
node_app -->|"registers routes"| node_dashboard
node_app -->|"registers routes"| node_budgets
node_app -->|"registers routes"| node_transactions
node_accounts -->|"reads and writes"| node_database
node_connections -->|"reads and writes"| node_database
node_categories -->|"reads and writes"| node_database
node_goals -->|"reads and writes"| node_database
node_database -->|"uses tables"| node_schema
node_database -->|"queries"| node_postgres
node_app -->|"registers routes"| node_sync
node_sync -->|"fetches data"| node_pluggy
node_sync -->|"uses connection records"| node_connections
node_sync -->|"evaluates alerts"| node_alerts
node_app -->|"registers routes"| node_alerts
node_app -->|"registers routes"| node_planned
node_app -->|"registers routes"| node_goals
node_app -->|"registers routes"| node_bills
node_app -->|"registers routes"| node_projection
node_app -->|"registers routes"| node_categories
node_dashboard -->|"uses account totals"| node_accounts
node_dashboard -->|"loads budgets"| node_budgets
node_dashboard -->|"loads goals"| node_goals
node_dashboard -->|"loads projection"| node_projection
node_dashboard -->|"loads transactions"| node_transactions
node_frontend -.->|"calls API"| node_app

click node_app "https://github.com/luccasphilot/valora/blob/main/backend/src/app.ts"
click node_accounts "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/accounts/accounts.service.ts"
click node_connections "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/connections/connections.service.ts"
click node_transactions "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/transactions/transactions.service.ts"
click node_categories "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/categories/categories.repository.ts"
click node_budgets "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/budgets/budgets.service.ts"
click node_bills "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/credit-card-bills/credit-card-bills.service.ts"
click node_goals "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/goals/goals.service.ts"
click node_planned "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/planned-entries/planned-entries.service.ts"
click node_projection "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/projection/projection.service.ts"
click node_dashboard "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/dashboard/dashboard.service.ts"
click node_alerts "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/alerts/alerts.module.ts"
click node_sync "https://github.com/luccasphilot/valora/blob/main/backend/src/modules/sync/sync.service.ts"
click node_database "https://github.com/luccasphilot/valora/blob/main/backend/src/db/database.ts"
click node_schema "https://github.com/luccasphilot/valora/blob/main/backend/src/db/schema.ts"
click node_frontend "https://github.com/luccasphilot/valora/blob/main/frontend/src/main.tsx"

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_app,node_dashboard,node_frontend toneBlue
class node_accounts,node_transactions,node_categories,node_budgets,node_bills,node_goals,node_planned,node_projection,node_alerts toneAmber
class node_connections,node_sync,node_pluggy toneMint
class node_database,node_schema,node_postgres toneRose
class node_user toneIndigo
```

## Components

### API and overview

- [API setup](https://github.com/luccasphilot/valora/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Dashboard](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/dashboard/dashboard.service.ts): `backend/src/modules/dashboard/dashboard.service.ts`
- [React frontend](https://github.com/luccasphilot/valora/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`

### Finance features

- [Accounts](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/accounts/accounts.service.ts): `backend/src/modules/accounts/accounts.service.ts`
- [Transactions](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/transactions/transactions.service.ts): `backend/src/modules/transactions/transactions.service.ts`
- [Categories](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/categories/categories.repository.ts): `backend/src/modules/categories/categories.repository.ts`
- [Budgets](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/budgets/budgets.service.ts): `backend/src/modules/budgets/budgets.service.ts`
- [Card bills](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/credit-card-bills/credit-card-bills.service.ts): `backend/src/modules/credit-card-bills/credit-card-bills.service.ts`
- [Goals](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/goals/goals.service.ts): `backend/src/modules/goals/goals.service.ts`
- [Planned entries](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/planned-entries/planned-entries.service.ts): `backend/src/modules/planned-entries/planned-entries.service.ts`
- [Projection](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/projection/projection.service.ts): `backend/src/modules/projection/projection.service.ts`
- [Alerts](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/alerts/alerts.module.ts): `backend/src/modules/alerts/alerts.module.ts`

### Open Finance sync

- [Connections](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/connections/connections.service.ts): `backend/src/modules/connections/connections.service.ts`
- [Sync orchestration](https://github.com/luccasphilot/valora/blob/main/backend/src/modules/sync/sync.service.ts): `backend/src/modules/sync/sync.service.ts`
- **Meu Pluggy**

### Persistence

- [Database access](https://github.com/luccasphilot/valora/blob/main/backend/src/db/database.ts): `backend/src/db/database.ts`
- [Data schema](https://github.com/luccasphilot/valora/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`
- **PostgreSQL**

### Other components

- **Person**

## Connections

- Person → API setup: uses API (evidence: `README.md`)
- API setup → Accounts: registers routes (evidence: `backend/src/app.ts`)
- API setup → Connections: registers routes (evidence: `backend/src/app.ts`)
- API setup → Dashboard: registers routes (evidence: `backend/src/app.ts`)
- API setup → Budgets: registers routes (evidence: `backend/src/app.ts`)
- API setup → Transactions: registers routes (evidence: `backend/src/app.ts`)
- Accounts → Database access: reads and writes
- Connections → Database access: reads and writes
- Categories → Database access: reads and writes (evidence: `backend/src/modules/categories/categories.repository.ts`)
- Goals → Database access: reads and writes
- Database access → Data schema: uses tables (evidence: `backend/src/modules/connections/connections.repository.ts`)
- Database access → PostgreSQL: queries
- API setup → Sync orchestration: registers routes (evidence: `backend/src/app.ts`)
- Sync orchestration → Meu Pluggy: fetches data (evidence: `backend/src/modules/sync/sync.service.ts`)
- Sync orchestration → Connections: uses connection records (evidence: `backend/src/modules/sync/sync.service.ts`)
- Sync orchestration → Alerts: evaluates alerts (evidence: `backend/src/modules/sync/sync.service.ts`)
- API setup → Alerts: registers routes (evidence: `backend/src/app.ts`)
- API setup → Planned entries: registers routes (evidence: `backend/src/app.ts`)
- API setup → Goals: registers routes (evidence: `backend/src/app.ts`)
- API setup → Card bills: registers routes (evidence: `backend/src/app.ts`)
- API setup → Projection: registers routes (evidence: `backend/src/app.ts`)
- API setup → Categories: registers routes (evidence: `backend/src/app.ts`)
- Dashboard → Accounts: uses account totals (evidence: `backend/src/modules/dashboard/dashboard.service.ts`)
- Dashboard → Budgets: loads budgets (evidence: `backend/src/modules/dashboard/dashboard.service.ts`)
- Dashboard → Goals: loads goals (evidence: `backend/src/modules/dashboard/dashboard.service.ts`)
- Dashboard → Projection: loads projection (evidence: `backend/src/modules/dashboard/dashboard.service.ts`)
- Dashboard → Transactions: loads transactions (evidence: `backend/src/modules/dashboard/dashboard.service.ts`)
- React frontend → API setup: calls API