Files
HoruxStrategyKimi/docs/plans/2026-01-31-horux-strategy-design.md
HORUX360 c1321c3f0c Initial commit: Horux Strategy project setup
- Add project design document with complete specifications
- Configure Turborepo monorepo structure
- Add README with project overview and setup instructions
- Configure .gitignore for Node.js/TypeScript project
- Set up pnpm workspace configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 09:50:44 +00:00

26 KiB
Raw Permalink Blame History

Horux Strategy - Documento de Diseño

Versión: 1.0 Fecha: 31 de Enero, 2026 Autor: HORUX360 Estado: Aprobado para implementación


Tabla de Contenidos

  1. Resumen Ejecutivo
  2. Decisiones de Producto
  3. Arquitectura General
  4. Métricas y KPIs
  5. Pipeline de Reportes con IA
  6. Integraciones
  7. Estructura de Base de Datos
  8. Planes y Pricing
  9. Flujos de Usuario
  10. Roadmap de Implementación

1. Resumen Ejecutivo

1.1 Visión del Producto

Horux Strategy es una plataforma SaaS de inteligencia financiera que transforma datos fiscales y contables en insights estratégicos accionables. Combina dashboards en tiempo real con reportes ejecutivos generados por IA, posicionándose como el "CFO Digital" para empresas mexicanas.

1.2 Propuesta de Valor

  • 50% más económico que Monthly.la (competidor principal)
  • Automatización completa: Conexión directa con SAT y 5 sistemas contables
  • Dashboards en tiempo real + Reportes ejecutivos con IA
  • +50 métricas financieras organizadas en módulos (Core, Startup, Enterprise)
  • Plataforma modular que se adapta a PYMES, startups y empresas medianas

1.3 Diferenciadores Clave

Aspecto Monthly.la Horux Strategy
Precio $11,999 - $19,999/mes $5,999 - $9,999/mes
Dashboards No (solo reportes) Sí, tiempo real
Integraciones Manual Automáticas (5 sistemas)
Frecuencia reportes Mensual Bajo demanda
Alertas No Sí, automáticas
API No Sí (planes Pro+)

2. Decisiones de Producto

2.1 Resumen de Decisiones

Aspecto Decisión
Público objetivo Modular: PYMES, startups, empresas medianas
Fuentes de datos SAT (FIEL) + Sistemas contables (5)
Core value Dashboards live + Reportes ejecutivos con IA
Relación con Horux360 Productos completamente separados
Modelo de pricing Suscripción mensual por tamaño de empresa
Stack tecnológico Next.js 14 + Express + PostgreSQL + Turborepo
IA DeepSeek API
Timeline Máxima velocidad (16 semanas)

2.2 Público Objetivo

Segmento 1: PYMES Tradicionales

  • Restaurantes, comercios, servicios
  • Necesitan visibilidad básica de flujo de caja y rentabilidad
  • Buscan evitar sorpresas fiscales

Segmento 2: Startups con Inversionistas

  • Empresas tecnológicas en crecimiento
  • Necesitan métricas de crecimiento (MRR, CAC, LTV, runway)
  • Reportes para inversionistas

Segmento 3: Empresas Medianas

  • Operaciones establecidas
  • Necesitan estados financieros completos, presupuestos, comparativos
  • Reportes para junta directiva

3. Arquitectura General

3.1 Diagrama de Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      HORUX STRATEGY                              │
├─────────────────────────────────────────────────────────────────┤
│  FRONTEND (Next.js 14)                                          │
│  ├── Dashboard Hub (métricas en tiempo real)                    │
│  ├── Centro de Reportes (generación y descarga)                 │
│  ├── Configuración de Empresa                                   │
│  └── Gestión de Integraciones                                   │
├─────────────────────────────────────────────────────────────────┤
│  BACKEND (Express + TypeScript)                                 │
│  ├── Auth Service (JWT + roles)                                 │
│  ├── Integration Service (SAT, contables)                       │
│  ├── Analytics Engine (cálculo de métricas)                     │
│  ├── Report Generator (plantillas + IA)                         │
│  └── Scheduler (sync automático, alertas)                       │
├─────────────────────────────────────────────────────────────────┤
│  DATA LAYER                                                     │
│  ├── PostgreSQL (multi-tenant por schema)                       │
│  ├── Redis (cache de métricas, colas)                           │
│  └── S3/MinIO (reportes PDF generados)                          │
├─────────────────────────────────────────────────────────────────┤
│  INTEGRACIONES EXTERNAS                                         │
│  ├── SAT (descarga CFDI vía FIEL)                              │
│  ├── Sistemas Contables (CONTPAQi, Aspel, Odoo, Alegra, SAP)   │
│  └── DeepSeek API (generación narrativa)                        │
└─────────────────────────────────────────────────────────────────┘

