# joao-fcosta/finance-app architecture

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

## Overview

FinanceApp is a personal-finance web app for recording income and expenses, organizing spending by category, and tracking monthly balances and installments. Users sign in with Google, then use the dashboard to browse months, review totals, and create, edit, or delete transactions; the transaction form supports expense categories and installment purchases. Server Actions validate the authenticated user and perform Supabase operations, while the README describes row-level data isolation. The excerpts show the main UI, action, and auth paths; some dashboard and database details are documented rather than independently verified in source.

Main entry points: [`app/page.tsx`](https://github.com/joao-fcosta/finance-app/blob/main/app/page.tsx) (Monthly dashboard), [`app/actions.ts`](https://github.com/joao-fcosta/finance-app/blob/main/app/actions.ts) (Finance Server Actions), [`app/login/page.tsx`](https://github.com/joao-fcosta/finance-app/blob/main/app/login/page.tsx) (Google login), [`app/auth/callback/route.ts`](https://github.com/joao-fcosta/finance-app/blob/main/app/auth/callback/route.ts) (OAuth callback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication"]
  node_login["Google login<br/>[page.tsx]"]
  node_browserclient["Supabase browser client<br/>[supabase.ts]"]
  node_callback["OAuth callback<br/>[route.ts]"]
  node_proxy["Session gate<br/>[proxy.ts]"]
end

subgraph group_finance["Finance experience"]
  node_dashboard["Monthly dashboard<br/>[page.tsx]"]
  node_modal["Transaction form"]
  node_categories["Expense categories<br/>[page.tsx]"]
end

subgraph group_backend["Data services"]
  node_installments["Installment creation<br/>[actions.ts]"]
  node_actions["Finance Server Actions<br/>[actions.ts]"]
end

node_user(("User"))
node_google{{"Google OAuth"}}
node_supabaseauth{{"Supabase Auth"}}
node_store[("Supabase finance tables")]

node_user -->|"starts login"| node_login
node_login -->|"uses client"| node_browserclient
node_login -->|"requests OAuth"| node_google
node_google -->|"returns code"| node_callback
node_callback -->|"exchanges code"| node_supabaseauth
node_proxy -->|"checks session"| node_supabaseauth
node_user -->|"manages finances"| node_dashboard
node_dashboard -->|"loads and deletes"| node_actions
node_dashboard -->|"opens form"| node_modal
node_modal -->|"creates or edits"| node_actions
node_dashboard -->|"calculates totals"| node_categories
node_actions -->|"reads and writes"| node_store
node_actions -->|"creates installments"| node_installments
node_installments -->|"stores installment records"| node_store

click node_login "https://github.com/joao-fcosta/finance-app/blob/main/app/login/page.tsx"
click node_browserclient "https://github.com/joao-fcosta/finance-app/blob/main/app/lib/supabase.ts"
click node_callback "https://github.com/joao-fcosta/finance-app/blob/main/app/auth/callback/route.ts"
click node_proxy "https://github.com/joao-fcosta/finance-app/blob/main/proxy.ts"
click node_dashboard "https://github.com/joao-fcosta/finance-app/blob/main/app/page.tsx"
click node_modal "https://github.com/joao-fcosta/finance-app/blob/main/app/components/TransactionModal.tsx"
click node_categories "https://github.com/joao-fcosta/finance-app/blob/main/app/page.tsx"
click node_installments "https://github.com/joao-fcosta/finance-app/blob/main/app/actions.ts"
click node_actions "https://github.com/joao-fcosta/finance-app/blob/main/app/actions.ts"

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_login,node_browserclient,node_callback,node_proxy,node_user toneBlue
class node_dashboard,node_modal,node_categories,node_store toneAmber
class node_installments,node_actions toneMint
class node_google,node_supabaseauth toneIndigo
```

## Components

### Authentication

- [Google login](https://github.com/joao-fcosta/finance-app/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Supabase browser client](https://github.com/joao-fcosta/finance-app/blob/main/app/lib/supabase.ts): `app/lib/supabase.ts`
- [OAuth callback](https://github.com/joao-fcosta/finance-app/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Session gate](https://github.com/joao-fcosta/finance-app/blob/main/proxy.ts): `proxy.ts`

### Finance experience

- [Monthly dashboard](https://github.com/joao-fcosta/finance-app/blob/main/app/page.tsx): `app/page.tsx`
- [Transaction form](https://github.com/joao-fcosta/finance-app/blob/main/app/components/TransactionModal.tsx): `app/components/TransactionModal.tsx`
- [Expense categories](https://github.com/joao-fcosta/finance-app/blob/main/app/page.tsx): `app/page.tsx`

### Data services

- [Installment creation](https://github.com/joao-fcosta/finance-app/blob/main/app/actions.ts): `app/actions.ts`
- [Finance Server Actions](https://github.com/joao-fcosta/finance-app/blob/main/app/actions.ts): `app/actions.ts`

### Other components

- **User**
- **Google OAuth**
- **Supabase Auth**
- **Supabase finance tables**

## Connections

- User → Google login: starts login (evidence: `README.md`)
- Google login → Supabase browser client: uses client (evidence: `app/login/page.tsx`)
- Google login → Google OAuth: requests OAuth (evidence: `app/login/page.tsx`)
- Google OAuth → OAuth callback: returns code (evidence: `README.md`)
- OAuth callback → Supabase Auth: exchanges code (evidence: `app/auth/callback/route.ts`)
- Session gate → Supabase Auth: checks session (evidence: `proxy.ts`)
- User → Monthly dashboard: manages finances (evidence: `README.md`)
- Monthly dashboard → Finance Server Actions: loads and deletes (evidence: `app/page.tsx`)
- Monthly dashboard → Transaction form: opens form (evidence: `app/page.tsx`)
- Transaction form → Finance Server Actions: creates or edits (evidence: `app/components/TransactionModal.tsx`)
- Monthly dashboard → Expense categories: calculates totals (evidence: `app/page.tsx`)
- Finance Server Actions → Supabase finance tables: reads and writes (evidence: `app/actions.ts`)
- Finance Server Actions → Installment creation: creates installments (evidence: `app/actions.ts`)
- Installment creation → Supabase finance tables: stores installment records (evidence: `app/actions.ts`)