System Architecture
Sistema Financiero is built as a modern full-stack web application using Next.js 15 with the App Router, React 19, TypeScript, and Supabase PostgreSQL. This guide explains how all the pieces fit together.High-Level Overview
The application follows a three-tier architecture:Tech Stack Details
Frontend Technologies
Next.js 15.5.4
React framework with App Router for file-based routing and server components
React 19
Latest React with improved hooks, concurrent features, and server components
TypeScript 5
Type-safe development with full IntelliSense and compile-time error checking
Tailwind CSS 4
Utility-first CSS framework for rapid UI development with dark mode
Backend Technologies
Next.js API Routes
Serverless API endpoints deployed as edge functions
Supabase PostgreSQL
Managed PostgreSQL with real-time subscriptions and Row Level Security
OpenRouter
Unified API gateway for accessing multiple LLM providers
Gemini 2.5 Flash
Google’s fast AI model with vision and function calling capabilities
Supporting Libraries
package.json
Project Structure
The codebase is organized following Next.js 15 App Router conventions:Database Schema
Tables
Sistema Financiero uses a single table architecture for simplicity:Unlike traditional accounting systems with dozens of normalized tables, this app uses one flexible table with smart indexing.
transacciones Table
| Field | Type | Description | Example |
|---|---|---|---|
id | UUID | Unique identifier | 550e8400-e29b-41d4-a716-446655440000 |
fecha | TIMESTAMP | Transaction date/time | 2024-03-15 14:30:00 |
tipo | TEXT | Transaction type | gasto or ingreso |
monto | NUMERIC | Amount (2 decimal places) | 150.50 |
categoria | TEXT | Expense/income category | Alimentación, Salario |
concepto | TEXT | Brief description | Compras del súper |
descripcion | TEXT | Detailed notes | Pan, leche, huevos |
metodo_pago | TEXT | Payment method | Efectivo, Tarjeta, Transferencia |
registrado_por | TEXT | Who registered it | Juan, María |
foto_url | TEXT | Receipt image URL | https://...supabase.co/storage/.../receipt.jpg |
usuario_id | UUID | Foreign key to user | auth.users(id) |
created_at | TIMESTAMP | Record creation time | 2024-03-15 14:30:00 |
Indexes
Performance-optimized indexes for common queries:Row Level Security (RLS)
User data isolation is enforced at the database level:Data Flow
User Registers a Transaction (Manual)
Implementation in code:User Chats with AI Agent
Implementation of the streaming chat endpoint:Dashboard Loads Data
Implementation:Component Architecture
Core Components
Header
Navigation bar with theme toggle and route links
KPICard
Reusable metric display card with glassmorphism effects
TrendChart
Line chart visualization using Chart.js
DataViews
Transaction table with filtering and grouping
Custom Hooks
useEnhancedChat - Manages AI chat state:hooks/useEnhancedChat.ts
API Endpoints
GET /api/transacciones
Fetch transactions with optional filters: Query Parameters:vista- Time view:diaria,semanal,mensual,personalizadafecha_inicio- Start date for custom range (ISO 8601)fecha_fin- End date for custom range (ISO 8601)
POST /api/chat/stream
Streaming AI chat endpoint with function calling: Request Body:Performance Optimizations
Database Indexing
Frontend Optimizations
- Dynamic Imports: Chart.js loaded only when needed to reduce bundle size
- React Server Components: Static content pre-rendered on server
- Image Optimization: Next.js automatic image optimization for receipts
- Dark Mode: CSS variables with zero-JS toggle
API Optimizations
- Streaming Responses: SSE reduces perceived latency for AI chat
- Query Limits: Max 500 transactions per request prevents timeout
- Date Range Filters: Queries only relevant time periods
Security Considerations
Environment Variables
Row Level Security
RLS ensures users can’t access each other’s data:Deployment
Vercel (Recommended)
Import to Vercel
Go to vercel.com and import your repo
Environment-Specific Configuration
next.config.ts
Extending the System
Adding a New Transaction Field
Adding a New Category
Categories are hardcoded arrays - no database changes needed:Switching AI Models
Change the model in the API route:Summary
Sistema Financiero’s architecture prioritizes:- Simplicity: Single table, minimal dependencies
- Security: RLS, environment variables, type safety
- Performance: Indexed queries, streaming responses, optimized bundles
- Developer Experience: TypeScript, hot reload, clear file structure
- User Experience: Real-time updates, responsive design, dark mode
Back to Introduction
Review what Sistema Financiero does
Quick Start Guide
Set up your own instance