# eduardo-ve/gestor-gastos architecture

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

- Interactive diagram: https://gitdiagram.com/eduardo-ve/gestor-gastos
- Repository: https://github.com/eduardo-ve/gestor-gastos

## Overview

#### Purpose and Entry Points
Gestor de Gastos is a personal-finance web application for authenticated users to record income/expenses, manage category budgets, track recurring fixed expenses, and view spending analytics. It runs as a Next.js 16 App Router application. Root routing and shared providers begin at `app/layout.tsx`, `app/page.tsx`, and `app/providers.tsx`; the authenticated product shell is `app/(app)/layout.tsx`.

#### Authentication and Access Boundary
Auth.js v5 supports Google OAuth and email/password credentials. The Auth.js HTTP integration is isolated to `app/api/auth/[...nextauth]/route.ts`; auth configuration and server-side access helpers reside in `lib/auth.ts` and `lib/auth.config.ts`. Login and registration are separate route flows at `app/login/page.tsx`, `app/register/page.tsx`, and `app/register/actions.ts`. `proxy.ts` is the likely request-level route boundary.

#### Authenticated Product Areas
The `(app)` route group contains the core user-facing domains:
- Dashboard aggregation and visual presentation: `app/(app)/dashboard/page.tsx`, `app/(app)/dashboard/dashboard-client.tsx`.
- Transaction recording and listing: `app/(app)/transactions/page.tsx`, `app/(app)/transactions/actions.ts`, `app/(app)/transactions/transactions-client.tsx`.
- User-defined categories: `app/(app)/categories/page.tsx`, `app/(app)/categories/actions.ts`.
- Account settings: `app/(app)/settings/page.tsx`, `app/(app)/settings/actions.ts`.

Server Components provide initial page reads; client components own interactive forms, modals, filters, and charts.

#### Budgeting and Recurrence Domains
Monthly category budgets are managed separately from transaction capture, with status/threshold presentation in `app/(app)/budgets/page.tsx`, `app/(app)/budgets/actions.ts`, and `app/(app)/budgets/budget-status.ts`. Fixed recurring expenses are nested under budgets at `app/(app)/budgets/fixed-expenses/page.tsx`, `app/(app)/budgets/fixed-expenses/fixed-expenses-client.tsx`, and `lib/actions/fixed-expenses.ts`. The data model supports optional linkage between a recurring expense and its actual payment transaction.

#### Data and Mutation Flow
Reads are centralized in `lib/queries.ts` and consumed by server-rendered pages. Writes use Next.js Server Actions colocated with a feature or shared in `lib/actions/`, rather than conventional application API routes. Typical flow is: authenticated user → route/page read → client interaction/modal → Server Action → Prisma persistence → route/UI refresh. Input validation is a business boundary in `lib/validations.ts`.

#### Persistence and External Services
PostgreSQL is the system of record, intended for Neon serverless Postgres. Prisma is configured through `prisma.config.ts`; runtime client/database access is in `lib/prisma.ts` and `lib/db.ts`. The durable schema and migration history are `prisma/schema.prisma` and `prisma/migrations/`. Core persisted relationships connect `User` ownership to `Category`, `Transaction`, `Budget`, and `FixedExpense`, enforcing per-user financial data boundaries. External services are Neon/PostgreSQL and Google OAuth; passwords use bcryptjs.

#### Runtime and UI Stack
The runtime is Node.js 18.17+ with TypeScript, Next.js, and React 19. Tailwind CSS and shadcn-style primitives provide the dark-first UI (`app/globals.css`, `components/ui/button.tsx`); Recharts supports dashboard visualizations. Default-category provisioning is represented by `lib/default-categories.ts` and `lib/seed-categories.ts`.

