Skip to content

PabloClevesFX/logbook-trading

BranchesTags

Repository files navigation

Bitácora Ultimate Trading

Node.js Next.js License: MIT PRs Welcome Version

Tu bitácora de trading, open source y bajo tu control.

Aplicación web para registrar operaciones, medir tu rendimiento con métricas reales y mejorar tu disciplina con análisis impulsado por IA. Pensada para traders que quieren claridad — y para developers que quieren contribuir a una herramienta seria.

Demo / producto en producción: cleveshubfx.com
Tutorial de uso: Ver en YouTube
Contacto / soporte: Telegram @PabloClevesFX

Tabla de contenidos

Para traders — Funcionalidades

Bitácora Ultimate te ayuda a dejar de operar “a ciegas” y a construir un historial accionable:

Área Qué puedes hacer
Registro de operaciones Anota entradas, salidas, SL/TP, confirmaciones y reflexiones por operación
Métricas clave Win Rate, Risk/Reward Ratio (RRR), efectividad, efectividad vs eficiencia y más
Multi-mercado Soporte para Forex, metales, índices y cripto (incl. calculadora de tamaño de lote)
Análisis con IA Maestro Ultimate con Google Gemini: diagnóstico, próximos pasos y puntos a mantener
Dashboard Visualiza rendimiento, capital y filtros para entender tu edge
Multi-bitácora Separa cuentas, estrategias o etapas (demo / real / backtest)
Compartir Genera enlaces de bitácora compartida cuando quieras mostrar tu process
Suscripción y planes Flujo de trial / planes listo para auto-hospedar o adaptar a tu negocio

Ideal si eres trader que quiere autogestionar su journal, o un equipo que busca un base sólida open source para personalizar.

Tutorial de uso

¿Prefieres verlo en acción? Aquí tienes el tutorial completo: dashboard, registro de operaciones, métricas y flujo general de la bitácora.

▶ Ver tutorial en YouTube

Tutorial Bitácora Ultimate Trading

Haz clic en la miniatura o en el enlace para abrir el video.

Privacidad y seguridad

Al ejecutar el proyecto en tu máquina (o en tu propio hosting), tus datos financieros te pertenecen: viven en tu instancia de MongoDB (Atlas o local). No dependes de un tercero para el almacenamiento de tu journal.

Buenas prácticas incluidas / recomendadas:

  • Secretos solo en .env.local (nunca en el repositorio)
  • Contraseñas hasheadas (bcrypt) y sesiones firmadas con JWT_SECRET
  • APIs de terceros (Gemini, tasas de cambio, email) se invocan desde el servidor, no desde el navegador con la key expuesta

Si despliegas en nube, eres responsable de proteger tu URI de Mongo, rotar keys y restringir el Network Access del cluster.

Stack tecnológico

Capa Tecnología
Framework Next.js 16 (App Router) + React 19
Lenguaje TypeScript
Estilos Tailwind CSS 4
Base de datos MongoDB + Mongoose
Auth JWT (jsonwebtoken) + bcrypt — no usamos NextAuth; fácil de adaptar si lo prefieres
IA Google Gemini (@google/generative-ai)
Gráficos Chart.js + react-chartjs-2
Email Nodemailer (Gmail App Password)
UI Headless UI, Lucide, next-themes

¿Quieres cambiar algo del stack? Edita esta tabla y sigue siendo bienvenido a proponer mejoras vía PR.

Estructura del proyecto

logbook-trading/
├── public/                 # Assets estáticos (imágenes, robots.txt, etc.)
├── src/
│   ├── app/                # App Router (páginas + layouts)
│   │   └── api/            # Route Handlers (REST)
│   │       ├── auth/       # Login, register, reset password…
│   │       ├── logbooks/   # Bitácoras
│   │       ├── operations/ # Operaciones
│   │       ├── gemini/     # Análisis con IA
│   │       ├── admin/      # Panel administrativo
│   │       └── …           # exchange-rate, share, sync, etc.
│   ├── components/         # UI (Dashboard, Operations, Maestro…)
│   ├── hooks/              # Hooks de React (auth, suscripción…)
│   ├── middleware/         # Auth JWT (requireAuth, generateJWT)
│   ├── models/             # Esquemas Mongoose
│   ├── services/           # Lógica de negocio / acceso a datos
│   ├── lib/ & libs/        # Utilidades (auth-check, mongodb…)
│   ├── constants/          # Constantes de dominio
│   ├── types/              # Tipos TypeScript
│   └── utils/              # Helpers
├── scripts/                # Scripts auxiliares
├── .env.local              # Tus secretos (NO se sube a Git)
├── package.json
└── README.md