3.2 Stack Tecnológico

Componente Tecnología
Frontend Next.js 14, TypeScript, Tailwind CSS, Zustand
Backend Node.js, Express, TypeScript
Base de datos PostgreSQL (multi-tenant por schema)
Cache/Colas Redis, BullMQ
Storage MinIO / AWS S3
Monorepo Turborepo + pnpm
Contenedores Docker Compose
IA DeepSeek API
Gráficas Recharts (frontend), Chart.js (server-side)
PDF Puppeteer

3.3 Arquitectura Multi-tenant

  • Estrategia: Schema por tenant en PostgreSQL
  • Beneficios:
    • Aislamiento de datos garantizado a nivel BD
    • Facilita backups y restauración por cliente
    • Performance consistente
    • Cumplimiento de privacidad

4. Métricas y KPIs

4.1 Módulo Core (Todos los planes)

Métrica Fuente Requisitos Usuario Cálculo
Ingresos totales SAT Conectar FIEL Σ CFDIs emitidos tipo "I"
Gastos totales SAT Conectar FIEL Σ CFDIs recibidos
Utilidad bruta SAT Clasificar costos Ingresos - Costo de ventas
Utilidad neta SAT + Contable Clasificar gastos Utilidad bruta - Gastos - Impuestos
Flujo de caja SAT Ninguno Complementos de pago recibidos - pagados
Cuentas por cobrar SAT Ninguno Facturas emitidas sin pago
Cuentas por pagar SAT Ninguno Facturas recibidas sin pago
Antigüedad CxC SAT Ninguno Días desde emisión, agrupado 0-30, 31-60, 61-90, 90+
Antigüedad CxP SAT Ninguno Días desde recepción sin pago
IVA por pagar SAT Ninguno IVA trasladado - IVA acreditable
IVA a favor SAT Ninguno Cuando acreditable > trasladado

4.2 Módulo Startup (Plan PYME+)

Métrica Fuente Requisitos Usuario Cálculo
MRR SAT + Config Marcar clientes recurrentes Σ ingresos recurrentes mensuales
ARR Derivado Igual que MRR MRR × 12
Runway SAT + Config Ingresar saldo bancario Saldo ÷ Burn rate
Burn rate SAT Ninguno Promedio (Gastos - Ingresos) mensual
Net Burn SAT Ninguno Gastos - Ingresos mensual
Gross Burn SAT Ninguno Solo gastos mensuales
CAC Config Gasto marketing + clientes nuevos Gasto MKT ÷ Clientes nuevos
LTV SAT + Config Marcar recurrentes + histórico (ARPU × Margen) ÷ Churn
Churn rate Config Registrar clientes activos/cancelados Perdidos ÷ Inicio período
Growth rate MoM SAT Ninguno (Actual - Anterior) ÷ Anterior
Growth rate YoY SAT Ninguno (Año actual - Año anterior) ÷ Año anterior
LTV:CAC Ratio Derivado Igual que LTV y CAC LTV ÷ CAC
Months to recover CAC Derivado Igual que CAC CAC ÷ (ARPU × Margen)

4.3 Módulo Enterprise (Plan Enterprise+)

Métrica Fuente Requisitos Usuario Cálculo
EBITDA Contable Conectar sistema contable Utilidad + Depreciación + Amortización
Margen EBITDA Derivado Igual que EBITDA EBITDA ÷ Ingresos
ROI Contable + Config Ingresar inversión (Ganancia - Inversión) ÷ Inversión
ROE Contable Conectar contable Utilidad neta ÷ Capital contable
ROA Contable Conectar contable Utilidad neta ÷ Activos totales
Razón corriente Contable Conectar contable Activos circulantes ÷ Pasivos circulantes
Prueba ácida Contable Conectar contable (AC - Inventarios) ÷ PC
Endeudamiento Contable Conectar contable Pasivos ÷ Activos
Apalancamiento Contable Conectar contable Pasivos ÷ Capital
Punto equilibrio SAT + Config Clasificar costos fijos/variables Fijos ÷ (1 - Variables/Ventas)
Margen contribución SAT + Config Clasificar variables Ventas - Costos variables
Presupuesto vs Real Config Cargar presupuesto Variación absoluta y %
Forecast SAT + IA Histórico 6+ meses Proyección estadística + IA
Working capital Contable Conectar contable AC - PC
DSO SAT Ninguno (CxC ÷ Ventas crédito) × Días
DPO SAT Ninguno (CxP ÷ Compras crédito) × Días
Cash Conversion Cycle Derivado Ninguno DSO + Days Inventory - DPO

5. Pipeline de Reportes con IA

5.1 Tipos de Reportes

Reporte Frecuencia Audiencia Contenido
Ejecutivo Mensual Mensual CEO/Dueño Resumen, tendencias, alertas, recomendaciones
Para Inversionistas Mensual/Trimestral Inversionistas Métricas startup, runway, crecimiento
Junta Directiva Trimestral Consejo Análisis profundo, comparativos, proyecciones
Flash Semanal Semanal Operaciones KPIs clave, alertas urgentes
Fiscal Mensual Contador/CFO IVA, retenciones, cumplimiento

5.2 Pipeline de Generación (10 Fases)

FASE 1: Trigger y Scheduling

  • Disparadores: Cron, manual, evento, fecha programada
  • Cola de trabajos con BullMQ
  • Prioridades y reintentos

FASE 2: Extracción de Datos

  • Datos del período actual
  • Datos históricos (YoY, MoM)
  • Contexto del cliente (industria, tamaño, metas)
  • Datos del sistema contable

FASE 3: Cálculo de Métricas

  • Ejecutar fórmulas de métricas
  • Calcular variaciones
  • Detectar anomalías (reglas)
  • Clasificar insights (positivo, neutral, negativo)

FASE 4: Preparación de Contexto para IA

  • Construcción de JSON estructurado
  • Selección de plantilla de prompt
  • Personalización por tipo de reporte

FASE 5: Llamadas a DeepSeek API

  • Llamadas paralelas por sección
  • Configuración: temperature=0.3, max_tokens variable
  • Manejo de errores y fallbacks
  • Validación de respuestas (anti-alucinación)

FASE 6: Generación de Visualizaciones

  • Gráficas con Chart.js server-side
  • Output PNG/SVG para PDF
  • Temas consistentes con branding

FASE 7: Composición del Documento

  • Motor de plantillas (Puppeteer HTML→PDF)
  • Inyección de textos, métricas, gráficas
  • Formatos: PDF, Excel, PowerPoint

FASE 8: Post-procesamiento y Calidad

  • Validación del PDF
  • Detección de alucinaciones (segunda capa)
  • Scoring de calidad

FASE 9: Almacenamiento y Entrega

  • Storage en S3/MinIO
  • Email automático
  • Notificación in-app
  • Link de descarga

FASE 10: Feedback y Mejora Continua

  • Rating del reporte
  • Feedback por sección
  • Mejora de prompts
  • Analytics del sistema

5.3 Estructura del Reporte Ejecutivo

┌─────────────────────────────────────────────────────────────┐
│  HORUX STRATEGY - Reporte Ejecutivo                         │
│  [Nombre Empresa] | [Mes Año]                               │
├─────────────────────────────────────────────────────────────┤
│  📊 RESUMEN EJECUTIVO (IA)                                  │
│  [Narrativa generada con insights principales]              │
├─────────────────────────────────────────────────────────────┤
│  💰 RESULTADOS DEL MES                                      │
│  [KPIs principales con variaciones]                         │
├─────────────────────────────────────────────────────────────┤
│  📈 GRÁFICAS                                                │
│  [Visualizaciones de tendencias y composición]              │
├─────────────────────────────────────────────────────────────┤
│  ⚠️ ALERTAS Y RIESGOS (IA)                                 │
│  [Problemas detectados automáticamente]                     │
├─────────────────────────────────────────────────────────────┤
│  💡 RECOMENDACIONES (IA)                                    │
│  [Acciones sugeridas basadas en datos]                      │
├─────────────────────────────────────────────────────────────┤
│  📅 PRÓXIMO MES - QUÉ ESPERAR                              │
│  [Proyecciones y eventos importantes]                       │
└─────────────────────────────────────────────────────────────┘

6. Integraciones

6.1 SAT (Solo FIEL)

Autenticación: Exclusivamente e.firma (FIEL)

  • Archivos: .cer + .key + contraseña
  • Contraseña NO se almacena
  • .key encriptado con AES-256

Seguridad:

  • Validar vigencia del certificado
  • Verificar que no esté revocado
  • Alertar 30 días antes de expiración

Sincronización:

  • Inicial: últimos 12-72 meses
  • Incremental: cada 2-8 horas (según plan)
  • Delta: solo CFDIs nuevos

6.2 Sistemas Contables

Sistema Método de Conexión Datos
CONTPAQi SDK/BD directa + Agente Windows Catálogo, pólizas, balanza, auxiliares
Aspel Firebird/SQL Server + Agente COI, SAE, balanza, CxC/CxP
Odoo API XML-RPC/JSON-RPC Cuentas, moves, payments, partners
Alegra API REST (OAuth 2.0) Invoices, bills, payments, contacts
SAP B1 Service Layer REST API Chart of accounts, journals, invoices

6.3 Agente Local (Horux Sync Agent)

Para CONTPAQi y Aspel on-premise:

  • Instalador Windows (.msi)
  • Servicio Windows auto-inicio
  • Comunicación siempre saliente (no requiere abrir puertos)
  • Datos encriptados en tránsito y reposo
  • Auto-actualización

6.4 Arquitectura de Conectores

┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ Conector        │    │   Adapter        │    │   Modelo         │
│ (por sistema)   │───▶│   (normaliza)    │───▶│   Unificado      │
└─────────────────┘    └──────────────────┘    └──────────────────┘

Interfaz común: IConnector

  • validateCredentials()
  • testConnection()
  • getAccounts(), getTransactions(), getJournalEntries()
  • syncIncremental(), syncFull()

7. Estructura de Base de Datos

7.1 Schema Public (Compartido)

Tablas principales:

  • tenants - Empresas registradas
  • users - Usuarios de la plataforma
  • user_sessions - Sesiones activas
  • plans - Planes de suscripción
  • subscriptions - Relación tenant-plan
  • subscription_history - Historial de cambios
  • payment_methods - Métodos de pago
  • invoices - Facturas de cobro
  • audit_log - Log de auditoría global
  • background_jobs - Jobs en cola
  • api_keys - Llaves de API
  • webhooks - Webhooks configurados
  • feature_flags - Feature flags

7.2 Schema Tenant (Por Empresa)

Tablas de datos fiscales:

  • sat_credentials - Credenciales FIEL encriptadas
  • sat_sync_history - Historial de sincronizaciones
  • cfdis - Comprobantes fiscales
  • complementos_pago - Complementos de pago
  • documentos_pagados - Relación pago-CFDI

Tablas de datos financieros:

  • transactions - Modelo unificado de transacciones
  • payments - Pagos registrados
  • contacts - Clientes y proveedores
  • accounts - Cuentas contables
  • journal_entries - Pólizas contables
  • journal_entry_lines - Movimientos de pólizas
  • categories - Categorías de clasificación
  • cost_centers - Centros de costo
  • projects - Proyectos
  • bank_accounts - Cuentas bancarias
  • bank_transactions - Movimientos bancarios

Tablas de análisis:

  • metrics_cache - Métricas precalculadas
  • metrics_history - Historial para tendencias
  • goals - Metas y objetivos
  • alerts - Alertas generadas
  • alert_rules - Reglas de alertas
  • budgets - Presupuestos
  • budget_lines - Líneas de presupuesto
  • recurring_revenue_config - Configuración MRR

Tablas de reportes:

  • reports - Reportes generados
  • report_schedules - Reportes programados
  • report_feedback - Feedback de reportes

Tablas de configuración:

  • integration_configs - Configuración de integraciones
  • integration_sync_history - Historial de sync
  • settings - Configuración general
  • categorization_rules - Reglas de categorización
  • dashboard_configs - Configuración de dashboards

Tablas auxiliares:

  • attachments - Archivos adjuntos
  • notes - Notas y comentarios
  • activity_log - Actividad del usuario
  • user_notifications - Notificaciones
  • exports - Exportaciones

8. Planes y Pricing

8.1 Estructura de Precios

Plan Precio Mensual Precio Anual Ingresos Anuales
STARTUP $5,999 MXN $59,990 MXN < $100M MXN
PYME $6,499 MXN $64,990 MXN < $400M MXN
ENTERPRISE $8,499 MXN $84,990 MXN < $1,000M MXN
CORPORATIVO $9,999 MXN $99,990 MXN > $1,000M MXN

Comparativa con Monthly.la (50% más económico):

  • Monthly.la Pequeña: $11,999 → Horux: $5,999
  • Monthly.la Mediana: $12,999 → Horux: $6,499
  • Monthly.la Grande: $16,999 → Horux: $8,499
  • Monthly.la Extra: $19,999 → Horux: $9,999

8.2 Features por Plan

Feature STARTUP PYME ENTERPRISE CORPORATIVO
Usuarios incluidos 3 5 10 Ilimitados
RFCs conectados 1 2 5 10
SAT (FIEL)
CONTPAQi/Aspel
Odoo/Alegra
SAP Business One
Métricas totales +40 +50 +50 +50
Módulo Core
Módulo Startup
Módulo Enterprise
Reportes/mes 5 15 30 Ilimitados
Historial datos 24 meses 36 meses 60 meses Ilimitado
API Lectura Completa Completa
Soporte Email Chat Prioritario Dedicado

8.3 Trial

  • Duración: 14 días
  • Acceso: Plan PYME completo
  • Tarjeta: No requerida
  • Ofertas conversión: 17% descuento anual, 20% primeros 3 meses

9. Flujos de Usuario

9.1 Mapa de Navegación

SIDEBAR:
├── 🏠 Dashboard
├── 📊 Métricas (Core, Startup, Enterprise)
├── 📄 Reportes (Generar, Historial, Programados)
├── 💰 Transacciones (Ingresos, Gastos, CxC, CxP)
├── 🧾 CFDIs (Emitidos, Recibidos, Complementos)
├── 👥 Contactos (Clientes, Proveedores)
├── 🔗 Integraciones (SAT, Contables)
├── 🔔 Alertas
├── 📈 Presupuestos
└── ⚙️ Configuración

9.2 Flujo de Onboarding

  1. Registro: Email + contraseña o OAuth
  2. Información empresa: RFC, industria, tamaño, ingresos
  3. Conectar SAT: Upload FIEL (.cer, .key, contraseña)
  4. Sincronización: Descarga automática de CFDIs
  5. Sistema contable (opcional): Seleccionar y configurar
  6. ¡Listo!: Dashboard con métricas

9.3 Pantallas Principales

  • Dashboard: KPIs, gráficas, alertas, acciones rápidas
  • Métricas: Tabs por módulo, gráficas de tendencia, detalles
  • Generar Reporte: Selección tipo, período, opciones, generación
  • Transacciones: Lista filtrable, detalles, categorización
  • CFDIs: Lista, búsqueda, XML, complementos de pago
  • Integraciones: Estado de conexiones, configuración, sync manual

10. Roadmap de Implementación

10.1 Resumen de Fases

Fase Nombre Duración Equipos
1 Foundation 2 semanas 3
2 Core MVP 4 semanas 4
3 Integraciones 4 semanas 5
4 IA y Reportes 3 semanas 3
5 Scale & Polish 3 semanas 4
Total 16 semanas

10.2 Fase 1: Foundation (Semanas 1-2)

Equipo A: Infraestructura

  • Setup monorepo Turborepo
  • Configurar PostgreSQL, Redis, MinIO
  • Docker Compose dev
  • CI/CD pipeline básico

Equipo B: Auth & Tenants

  • Sistema JWT + refresh tokens
  • Registro, login, reset password
  • Multi-tenant middleware
  • Creación schemas tenant

Equipo C: Frontend Base

  • Setup Next.js 14
  • Tailwind + componentes UI
  • Layout principal
  • Sistema de rutas

Entregables:

  • Repo configurado y funcionando
  • Auth completo con multi-tenant
  • Usuario puede registrarse y ver dashboard vacío

10.3 Fase 2: Core MVP (Semanas 3-6)

Equipo A: Integración SAT

  • Upload y validación FIEL
  • Conexión Web Service SAT
  • Descarga masiva CFDIs
  • Parser XML, sync incremental

Equipo B: Motor de Métricas

  • Modelo de transacciones
  • Cálculo métricas Core
  • Cache de métricas
  • API endpoints

Equipo C: Dashboard Frontend

  • Dashboard principal
  • KPI cards, gráficas
  • Selector período, comparativos

Equipo D: Gestión de Datos

  • CRUD Contactos, Categorías
  • Vista transacciones, CFDIs
  • Filtros, búsqueda, exportar

Entregables:

  • Usuario conecta SAT con FIEL
  • CFDIs se descargan automáticamente
  • Dashboard muestra métricas Core

10.4 Fase 3: Integraciones (Semanas 7-10)

5 equipos paralelos:

  • Equipo A: CONTPAQi (SDK + Agente)
  • Equipo B: Aspel (Firebird + Agente)
  • Equipo C: Odoo (XML-RPC)
  • Equipo D: Alegra (REST API)
  • Equipo E: SAP B1 + Métricas avanzadas

Entregables:

  • 5 integraciones contables funcionando
  • Agente local disponible
  • Todas las métricas (+50) calculándose

10.5 Fase 4: IA y Reportes (Semanas 11-13)

Equipo A: Pipeline IA

  • Integración DeepSeek API
  • Construcción de contexto
  • Prompt templates
  • Validación respuestas

Equipo B: Generación Reportes

  • Motor gráficas server-side
  • Plantillas HTML/PDF
  • Generación Excel, PowerPoint
  • Job queue async

Equipo C: UI Reportes + Alertas

  • Pantalla generar reporte
  • Historial, visor PDF
  • Sistema de alertas
  • Centro notificaciones

Entregables:

  • Reportes ejecutivos con IA
  • 5 tipos de reportes
  • Sistema de alertas funcionando

10.6 Fase 5: Scale & Polish (Semanas 14-16)

Equipo A: Billing & Plans

  • Integración Stripe/Conekta
  • Planes y precios
  • Trial, upgrade/downgrade
  • Facturación CFDI

Equipo B: Admin & Settings

  • Gestión usuarios, roles
  • Multi-RFC, presupuestos
  • Reportes programados

Equipo C: API & Webhooks

  • API REST documentada
  • API keys, rate limiting
  • Webhooks salientes

Equipo D: QA & Launch

  • Testing E2E
  • Performance, security
  • Bug fixes, landing page
  • Deploy producción

Entregables:

  • Sistema de pagos funcionando
  • API documentada
  • Plataforma lista para producción

10.7 Hitos Clave

Semana Hito
2 Auth + Multi-tenant funcionando
6 MVP con SAT + Dashboard + Métricas Core
10 5 integraciones + Métricas completas
13 Reportes con IA + Alertas
16 LAUNCH - Plataforma en producción

10.8 Recursos Estimados

  • 4-5 desarrolladores full-stack
  • 1 diseñador UI/UX (parcial)
  • 1 QA engineer (desde semana 10)
  • Claude Code como multiagente para acelerar

10.9 Dependencias Externas

  • API DeepSeek (cuenta y créditos)
  • Procesador de pagos (Stripe/Conekta)
  • Acceso APIs sistemas contables para testing
  • Servidor Windows para agente (desarrollo)

Apéndices

A. Glosario

Término Definición
CFDI Comprobante Fiscal Digital por Internet
FIEL Firma Electrónica Avanzada (e.firma del SAT)
MRR Monthly Recurring Revenue
ARR Annual Recurring Revenue
CAC Customer Acquisition Cost
LTV Lifetime Value
EBITDA Earnings Before Interest, Taxes, Depreciation, Amortization
CxC Cuentas por Cobrar
CxP Cuentas por Pagar

B. Referencias


Documento aprobado para implementación

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com