Presentación del proyecto OpenStock

Resumen del proyecto

OpenStock es una aplicación moderna y de código abierto para el mercado de valores, diseñada para ofrecer a todos herramientas gratuitas y abiertas para el seguimiento del mercado. Es una alternativa de código abierto a las costosas plataformas comerciales, con soporte para seguimiento en tiempo real de precios, alertas personalizadas y análisis detallado de empresas.

Principio fundamental: El conocimiento debe ser abierto, gratuito y accesible; la tecnología debe pertenecer a todos.

Características principales

🔐 Autenticación

• Sistema de autenticación por correo electrónico/contraseña basado en Better Auth + MongoDB
• Rutas protegidas mediante middleware de Next.js
• Gestión completa de sesiones de usuario

🔍 Búsqueda global

• Búsqueda rápida de acciones, respaldada por la API de Finnhub
• Muestra acciones populares cuando está inactivo, con consultas optimizadas (debounced)
• Panel de comandos accesible mediante el atajo Command + K

⭐ Lista de seguimiento personalizada

• Las acciones seguidas por cada usuario se almacenan en MongoDB
• Cada símbolo bursátil es único por usuario
• Funcionalidad sencilla para añadir/eliminar acciones

📊 Detalles de acciones

• Información sobre símbolos bursátiles proporcionada por TradingView
• Gráficos de velas/avanzados, gráficos de línea base e indicadores técnicos
• Widgets con perfiles empresariales y datos financieros

📈 Visión general del mercado

• Mapas de calor, cotizaciones y titulares de noticias
• Widgets embebidos de TradingView
• Actualización en tiempo real de los datos del mercado

🎯 Proceso de bienvenida personalizado

• Recopila el país del usuario, sus objetivos de inversión
• Tolerancia al riesgo y sectores preferidos
• Experiencia de usuario adaptada individualmente

📧 Correo electrónico y automatización

• Correo de bienvenida personalizado con IA (invocando Gemini mediante Inngest)
• Resúmenes diarios de noticias (tareas programadas)
• Contenido personalizado basado en las acciones seguidas por el usuario

🎨 Interfaz de usuario refinada

• Componentes shadcn/ui + componentes base de Radix UI
• Sistema de diseño con Tailwind v4
• Tema oscuro predeterminado
• Diseño responsivo

Pila tecnológica

Tecnologías principales

• Next.js 15 (App Router)
• React 19
• TypeScript
• Tailwind CSS v4 (mediante @tailwindcss/postcss)
• Componentes base shadcn/ui + Radix UI
• Biblioteca de iconos Lucide

Autenticación y datos

• Better Auth: autenticación por correo/contraseña con adaptador para MongoDB
• MongoDB + Mongoose: persistencia de datos
• API de Finnhub: símbolos bursátiles, perfiles empresariales y noticias del mercado
• TradingView: widgets embebibles de gráficos

Automatización y comunicación

• Inngest: manejo de eventos, tareas programadas e inferencia con IA (Gemini)
• Nodemailer: envío de correos (mediante Gmail)
• next-themes: cambio de tema
• cmdk: panel de comandos
• react-hook-form: gestión de formularios

Composición por lenguajes

• TypeScript (~93,4%)
• CSS (~6%)
• JavaScript (~0,6%)

Estructura del proyecto

app/
├── (auth)/                    # Páginas relacionadas con autenticación
│   ├── layout.tsx
│   ├── sign-in/page.tsx
│   └── sign-up/page.tsx
├── (root)/                    # Páginas principales de la aplicación
│   ├── layout.tsx
│   ├── page.tsx
│   ├── help/page.tsx
│   └── stocks/[symbol]/page.tsx
├── api/inngest/route.ts       # Endpoint de la API de Inngest
├── globals.css
└── layout.tsx

components/
├── ui/                        # Componentes base de shadcn/Radix
├── forms/                     # Componentes de formularios
├── Header.tsx
├── Footer.tsx
├── SearchCommand.tsx
└── WatchlistButton.tsx

database/
├── models/watchlist.model.ts
└── mongoose.ts

lib/
├── actions/                   # Acciones del servidor
│   ├── auth
│   ├── finnhub
│   ├── user
│   └── watchlist
├── better-auth/
├── inngest/                   # Cliente y funciones de Inngest
├── nodemailer/               # Configuración de envío de correos
├── constants.ts
└── utils.ts

scripts/
└── test-db.mjs               # Prueba de conexión a la base de datos

types/
└── global.d.ts

public/assets/images/         # Logotipos y capturas de pantalla

Inicio rápido

Requisitos previos

• Node.js 20+
• pnpm o npm
• Cadena de conexión a MongoDB (MongoDB Atlas o Docker local)
• Clave de la API de Finnhub
• Cuenta de Gmail (para enviar correos electrónicos)
• Opcional: clave de la API de Google Gemini (para generación de contenido con IA)

Pasos de instalación

1. Clonar el repositorio

git clone https://github.com/Open-Dev-Society/OpenStock.git
cd OpenStock

2. Instalar dependencias

pnpm install
# o
npm install

3. Configurar variables de entorno

Crear un archivo .env:

# Configuración básica
NODE_ENV=development

# Base de datos
MONGODB_URI=tu_cadena_de_conexión_a_mongodb

# Better Auth
BETTER_AUTH_SECRET=tu_secreto_de_better_auth
BETTER_AUTH_URL=http://localhost:3000

# Finnhub
FINNHUB_API_KEY=tu_clave_de_finnhub
NEXT_PUBLIC_FINNHUB_API_KEY=
FINNHUB_BASE_URL=https://finnhub.io/api/v1