Requisitos

  • Node.js 18 o superior (recomendado LTS)
  • npm (incluido con Node.js)
  • Cuenta en MongoDB Atlas (o MongoDB local)
  • Las API keys descritas más abajo

Instalación en local

1. Clonar el repositorio

git clone https://github.com/PabloClevesFX/logbook-trading.git
cd logbook-trading

2. Instalar dependencias

npm install

3. Crear el archivo de entorno

Crea un archivo .env.local en la raíz del proyecto (al mismo nivel que package.json).

Importante: nunca subas .env.local a Git. Ya está ignorado en .gitignore.

Copia esta plantilla y rellénala con tus valores:

MONGODB_URI=
APIKEY_CALCULATOR=
APIKEY_GEMINI=
NEXT_PUBLIC_APP_URL=http://localhost:3000
GMAIL_APP_PASSWORD=
NOTIFY_FROM_EMAIL=
JWT_SECRET=
NEXT_PUBLIC_GA_MEASUREMENT_ID=
NEXT_PUBLIC_GTM_ID=

4. Arrancar en desarrollo

npm run dev

Abre http://localhost:3000 en el navegador.

Otros comandos

npm run build   # Compilar para producción
npm start       # Servir el build de producción
npm run lint    # Linter

Variables de entorno

Obligatorias (para que la app funcione)