Main entry points: [`app/(app)/layout.tsx`](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/layout.tsx) (Authenticated shell), [`lib/prisma.ts`](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/prisma.ts) (Prisma database runtime), [`app/(app)/transactions/actions.ts`](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/transactions/actions.ts) (Server actions), [`app/(app)/budgets/page.tsx`](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/budgets/page.tsx) (Monthly budgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Next.js runtime"]
  node_root["Root layout &amp; providers<br/>app composition<br/>[layout.tsx]"]
end

subgraph group_auth["Authentication"]
  node_proxy{{"Route access boundary<br/>request guard<br/>[proxy.ts]"}}
  node_auth_route["Auth.js HTTP route<br/>auth endpoint<br/>[route.ts]"]
  node_auth_config["Auth configuration<br/>server auth<br/>[auth.ts]"]
  node_login_register["Login &amp; registration<br/>public routes<br/>[page.tsx]"]
  node_google(("Google OAuth<br/>identity provider"))
end

subgraph group_product["Authenticated product"]
  node_app_shell["Authenticated shell<br/>route layout<br/>[layout.tsx]"]
  node_dashboard["Dashboard analytics<br/>[page.tsx]"]
  node_transactions["Transactions<br/>page + server actions<br/>[page.tsx]"]
  node_categories["Categories<br/>page + server actions<br/>[page.tsx]"]
  node_budgets["Monthly budgets<br/>page + server actions<br/>[page.tsx]"]
  node_fixed_expenses["Recurring fixed expenses<br/>nested page + actions<br/>[page.tsx]"]
  node_settings["Account settings<br/>page + server actions<br/>[page.tsx]"]
end

subgraph group_data["Data layer"]
  node_queries["Central read queries<br/>query service<br/>[queries.ts]"]
  node_validation{{"Input validation<br/>business boundary<br/>[validations.ts]"}}
  node_server_actions["Server actions<br/>mutation layer<br/>[actions.ts]"]
  node_prisma_runtime["Prisma database runtime<br/>ORM client<br/>[prisma.ts]"]
  node_schema["Financial data schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_postgres[("Neon PostgreSQL<br/>system of record")]
  node_defaults["Default categories<br/>user provisioning"]
end

node_root -->|"renders protected routes"| node_app_shell
node_proxy -->|"guards access"| node_app_shell
node_auth_route -->|"uses"| node_auth_config
node_auth_config -->|"OAuth provider"| node_google
node_login_register -->|"signs in"| node_auth_route
node_app_shell -->|"hosts"| node_dashboard
node_app_shell -->|"hosts"| node_transactions
node_app_shell -->|"hosts"| node_categories
node_app_shell -->|"hosts"| node_budgets
node_app_shell -->|"hosts"| node_settings
node_budgets -->|"nested domain"| node_fixed_expenses
node_dashboard -->|"initial reads"| node_queries
node_transactions -->|"initial reads"| node_queries
node_budgets -->|"initial reads"| node_queries
node_queries -->|"reads via"| node_prisma_runtime
node_transactions -->|"interactive writes"| node_server_actions
node_categories -.->|"interactive writes"| node_server_actions
node_budgets -.->|"interactive writes"| node_server_actions
node_fixed_expenses -.->|"recurrence writes"| node_server_actions
node_server_actions -->|"validates"| node_validation
node_validation -->|"permits persistence"| node_prisma_runtime
node_prisma_runtime -->|"maps models"| node_schema
node_prisma_runtime -->|"persists"| node_postgres
node_login_register -.->|"provisions"| node_defaults
node_defaults -->|"creates records"| node_prisma_runtime

click node_root "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/layout.tsx"
click node_proxy "https://github.com/eduardo-ve/gestor-gastos/blob/main/proxy.ts"
click node_auth_route "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/api/auth/%5B...nextauth%5D/route.ts"
click node_auth_config "https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/auth.ts"
click node_login_register "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/login/page.tsx"
click node_app_shell "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/layout.tsx"
click node_dashboard "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/dashboard/page.tsx"
click node_transactions "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/transactions/page.tsx"
click node_categories "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/categories/page.tsx"
click node_budgets "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/budgets/page.tsx"
click node_fixed_expenses "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/budgets/fixed-expenses/page.tsx"
click node_settings "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/settings/page.tsx"
click node_queries "https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/queries.ts"
click node_validation "https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/validations.ts"
click node_server_actions "https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/transactions/actions.ts"
click node_prisma_runtime "https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/prisma.ts"
click node_schema "https://github.com/eduardo-ve/gestor-gastos/blob/main/prisma/schema.prisma"
click node_defaults "https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/default-categories.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_root toneBlue
class node_proxy,node_auth_route,node_auth_config,node_login_register,node_google toneAmber
class node_app_shell,node_dashboard,node_transactions,node_categories,node_budgets,node_fixed_expenses,node_settings toneMint
class node_queries,node_validation,node_server_actions,node_prisma_runtime,node_schema,node_postgres,node_defaults toneRose
```

## Components

### Next.js runtime

- [Root layout & providers](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/layout.tsx): app composition · Starts shared routing and client providers. · `app/layout.tsx`

### Authentication

- [Route access boundary](https://github.com/eduardo-ve/gestor-gastos/blob/main/proxy.ts): request guard · `proxy.ts`
- [Auth.js HTTP route](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/api/auth/%5B...nextauth%5D/route.ts): auth endpoint · `app/api/auth/[...nextauth]/route.ts`
- [Auth configuration](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/auth.ts): server auth · Provides Auth.js configuration and server access helpers. · `lib/auth.ts`
- [Login & registration](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/login/page.tsx): public routes · `app/login/page.tsx`
- **Google OAuth**: identity provider

### Authenticated product

- [Authenticated shell](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/layout.tsx): route layout · `app/(app)/layout.tsx`
- [Dashboard analytics](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/dashboard/page.tsx): server page + client charts · `app/(app)/dashboard/page.tsx`
- [Transactions](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/transactions/page.tsx): page + server actions · Records and lists income and expenses. · `app/(app)/transactions/page.tsx`
- [Categories](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/categories/page.tsx): page + server actions · `app/(app)/categories/page.tsx`
- [Monthly budgets](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/budgets/page.tsx): page + server actions · Shows category thresholds and budget status. · `app/(app)/budgets/page.tsx`
- [Recurring fixed expenses](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/budgets/fixed-expenses/page.tsx): nested page + actions · Can link a recurring expense to its payment transaction. · `app/(app)/budgets/fixed-expenses/page.tsx`
- [Account settings](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/settings/page.tsx): page + server actions · `app/(app)/settings/page.tsx`

### Data layer

- [Central read queries](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/queries.ts): query service · `lib/queries.ts`
- [Input validation](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/validations.ts): business boundary · `lib/validations.ts`
- [Server actions](https://github.com/eduardo-ve/gestor-gastos/blob/main/app/(app)/transactions/actions.ts): mutation layer · Feature-colocated actions persist interactive changes. · `app/(app)/transactions/actions.ts`
- [Prisma database runtime](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/prisma.ts): ORM client · `lib/prisma.ts`
- [Financial data schema](https://github.com/eduardo-ve/gestor-gastos/blob/main/prisma/schema.prisma): Prisma schema · User-owned categories, transactions, budgets, and fixed expenses. · `prisma/schema.prisma`
- **Neon PostgreSQL**: system of record
- [Default categories](https://github.com/eduardo-ve/gestor-gastos/blob/main/lib/default-categories.ts): user provisioning · `lib/default-categories.ts`

## Connections

- Root layout & providers → Authenticated shell: renders protected routes
- Route access boundary → Authenticated shell: guards access
- Auth.js HTTP route → Auth configuration: uses
- Auth configuration → Google OAuth: OAuth provider
- Login & registration → Auth.js HTTP route: signs in
- Authenticated shell → Dashboard analytics: hosts
- Authenticated shell → Transactions: hosts
- Authenticated shell → Categories: hosts
- Authenticated shell → Monthly budgets: hosts
- Authenticated shell → Account settings: hosts
- Monthly budgets → Recurring fixed expenses: nested domain
- Dashboard analytics → Central read queries: initial reads
- Transactions → Central read queries: initial reads
- Monthly budgets → Central read queries: initial reads
- Central read queries → Prisma database runtime: reads via
- Transactions → Server actions: interactive writes
- Categories → Server actions: interactive writes
- Monthly budgets → Server actions: interactive writes
- Recurring fixed expenses → Server actions: recurrence writes
- Server actions → Input validation: validates
- Input validation → Prisma database runtime: permits persistence
- Prisma database runtime → Financial data schema: maps models
- Prisma database runtime → Neon PostgreSQL: persists
- Login & registration → Default categories: provisions
- Default categories → Prisma database runtime: creates records