# IA de Inngest (Gemini)
GEMINI_API_KEY=tu_clave_de_gemini

# Configuración de correo
NODEMAILER_EMAIL=tu_correo@gmail.com
NODEMAILER_PASSWORD=tu_contraseña_de_aplicación_de_gmail

4. Verificar la conexión a la base de datos

pnpm test:db

5. Iniciar el servidor de desarrollo

pnpm dev

6. Iniciar Inngest (para flujos de trabajo y tareas programadas)

npx inngest-cli@latest dev

7. Acceder a la aplicación

Abrir en el navegador http://localhost:3000

Despliegue con Docker

El proyecto incluye una configuración de Docker Compose para iniciar rápidamente la aplicación y MongoDB:

# Iniciar MongoDB
docker compose up -d mongodb

# Construir e iniciar la aplicación
docker compose up -d --build

Al usar Docker, la cadena de conexión a MongoDB debería ser:

MONGODB_URI=mongodb://root:example@mongodb:27017/openstock?authSource=admin

Datos e integraciones

API de Finnhub

• Proporciona búsqueda de acciones, perfiles empresariales y noticias del mercado
• La versión gratuita puede devolver cotizaciones con retraso
• Se deben respetar los límites de frecuencia

TradingView

• Ofrece widgets embebibles de gráficos, mapas de calor y cotizaciones
• Imágenes externas provienen de i.ibb.co

Better Auth + MongoDB

• Autenticación por correo electrónico/contraseña
• Adaptador de MongoDB para almacenamiento de sesiones
• La mayoría de las rutas están protegidas, excepto las páginas de inicio de sesión y registro

Flujos de trabajo de Inngest

• Evento de creación de usuario → Correo de bienvenida personalizado con IA
• Tarea programada (diariamente a las 12:00) → Envío de resumen de noticias
• En desarrollo local se utiliza npx inngest-cli@latest dev

Envío de correos (Nodemailer)

• Usa Gmail como servicio de transporte
• Incluye plantillas para correos de bienvenida y resúmenes de noticias
• Se recomienda utilizar un servicio SMTP profesional en producción

Scripts disponibles

• pnpm dev – Inicia el servidor de desarrollo (Turbopack)
• pnpm build – Construye para entorno de producción
• pnpm start – Inicia el servidor en producción
• pnpm lint – Ejecuta ESLint
• pnpm test:db – Verifica la conexión a la base de datos

Experiencia para desarrolladores

• Modo estricto de TypeScript
• Tailwind CSS v4 (sin necesidad de archivo de configuración adicional)
• Biblioteca de componentes shadcn/ui
• Panel de comandos cmdk
• Cambio de tema con next-themes
• Iconos lucide-react

Manifiesto de Open Dev Society

Vivimos en un mundo donde el conocimiento está oculto tras muros de pago, las herramientas están encerradas en suscripciones, la información se distorsiona por sesgos y a los principiantes se les dice que "no son lo suficientemente buenos" para construir.

Nuestras creencias:

• La tecnología debe pertenecer a todos
• El conocimiento debe ser abierto, gratuito y accesible
• La comunidad debe dar la bienvenida a los principiantes con confianza, no con barreras

Nuestra misión:

• Crear proyectos de código abierto verdaderamente útiles y gratuitos
• Herramientas accesibles sin obstáculos tanto para profesionales como para estudiantes
• Plataformas de conocimiento donde aprender siempre sea gratis
• Comunidades que guíen, no juzguen, a los principiantes
• Recursos que funcionen con base en la confianza, no en beneficios económicos

Nuestro compromiso:

• Nunca encerrar conocimiento
• Nunca cobrar por el acceso
• Nunca intercambiar confianza por dinero
• Operar con transparencia, donaciones y el poder de la comunidad

Guía de contribución

¡Todas las contribuciones son bienvenidas! Ya seas estudiante, desarrollador autodidacta o ingeniero experimentado:

• Discute ideas y errores mediante Issues
• Busca problemas etiquetados como "good first issue" o "help wanted"
• Mantén tus PR enfocados; incluye capturas de pantalla para cambios en la interfaz
• Sé amable, guía a los principiantes y rechaza las barreras: así es como actúa ODS

Seguridad

Si descubres una vulnerabilidad de seguridad:

• No publiques un Issue público
• Envía un correo a: opendevsociety@cc.cc
• Coordinaremos una divulgación responsable y aplicaremos parches rápidamente

Licencia

OpenStock se distribuye bajo la licencia AGPL-3.0. Si modificas, redistribuyes o despliegas este software (incluido como servicio web), debes publicar tu código fuente bajo la misma licencia y reconocer al autor original.

Agradecimientos

• Finnhub – Por proporcionar datos de mercado accesibles
• TradingView – Por los widgets embebibles del mercado
• Comunidades de shadcn/ui, Radix UI, Tailwind CSS y Next.js
• Inngest – Por tareas en segundo plano y flujos de trabajo fiables
• Better Auth – Por una autenticación sencilla y segura
• Todos los colaboradores que hacen posible estas herramientas de código abierto

Un agradecimiento especial a Adrian Hajdin (JavaScript Mastery), cuyo excelente tutorial sobre aplicaciones de mercado de valores ayudó significativamente a Open Dev Society en la construcción de OpenStock.

Construido en apertura, para todos, siempre gratuito. — Open Dev Society

Repositorio del proyecto: https://github.com/Open-Dev-Society/OpenStock