Variable Para qué sirve Dónde y cómo obtenerla
MONGODB_URI Conexión a la base de datos (usuarios, bitácoras, operaciones) 1. Entra a MongoDB Atlas
2. Crea un cluster (gratis con el plan M0)
3. Database Access: crea un usuario y contraseña
4. Network Access: permite tu IP (o 0.0.0.0/0 solo para pruebas)
5. Connect → Drivers y copia la URI:
mongodb+srv://USER:PASS@cluster.../nombreDB?retryWrites=true&w=majority
APIKEY_CALCULATOR Tasas de cambio (calculadora / divisas) vía exchangerate.host 1. Regístrate en APILayer – Exchange Rates Data o el portal de exchangerate.host
2. Crea una API key gratuita
3. Pégala en esta variable
APIKEY_GEMINI Análisis con IA (Google Gemini) 1. Ve a Google AI Studio
2. Inicia sesión con tu cuenta de Google
3. Crea una API key
4. Pégala aquí
NEXT_PUBLIC_APP_URL URL pública de la app (enlaces de verificación de email, reset de contraseña, etc.) En local usa http://localhost:3000
En producción: la URL de tu dominio (ej. https://tudominio.com)
GMAIL_APP_PASSWORD Envío de emails (registro, verificación, recuperación de contraseña) con Nodemailer + Gmail 1. Usa una cuenta Gmail
2. Activa la verificación en 2 pasos
3. En Contraseñas de aplicaciones crea una para “Correo” / “Otro”
4. Copia la contraseña de 16 caracteres (puedes quitar los espacios)
5. El email remitente debe ser el de esa cuenta Gmail (ver NOTIFY_FROM_EMAIL)
NOTIFY_FROM_EMAIL Dirección “From” de los correos El mismo Gmail con el que generaste GMAIL_APP_PASSWORD (ej. tunombre@gmail.com)
JWT_SECRET Firma de tokens de sesión (login / auth) Genera una cadena larga y aleatoria. Por ejemplo en terminal:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
No la compartas ni la reutilices entre proyectos públicos.

Opcionales (analíticas)

Variable Para qué sirve Dónde y cómo obtenerla
NEXT_PUBLIC_GA_MEASUREMENT_ID Google Analytics 4 1. Google Analytics
2. Crea una propiedad → flujo Web
3. Copia el Measurement ID (G-XXXXXXXX)
Si lo dejas vacío, la app funciona igual sin GA.
NEXT_PUBLIC_GTM_ID Google Tag Manager 1. Google Tag Manager
2. Crea un contenedor Web
3. Copia el ID (GTM-XXXXXXX)
Si lo dejas vacío, no se carga GTM.

Ejemplo de .env.local (solo plantilla)

MONGODB_URI=mongodb+srv://usuario:contraseña@tu-cluster.mongodb.net/bitacora?retryWrites=true&w=majority
APIKEY_CALCULATOR=tu_access_key_de_exchangerate
APIKEY_GEMINI=tu_api_key_de_google_ai_studio
NEXT_PUBLIC_APP_URL=http://localhost:3000
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx
NOTIFY_FROM_EMAIL=tunombre@gmail.com
JWT_SECRET=pega_aqui_el_string_aleatorio_generado
NEXT_PUBLIC_GA_MEASUREMENT_ID=
NEXT_PUBLIC_GTM_ID=

Notas útiles

  • Primera vez con MongoDB: tras conectar, la app crea las colecciones al usarse (registro, bitácoras, etc.).
  • Emails en local: necesitan GMAIL_APP_PASSWORD + NOTIFY_FROM_EMAIL + NEXT_PUBLIC_APP_URL. Sin eso, registro y recuperación de contraseña fallarán al enviar correo.
  • Gemini: sin APIKEY_GEMINI fallará el endpoint de análisis con IA.
  • Variables NEXT_PUBLIC_*: se exponen al navegador; no pongas secrets ahí.
  • Si cambias .env.local, reinicia npm run dev.

Despliegue y pruebas

Pruebas / calidad local

npm run lint    # ESLint (regla actual del proyecto)
npm run build   # Verifica que el proyecto compile

Hoy no hay un script test en package.json. Cuando se añadan tests (Jest / Vitest / Playwright, etc.), el comando típico será:

npm run test

PRs que añadan una suite de tests básica son muy bienvenidos.

Despliegue en Vercel (recomendado)

  1. Sube el repo a GitHub (si aún no está).
  2. Entra a Vercel → Import Project.
  3. Configura las mismas variables de .env.local en Project Settings → Environment Variables.
  4. En producción, NEXT_PUBLIC_APP_URL debe ser tu dominio real (HTTPS).
  5. Deploy. Vercel detecta Next.js automáticamente.

También puedes desplegar en cualquier host que soporte Node (Railway, Render, VPS con Docker, etc.): npm run build + npm start.

Guía de contribución

¡Las contribuciones mejoran la herramienta para toda la comunidad!

  1. Fork del repositorio en GitHub.

  2. Clona tu fork y crea una rama descriptiva:

    git checkout -b feature/mi-mejora
# o
git checkout -b fix/descripcion-del-bug

  3. Haz tus cambios, prueba en local (npm run lint / npm run build).

  4. Commit con mensaje claro (qué y por qué).

  5. Push a tu fork y abre un Pull Request hacia main (o la rama por defecto).

  6. Describe el problema, la solución y cómo lo probaste.

Ideas de contribución: tests, i18n, mejoras de UX trader, hardening de seguridad, integraciones de brokers.

Redes sociales

Sígueme para contenido de trading, disciplina y actualizaciones del proyecto:

Red Link
Telegram t.me/PabloClevesFX
TikTok @pabloclevesfx
YouTube @pabloclevesfx

Links de referidos

Si vas a abrir cuenta con un broker, prop firm o exchange, usar estos links no te cuesta más y me ayuda a seguir desarrollando Bitácora Ultimate en open source. ¡Gracias!

Plataforma Descripción Link
IC Markets Broker Abrir con mi referido
FTMO Prop firm / challenge Registrarse con mi afiliado
IC Funded Funding / productos Checkout con afiliado
Binance Exchange (CPA referral) Unirme con referido

Invítame un café

Este repo es gratis y open source. Si Bitácora Ultimate te está sirviendo para journalizar mejor, mantener la disciplina o construir tu propio setup…

invítame un café. ☕

Cada aporte — por pequeño que sea — paga servidores, APIs (Gemini, tasas de cambio), café de madrugada debuggeando y tiempo para seguir mejorando la herramienta para toda la comunidad.

Método Datos Notas
USDT (TRC20) TLe5PUizZ36MykPV9vBF8LVmP7oXmpfuWX Red TRC20 (Tron). Verifica siempre la red antes de enviar.
Bancolombia (Ahorros) Llave: @cleves87402 Transferencia por llave Bancolombia

Cualquier monto suma. No hay mínimo: un café, un almuerzo o lo que puedas. Si no puedes donar, compartir el repo o usar un link de referido también ayuda un montón.

¿Donaste? Mándame un mensaje por Telegram — me motiva saber que el proyecto le está sirviendo a alguien.

¿Necesitas ayuda?

Si algo no te cuadra al montarlo en local (Mongo, Gmail, Gemini, deploy, etc.), escríbeme por Telegram:

@PabloClevesFX

Licencia

Este proyecto se distribuye bajo la MIT License.

Puedes usarlo, modificarlo y redistribuirlo libremente — incluso en proyectos comerciales — siempre que incluyas el aviso de copyright y la licencia.

Hecho con disciplina de trader y código abierto.
¿Listo para journalizar mejor? → npm install · npm run dev · Telegram
¿Te gustó el repo? → Invítame un café · Redes · Referidos

About

A solid logbook for traders looking to level up their skills with a pile of solid, objective metrics.

logbook-trading.vercel.app

Topics

finance trading forex financial-data financial-analysis finantial finance-management

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages