FinSightAI

Ver más allá de tus finanzas

Proyecto desarrollado para el Hackathon Oracle Next Education (ONE) y No Country
Equipo TwentyNine Devs · G9 LATAM Team 29

📖 Descripción

FinSightAI es una plataforma web que ayuda a los usuarios a comprender su situación financiera mediante técnicas de Ciencia de Datos, Machine Learning e Inteligencia Artificial.

A partir de los ingresos, deudas, hábitos de ahorro y transacciones financieras, la plataforma analiza el comportamiento económico del usuario, clasifica automáticamente sus gastos, identifica patrones de consumo y genera recomendaciones personalizadas para favorecer una mejor toma de decisiones — con Finsi, un asistente conversacional, como guía en todo el proceso.

💬 "¡Hola! Soy Finsi — te acompaño en cada análisis, cada meta y cada duda financiera."

🎯 Problema y solución

Muchas personas registran sus ingresos y gastos, pero les resulta difícil transformar esos datos en información útil para comprender su situación financiera y mejorar su planificación económica.

FinSightAI convierte esos datos en información clara, explicable y accionable mediante modelos de Machine Learning, un Financial Score propio y un agente de IA capaz de responder preguntas concretas sobre las finanzas del usuario.

🚀 Funcionalidades

💰 Gestión financiera

Importación de movimientos vía CSV con clasificación automática de categorías.
Historial de transacciones con resúmenes y filtros por tipo/categoría.
Análisis del perfil financiero y Financial Score personalizado.
Evaluación del nivel de riesgo con explicación automática, fortalezas y oportunidades de mejora.
Recomendaciones financieras personalizadas y priorizadas.
Metas de ahorro: creación, aportes, liberación de fondos y cancelación.
Recordatorios y eventos financieros en calendario (exportables a .ics).
Exportación de reportes en CSV, XLSX y PDF.

🤖 Inteligencia Artificial — Finsi

Asistente conversacional financiero con memoria de contexto (Groq / Gemini).
Motor determinístico + LLM híbrido para respuestas explicables y consistentes.
Respuestas en streaming para una conversación más fluida.
Chat de soporte técnico con base de conocimiento propia (RAG).
Clasificación de gastos y de perfil financiero vía modelos de ML entrenados en el pipeline de Data Science.
Políticas de seguridad que bloquean el acceso a datos de otros usuarios e intentos de prompt injection.

🎮 Engagement

Sistema de logros y gamificación, con historial de desbloqueos.
Notificaciones push y recordatorios por correo.
Dashboard interactivo con historial de análisis.
Finsi acompaña la experiencia con mensajes contextuales en cada pantalla.

🔐 Cuenta y plataforma

Autenticación y sesiones vía Supabase (JWT), recuperación y cambio de contraseña.
Roles de Usuario / Administrador, con cuentas demo para evaluación.
Verificación de propiedad de datos en cada endpoint sensible (OwnershipInterceptor).
Cierre de sesión automático por inactividad, además del manual.
Baja de cuenta con preservación de historial (soft delete).
API REST documentada (OpenAPI/Swagger) para integraciones externas.

🛠 Stack tecnológico

Capa	Tecnologías
Frontend	React 19, TypeScript, Vite, TailwindCSS 4, React Router, Supabase JS, ApexCharts, jsPDF / ExcelJS
Backend	Java 21, Spring Boot 3.4, Spring Data JPA, Flyway, OAuth2 Resource Server, SpringDoc OpenAPI (Swagger)
AI-Service	Python, FastAPI, scikit-learn, Pandas, NumPy, FAISS (RAG), Joblib, Groq y Gemini (LLM)
Datos y autenticación	Supabase (PostgreSQL + Auth)
Cloud y despliegue	Vercel (frontend + Edge Functions), Render (Backend y AI-Service vía Docker)
DevOps	Git, GitHub, GitHub Actions, Docker

🏗 Arquitectura

flowchart TB
    Browser(["🧑‍💻 Usuario"])

    subgraph Vercel["▲ Vercel — Frontend"]
        SPA["React + Vite + TypeScript"]
        Edge["Edge Functions Node/TS<br/>registro · recuperar clave · push · calendario"]
    end

    subgraph Render["🔺 Render — Docker"]
        Backend["Backend<br/>Spring Boot 3 · Java 21"]
        AIService["AI-Service<br/>FastAPI · agente Finsi"]
        Models[("Modelos .joblib<br/>+ índice FAISS")]
    end

    subgraph Supabase["⚡ Supabase"]
        Auth["Auth · GoTrue (JWT)"]
        DB[("PostgreSQL")]
    end

    LLM["Groq · Gemini"]
    Resend["Resend — Email"]

    Browser --> SPA
    SPA -- "REST /api" --> Backend
    SPA -- "/agent/chat" --> AIService
    SPA -- "login / signup" --> Auth
    SPA --> Edge
    Edge --> Auth
    Edge --> Resend

    Backend -- "JPA / Flyway" --> DB
    Backend -. "valida JWT" .-> Auth
    AIService -- "datos del usuario (X-Service-Token)" --> Backend
    AIService --> Models
    AIService --> LLM

