Skip to main content

​
Prerequisites

Before installing Sistema Financiero, ensure you have the following prerequisites installed on your system:

Node.js 20+

Download from nodejs.org

npm or yarn

Included with Node.js installation

Git

For cloning the repository

Code Editor

VS Code, WebStorm, or your preferred editor

​
Verify Node.js Installation

Check that Node.js and npm are installed correctly:
Terminal
node --version
# Should output v20.x.x or higher

npm --version
# Should output 10.x.x or higher
Sistema Financiero requires Node.js 20 or higher due to Next.js 15 dependencies.

​
Installation Steps

1

Clone the Repository

Clone the Sistema Financiero repository from GitHub:
Terminal
git clone https://github.com/danielcarreon/sistema-financiero-app.git
cd sistema-financiero-app
If you prefer SSH, use: git clone [email protected]:danielcarreon/sistema-financiero-app.git
2

Install Dependencies

Install all required npm packages:
Terminal
npm install
This will install all dependencies defined in package.json, including:
  • Next.js 15.5.4 (React framework)
  • Supabase client libraries
  • Chart.js for data visualization
  • Tailwind CSS 4 for styling
  • TypeScript 5 for type safety
Installation typically takes 2-5 minutes depending on your internet connection.
3

Verify Installation

Confirm that all dependencies were installed successfully:
Terminal
npm list --depth=0
You should see output listing all installed packages without errors.

​
Dependency Overview

Sistema Financiero uses the following key dependencies:

​
Core Framework

PackageVersionPurpose
next15.5.4React framework with App Router and API routes
react19.1.0UI library for building components
react-dom19.1.0React rendering for web
typescript^5Type-safe JavaScript

​
Backend & Database

PackageVersionPurpose
@supabase/supabase-js^2.58.0PostgreSQL database client

​
UI & Styling

PackageVersionPurpose
tailwindcss^4Utility-first CSS framework
@tailwindcss/typography^0.5.19Typography plugin for Tailwind
next-themes^0.4.6Dark mode support
lucide-react^0.544.0Icon library

​
Data Visualization

PackageVersionPurpose
chart.js^4.5.0Charting library
react-chartjs-2^5.3.0React wrapper for Chart.js

​
Content & Markdown

PackageVersionPurpose
react-markdown^10.1.0Markdown rendering
remark-gfm^4.0.1GitHub Flavored Markdown support
mermaid^11.12.0Diagram and flowchart rendering
All dependencies are production-ready and actively maintained. Check the GitHub repository for the latest versions.

​
Project Structure

After installation, your project structure will look like this: 
sistema-financiero-app/
├── app/                          # Next.js App Router
│   ├── page.tsx                 # Dashboard (home page)
│   ├── registro/page.tsx        # Manual transaction form
│   ├── agente-mejorado/page.tsx # AI chat interface
│   ├── corte-diario/page.tsx    # Daily cut/bulk entry
│   └── api/                     # Backend API routes
│       ├── transacciones/       # Transaction CRUD
│       ├── chat/stream/         # AI chat streaming
│       ├── upload-image/        # OCR for receipts
│       └── auth/                # Authentication
│
├── components/                   # React components
│   ├── Header.tsx               # Navigation bar
│   ├── KPICard.tsx              # Metric cards
│   ├── TrendChart.tsx           # Line charts
│   └── DataViews.tsx            # Transaction table
│
├── hooks/                        # Custom React hooks
│   ├── useEnhancedChat.ts       # Chat state management
│   └── useImageUpload.ts        # Image upload logic
│
├── lib/                          # Utilities
│   └── supabase.ts              # Supabase client
│
├── .env.example                  # Environment variables template
├── package.json                  # Dependencies
├── tsconfig.json                 # TypeScript configuration
└── tailwind.config.ts            # Tailwind CSS config

​
Development Scripts

After installation, you can use these npm scripts: 
npm run dev
# Starts Next.js development server on http://localhost:3000
# Includes hot-reload and fast refresh
Do not run npm run start without first running npm run build. The production server requires a built application.

​
Troubleshooting

​
Common Installation Issues

Problem: The engine "node" is incompatible with this module.Solution: Upgrade to Node.js 20 or higher:
# Using nvm (Node Version Manager)
nvm install 20
nvm use 20

# Or download from nodejs.org
Problem: Permission denied when installing packages globally.Solution: Fix npm permissions or use a Node version manager:
# Option 1: Use npx instead of global install
npx <package-name>

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Problem: TypeScript can’t find installed modules.Solution: Clear cache and reinstall:
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
Problem: npm install takes 10+ minutes.Solution: Disable Windows Defender real-time scanning for node_modules:
  1. Open Windows Security
  2. Go to Virus & threat protection settings
  3. Add exclusion for your project’s node_modules folder

​
Next Steps

Now that you’ve installed Sistema Financiero, proceed to:

Supabase Configuration

Set up your PostgreSQL database

Environment Variables

Configure your environment secrets

Build docs developers (and LLMs) love

Get started for freeTalk to us