How eduardo-ve/gestor-gastos works
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: layout.tsx Authenticated shell · prisma.ts Prisma database runtime · actions.ts Server actions · page.tsx Monthly budgets
Components 20
Next.js runtime
- Root layout & providers · Starts shared routing and client providers.
app/layout.tsx
Authentication
- Route access boundary
proxy.ts - Auth.js HTTP route
app/api/auth/[...nextauth]/route.ts - Auth configuration · Provides Auth.js configuration and server access helpers.
lib/auth.ts - Login & registration
app/login/page.tsx - Google OAuth
Authenticated product
- Authenticated shell
app/(app)/layout.tsx - Dashboard analytics
app/(app)/dashboard/page.tsx - Transactions · Records and lists income and expenses.
app/(app)/transactions/page.tsx - Categories
app/(app)/categories/page.tsx - Monthly budgets · Shows category thresholds and budget status.
app/(app)/budgets/page.tsx - Recurring fixed expenses · Can link a recurring expense to its payment transaction.
app/(app)/budgets/fixed-expenses/page.tsx - Account settings
app/(app)/settings/page.tsx
Data layer
- Central read queries
lib/queries.ts - Input validation
lib/validations.ts - Server actions · Feature-colocated actions persist interactive changes.
app/(app)/transactions/actions.ts - Prisma database runtime
lib/prisma.ts - Financial data schema · User-owned categories, transactions, budgets, and fixed expenses.
prisma/schema.prisma - Neon PostgreSQL
- Default categories
lib/default-categories.ts
Connections 25
- 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