📊 Flujo de funcionamiento

flowchart LR
    A[Inicio de sesión] --> B[Registro de datos /<br/>importación CSV]
    B --> C[Clasificación automática<br/>de gastos]
    C --> D[Análisis del perfil<br/>financiero]
    D --> E[Score y<br/>recomendaciones]
    E --> F[Dashboard, metas<br/>y asistente Finsi]

📂 Estructura del proyecto

Backend/Backend/     # API REST — Spring Boot (Java 21)
AI-Service/          # Microservicio de IA — FastAPI, agente Finsi, modelos ML
Data-Science/        # Notebook, datasets y pipeline de Machine Learning
frontend/            # SPA — React + Vite + Edge Functions (Vercel)
docs/                # Casos de uso, documentación técnica y auditorías
scripts/database/    # Scripts de carga de datos a Supabase

⚙️ Puesta en marcha local

Backend — Spring Boot

cd Backend/Backend
mvn spring-boot:run

AI-Service — FastAPI

cd AI-Service
python -m venv .venv
.venv\Scripts\activate      # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend — React + Vite

cd frontend
npm install
npm run dev

Variables de entorno y guía completa de despliegue en producción (Vercel + Render + Supabase): ver DEPLOY.md.

📚 Documentación

Documento	Contenido
`docs/casos_uso.md`	18 casos de uso (patrón Boundary–Control–Entity) con diagramas de secuencia
`docs/ai-service/`	Documentación técnica del microservicio de IA
`docs/data-science/`	Documentación del pipeline de Ciencia de Datos
`Data-Science/README.md`	Notebook, modelos e integración con el AI-Service
`DEPLOY.md`	Infraestructura y guía de despliegue
`owasp-audit-report.md`	Informe interno de revisión de seguridad (OWASP)
API Backend	Swagger / OpenAPI en `/swagger-ui.html` al levantar el servicio

🚧 La documentación técnica del Frontend está en preparación — próxima actualización.

🤖 Ciencia de Datos

El AI-Service se apoya en dos modelos propios, entrenados sobre datos sintéticos y serializados con Joblib al final de un pipeline de 28 pasos: generación de datos → EDA → limpieza → ingeniería de atributos → entrenamiento → validación cruzada → calibración → interpretabilidad → exportación.

Modelo	Técnica	Accuracy	F1 macro
Clasificador de gastos (16 categorías)	TF-IDF + `SGDClassifier` calibrado	99.7 % (CV agrupada por descripción)	97.7 %
Clasificador de perfil financiero (3 clases)	Regresión logística	89.6 % (CV estratificada, 5 folds)	90.1 %

Validación agrupada por descripción (StratifiedGroupKFold): las transacciones se agrupan por texto para que la misma descripción nunca aparezca en train y test a la vez, evitando fuga de datos y una accuracy inflada artificialmente.
Calibración de probabilidades (CalibratedClassifierCV, método sigmoide) antes de exponer el modelo en producción, para que los scores de confianza sean interpretables.
Gate de calidad automático que el clasificador de gastos debe aprobar antes de serializarse: accuracy ≥ 0.90, F1 macro ≥ 0.88, brecha train/test ≤ 0.05 y F1 mínimo por clase ≥ 0.80.
Artefactos exportados: clasificador_gastos.joblib, clasificador_perfil.joblib, metadata_modelos.json, metricas_modelos.csv, ejemplos_respuesta_backend.json — el mismo pipeline serializado se carga tal cual en el AI-Service, sin reescribir el preprocesamiento.

⚠️ Entrenado con datos sintéticos. El Financial Score y el perfil no constituyen una calificación crediticia ni un diagnóstico profesional; antes de un uso productivo real haría falta reentrenar con datos reales, sumar monitoreo de deriva y revisión por especialistas del dominio — ver limitaciones completas en Data-Science/README.md.

Notebook completo, ejecutable en Google Colab: Data-Science/FinSightAI_DataScience_1.0.ipynb ·

📅 Estado del proyecto

✅ Diseño de arquitectura y pipeline de datos
✅ Entrenamiento y serialización de modelos de ML
✅ Microservicio de IA (FastAPI) + agente conversacional Finsi
✅ Backend (Spring Boot) integrado con Supabase y el AI-Service
✅ Frontend (React) con dashboard, metas, CSV y exportación de reportes
✅ Gamificación y notificaciones (push + email)
✅ Despliegue en Vercel (frontend) y Render (Backend / AI-Service)
✅ Auditoría de seguridad inicial (OWASP)
✅ Presentación final del proyecto

👥 Equipo

G9 LATAM Team 29

Equipo multidisciplinario participante del Hackathon Oracle Next Education (ONE) y No Country.
Desarrollo de Frontend, Backend, Ciencia de Datos, Machine Learning, UX/UI y Gestión Ágil.

Guillermo
Illanes

_{Team Lead ·
Full Stack Developer}

_Argentina

Alberto Edgardo
Villalba

_{Full Stack Developer ·
AI Developer · Data Scientist}

_Argentina

Felipe Pereira
Alarcón

_{Full Stack Developer ·
Frontend · Data Scientist}

_Chile

Karen
Domínguez

_{Data Analyst ·
QA Tester}

_Colombia

Raúl Enrique
Vidaurre Vallejos

_{Data Analyst · Backend ·
QA Tester}

_Perú

_{Finsi — mascota (y sexto miembro honorario) del equipo 🐦}

📸 Capturas de pantalla

📊 Dashboard Financiero

Modo Claro ☀️	Modo Oscuro 🌙

📈 Análisis Financiero & Predicciones de ML

Modo Claro ☀️	Modo Oscuro 🌙

🤖 Asistente IA (Finsi) & Recomendaciones Personalizadas

Asistente IA (Modo Claro) ☀️	Asistente IA (Modo Oscuro) 🌙

Recomendaciones (Modo Claro) ☀️	Recomendaciones (Modo Oscuro) 🌙

💳 Transacciones & Metas Financieras

Gestor de Transacciones	Metas de Ahorro

🎮 Gamificación, Modo Matrix y Herramientas

Modo Matrix (Easter Egg 🕶️)	Juegos y Logros

Calendario Financiero	Centro de Soporte

🔌 Documentación de APIs (Backend Spring Boot & AI Service FastAPI)

Swagger REST API (Java Spring Boot)	AI Service API Docs (Python FastAPI)

📄 Licencia

Proyecto desarrollado con fines educativos para el Hackathon Oracle Next Education (ONE), organizado por Alura Latam, Oracle y No Country.

Su propósito es demostrar la integración de tecnologías de desarrollo web, Ciencia de Datos, Machine Learning e Inteligencia Artificial para resolver un problema real relacionado con la educación financiera.

Name		Name	Last commit message	Last commit date
.bats		.bats
AI-Service		AI-Service
Backend/backend		Backend/backend
Data-Science		Data-Science
docs		docs
frontend		frontend
scripts/database		scripts/database
tmp/imagegen		tmp/imagegen
.env.example		.env.example
.gitignore		.gitignore
Caddyfile		Caddyfile
Caddyfile.dev		Caddyfile.dev
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
logo.png		logo.png
logo_team.png		logo_team.png
package-lock.json		package-lock.json
render.yaml		render.yaml

Navigation Menu

Uh oh!

Repository files navigation

FinSightAI

📖 Descripción

🎯 Problema y solución

🚀 Funcionalidades

🛠 Stack tecnológico

🏗 Arquitectura

📊 Flujo de funcionamiento

📂 Estructura del proyecto

⚙️ Puesta en marcha local

📚 Documentación

🤖 Ciencia de Datos

📅 Estado del proyecto

👥 Equipo

G9 LATAM Team 29

📸 Capturas de pantalla

📊 Dashboard Financiero

📈 Análisis Financiero & Predicciones de ML

🤖 Asistente IA (Finsi) & Recomendaciones Personalizadas

💳 Transacciones & Metas Financieras

🎮 Gamificación, Modo Matrix y Herramientas

🔌 Documentación de APIs (Backend Spring Boot & AI Service FastAPI)

📄 Licencia

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

FinSightAI

📖 Descripción

🎯 Problema y solución

🚀 Funcionalidades

🛠 Stack tecnológico

🏗 Arquitectura

📊 Flujo de funcionamiento

📂 Estructura del proyecto

⚙️ Puesta en marcha local

📚 Documentación

🤖 Ciencia de Datos

📅 Estado del proyecto

👥 Equipo

G9 LATAM Team 29

📸 Capturas de pantalla

📊 Dashboard Financiero

📈 Análisis Financiero & Predicciones de ML

🤖 Asistente IA (Finsi) & Recomendaciones Personalizadas

💳 Transacciones & Metas Financieras

🎮 Gamificación, Modo Matrix y Herramientas

🔌 Documentación de APIs (Backend Spring Boot & AI Service FastAPI)

📄 Licencia

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages