From 07e15cd9a9472a2d98583b2feef2870e0b5424f3 Mon Sep 17 00:00:00 2001 From: Renato97 Date: Tue, 31 Mar 2026 01:32:51 -0300 Subject: [PATCH] docs: update README with bilingual documentation - Add English and Spanish sections - Improve project description and features - Add professional formatting --- README.md | 203 ++++++++++++++++++------------------------------------ 1 file changed, 66 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index 8f9dbb7..a4047bd 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,90 @@ -# 💰 Finanzas - Gestor Personal de Finanzas +# 💰 Finanzas - Personal Finance Dashboard -Una aplicación moderna y completa para la gestión de finanzas personales, construida con Next.js y TypeScript. Controla tus deudas, tarjetas de crédito, presupuestos y mantente al día con alertas inteligentes. +## 📝 Description / Descripción -![Dashboard Preview](./preview.png) +**English:** +A modern personal finance management application built with Next.js 14. Track expenses, income, debts, credit cards, and budgets with AI-powered predictions and Telegram notifications. -## ✨ Características Principales +**Español:** +Una aplicación moderna de gestión de finanzas personales construida con Next.js 14. Rastrea gastos, ingresos, deudas, tarjetas de crédito y presupuestos con predicciones impulsadas por IA y notificaciones de Telegram. -### 🏠 Dashboard Central -- **Resumen financiero** con métricas clave -- **Actividad reciente** y tendencias -- **Acciones rápidas** para agregar gastos y pagos -- **Alertas inteligentes** personalizadas +## 🚀 Features / Características -### 💳 Gestión de Tarjetas de Crédito -- Múltiples tarjetas con límites y saldos -- Registro de pagos y compras -- Seguimiento de cuotas e instalaciones -- Alertas de cierre y vencimiento +**English:** +- Dashboard with financial overview +- Expense and income tracking +- Credit card management with payment alerts +- Debt tracking with payment scheduling +- Budget management with visual progress +- AI-powered spending predictions +- Telegram bot notifications for alerts +- Secure authentication with OTP +- Data synchronization across devices +- Responsive design for mobile and desktop -### 📊 Control de Deudas -- **Deudas fijas**: Alquiler, servicios, suscripciones -- **Deudas variables**: Compras, entretenimiento, salud -- Categorización automática -- Marcado de pagos realizados -- Notas y recordatorios +**Español:** +- Dashboard con resumen financiero +- Seguimiento de gastos e ingresos +- Gestión de tarjetas de crédito con alertas de pago +- Seguimiento de deudas con programación de pagos +- Gestión de presupuestos con progreso visual +- Predicciones de gastos impulsadas por IA +- Notificaciones de bot de Telegram para alertas +- Autenticación segura con OTP +- Sincronización de datos entre dispositivos +- Diseño responsive para móvil y escritorio -### 💰 Presupuesto Mensual -- Ingresos y gastos planificados -- Metas de ahorro -- Seguimiento en tiempo real -- Visualización con gráficos +## 🛠️ Tech Stack / Stack Tecnológico -### 🚨 Sistema de Alertas -- Alertas de vencimiento de pagos -- Advertencias de presupuesto -- Recordatorios de cierre de tarjetas -- Detección de gastos inusuales -- Notificaciones de metas de ahorro +- **Framework:** Next.js 14 (App Router) +- **Language:** TypeScript +- **Styling:** Tailwind CSS +- **UI Components:** Custom + shadcn/ui +- **State Management:** Zustand +- **Authentication:** JWT + OTP +- **AI:** OpenAI API for predictions +- **Notifications:** Telegram Bot API +- **Database:** JSON-based storage (server-side) +- **Build Output:** Static export -### 📱 Diseño Responsivo -- Sidebar colapsible en desktop -- Navegación móvil intuitiva -- Interfaz moderna con Tailwind CSS -- Soporte completo para dispositivos móviles +## 📊 Dashboard Components -## 🛠️ Stack Tecnológico +- **Summary Cards:** Total balance, monthly income/expenses +- **Charts:** Expense breakdown, spending trends +- **Alerts:** Payment due dates, budget warnings +- **Quick Actions:** Add transactions, view reports -- **[Next.js 14](https://nextjs.org/)** - Framework React con SSR/SSG -- **[TypeScript](https://www.typescriptlang.org/)** - Tipado estático -- **[Tailwind CSS](https://tailwindcss.com/)** - Estilos utilitarios -- **[Zustand](https://github.com/pmndrs/zustand)** - Gestión de estado -- **[Recharts](https://recharts.org/)** - Gráficos y visualizaciones -- **[Lucide React](https://lucide.dev/)** - Iconos modernos +## 🔧 Setup / Configuración -## 🚀 Instalación y Uso +**English:** +1. Install dependencies: `npm install` +2. Set environment variables in `.env.local` +3. Run development server: `npm run dev` +4. Build for production: `npm run build` -### Prerrequisitos -- Node.js 18+ -- npm o yarn +**Español:** +1. Instala dependencias: `npm install` +2. Configura variables de entorno en `.env.local` +3. Ejecuta servidor de desarrollo: `npm run dev` +4. Construye para producción: `npm run build` -### 1. Clonar el repositorio -```bash -git clone https://gitea.cbcren.online/renato97/finanzas.git -cd finanzas -``` - -### 2. Instalar dependencias -```bash -npm install -``` - -### 3. Ejecutar en desarrollo -```bash -npm run dev -``` - -La aplicación estará disponible en `http://localhost:3000` - -### 4. Construir para producción -```bash -npm run build -``` - -Los archivos estáticos se generarán en el directorio `dist/` - -## 📁 Estructura del Proyecto +## 🌐 Environment Variables ``` -finanzas/ -├── app/ # Rutas y páginas de Next.js -│ ├── alerts/ # Página de alertas -│ ├── budget/ # Página de presupuesto -│ ├── cards/ # Página de tarjetas -│ ├── debts/ # Página de deudas -│ └── page.tsx # Dashboard principal -├── components/ # Componentes reutilizables -│ ├── alerts/ # Sistema de alertas -│ ├── budget/ # Componentes de presupuesto -│ ├── cards/ # Componentes de tarjetas -│ ├── dashboard/ # Componentes del dashboard -│ ├── debts/ # Componentes de deudas -│ ├── layout/ # Layout y navegación -│ └── modals/ # Modales de creación/edición -├── lib/ # Utilidades y store -│ ├── store/ # Estado global con Zustand -│ ├── alerts.ts # Lógica de alertas -│ ├── types.ts # Tipos TypeScript -│ └── utils.ts # Utilidades generales -└── public/ # Archivos estáticos +OPENAI_API_KEY=your_openai_key +TELEGRAM_BOT_TOKEN=your_telegram_token +JWT_SECRET=your_jwt_secret ``` -## 🎯 Funcionalidades Destacadas +## 👨‍💻 Author / Autor -### Estado Global con Zustand -- Gestión reactiva del estado -- Persistencia automática -- Selectores optimizados -- Actualizaciones en tiempo real +**Renato CBC** +- GitHub: [renato97](https://gitea.cbcren.online/renato97) -### Alertas Inteligentes -```typescript -// Tipos de alertas disponibles -- PAYMENT_DUE: Pago próximo a vencer -- BUDGET_WARNING: Límite de presupuesto alcanzado -- CARD_CLOSING: Fecha de cierre de tarjeta -- CARD_DUE: Vencimiento de tarjeta -- SAVINGS_GOAL: Meta de ahorro alcanzada -- UNUSUAL_SPENDING: Gasto inusual detectado -``` +## 📄 License / Licencia -### Categorización Automática -- **Deudas Fijas**: vivienda, servicios, suscripciones -- **Deudas Variables**: compras, comida, entretenimiento, salud -- **Pagos con Cuotas**: seguimiento de instalaciones - -## 📊 Métricas y Visualizaciones - -- Gráficos de gastos por categoría -- Tendencias de mes a mes -- Progreso de metas de ahorro -- Distribución de deuda total - -## 🔐 Seguridad - -- Validación de datos con TypeScript -- Sanitización de inputs -- Sin almacenamiento de datos sensibles -- Ejecución completamente en el cliente - -## 📄 Licencia - -ISC - -## 👨‍💻 Autor - -Desarrollado por **renato97** +Private project / Proyecto privado --- -⭐ **¿Te gusta el proyecto?** ¡No olvides darle una estrella en Gitea! +**Tags / Etiquetas:** `nextjs` `react` `typescript` `finance` `dashboard` `tailwind` `ai` `telegram`