Horux Despachos

Plataforma SaaS para despachos profesionales mexicanos. Gestión fiscal multi-RFC con roles jerárquicos (Owner/Supervisor/Auxiliar/Cliente), carteras de contribuyentes, y arquitectura BYO-DB.

Autor: Carlos e Ivan (Horux 360)

---

Qué es

Horux Despachos permite a despachos contables gestionar múltiples contribuyentes (RFCs) desde una sola cuenta. Cada contribuyente tiene su propia FIEL, CSD, y organización Facturapi. Los supervisores organizan contribuyentes en carteras y delegan trabajo a auxiliares.

Arquitectura

Monorepo (pnpm + Turborepo)
├── apps/api       → Express + TypeScript (puerto 4000)
├── apps/web       → Next.js 14 + App Router (puerto 3000)
└── packages/
    ├── core       → Auth (JWT), email transport, crypto (AES-256-GCM)
    ├── shared     → Tipos, constantes, interfaces compartidas
    ├── shared-ui  → Componentes UI (Button, Card, Dialog, selectors, hooks)
    └── vertical-contable → (scaffold) Lógica fiscal compartida

Funcionalidades implementadas

Gestión de despachos

• Signup multi-paso (formulario → vertical → plan)
• Onboarding wizard (6 pasos)
• Planes: Trial (30 días), Business Control (BYO-DB), Business Cloud (Managed)

Contribuyentes (RFCs)

• CRUD de contribuyentes por despacho
• FIEL per contribuyente (almacenada en BD tenant, cifrada AES-256-GCM)
• Facturapi org per contribuyente (CSD independiente)
• Emisión de CFDI con contribuyente_id

Roles y autorización

• Owner: acceso total, actúa como supervisor implícito
• Supervisor: titular de RFCs, crea carteras, gestiona auxiliares
• Auxiliar: accede solo a RFCs en carteras asignadas
• Cliente: visor externo read-only de sus RFCs
• getEntidadesVisibles(): cascada de permisos automática

Carteras

• CRUD completo (crear, editar, eliminar)
• Asignar/remover contribuyentes
• Asignar/remover auxiliares
• Cascada: si supervisor pierde RFC → auxiliares pierden acceso

Pricing

• Catálogo de planes (Business Control $21,000/año, Business Cloud $15,000/año + $45/RFC/mes)
• Add-ons recurrentes con multi-preapproval MercadoPago
• Paquetes de timbres one-shot

Connector BYO-DB

• Provisioning de tunnel (Cloudflare Tunnel ready)
• Heartbeat cada 30s con status en UI
• getPool() refactorizado para decrypt de conexiones BYO

Admin global

• Dashboard cross-despacho (métricas, lista despachos, actividad)
• Impersonación con motivo obligatorio + audit log
• Audit log expuesto al owner del despacho

Métricas pre-calculadas

• Hot/cold: año actual on-the-fly, años pasados pre-calculados
• Invalidación dirigida por cambios retroactivos en CFDIs
• Tablas: metricas_mensuales, acumuladas_anuales, contraparte, invalidaciones

Stack técnico

Capa	Tecnología
Frontend	Next.js 14, React 18, Tailwind, shadcn/ui, Zustand, React Query
Backend	Node.js 20+, Express 4, TypeScript 5, Prisma 5.22
BD Central	PostgreSQL 16 (Prisma ORM)
BD Tenant	PostgreSQL 16 (pg Pool + SQL raw + 17 migraciones numeradas)
Auth	JWT (15min) + refresh (7d) + bcrypt + magic link ready
Pagos	MercadoPago (preapproval + webhooks)
Email	Nodemailer + SMTP
Facturación	Facturapi (cuenta maestra broker)

Setup local

# Requisitos: Node 20+, pnpm 9+, PostgreSQL 16+
pnpm install
cp apps/api/.env.example apps/api/.env       # rellenar con secrets reales
echo "NEXT_PUBLIC_API_URL=http://localhost:4000/api" > apps/web/.env.local
cd apps/api && npx prisma generate
cd apps/api && npx prisma migrate deploy
cd apps/api && pnpm db:seed
pnpm dev  # API :4000 + Web :3000

Deploy a producción

Pre-requisitos del servidor

• Ubuntu 22.04+ (probado en 24.04)
• Node 20+, pnpm 9+
• PostgreSQL 16+ (con extensión pg_trgm para búsquedas full-text)
• Nginx (proxy + SSL Let's Encrypt)
• PM2 (process manager) — npm i -g pm2
• Playwright dependencies para SAT scrapers (npx playwright install-deps chromium)

Procedimiento de deploy fresco

# 1. Clonar
git clone https://github.com/Torch2196/Horux_despachos_NL.git /root/Horux
cd /root/Horux

# 2. Configurar env vars
cp apps/api/.env.example apps/api/.env
nano apps/api/.env                          # rellenar con secrets
echo "NEXT_PUBLIC_API_URL=https://api.horuxfin.com/api" > apps/web/.env.local

# 3. Instalar deps con versiones exactas
pnpm install --frozen-lockfile

# 4. BD central — schema y catálogos
pnpm db:generate
cd apps/api && npx prisma migrate deploy && cd ../..
pnpm db:seed

# 5. BD tenant — migraciones de cada tenant existente (idempotente)
pnpm --filter @horux/api db:migrate-tenants

# 6. Tenant admin global (Horux 360 — RFC HTS240708LJA)
pnpm --filter @horux/api bootstrap:admin-global
# ↑ imprime password temporal del admin en consola — guardarla

# 7. Lista negra del SAT (opcional, ~1MB de RFCs)
pnpm --filter @horux/api import:lista-negra

# 8. Build de producción
pnpm build

# 9. Configurar Nginx + SSL
sudo cp deploy/nginx/horux360.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/horux360.conf /etc/nginx/sites-enabled/
sudo certbot --nginx -d horuxfin.com -d api.horuxfin.com
sudo systemctl reload nginx

# 10. Levantar con PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup            # autostart al boot

Updates posteriores

cd /root/Horux
git pull
pnpm install --frozen-lockfile
pnpm db:generate
cd apps/api && npx prisma migrate deploy && cd ../..
pnpm --filter @horux/api db:migrate-tenants  # si hay nuevas migraciones tenant
pnpm build
pm2 restart all

Crons en producción

Los crons internos arrancan automáticamente en NODE_ENV=production:

• SAT sync diario — 03:00 AM (todos los planes)
• SAT incremental — 11:00, 15:00, 19:00 (solo Enterprise)
• Subscription lifecycle — 02:30 AM (apply pending changes, expire trials, purge)
• Reporte semanal email — Lunes 08:00 AM
• Opinión cumplimiento — Domingos 04:00 AM
• CSF mensual — Día 1 cada mes 04:00 AM
• SAT retry cron — cada hora (reintentos jobs pending)
• Watchdog jobs SAT — cada 2h (mata jobs zombies)

Si necesitás simular crons en dev: ENABLE_CRONS_IN_DEV=1 en apps/api/.env.

Estructura de BD

BD Central (Prisma)

Tenant, User, TenantMembership, Rol, Subscription, SubscriptionAddon, Payment, PlanCatalogo, PlanAddonCatalogo, FielCredential, ConnectorHeartbeat, AuditLog, TimbreSuscripcion, TimbrePaquete, catálogos SAT.

BD Tenant (SQL migrations 001-017)

001-005: Schema base (rfcs, cfdis, conciliaciones, alertas, opiniones, declaraciones, constancias) 006: tenant_migrations tracking 007-009: Core (entidades_gestionadas, carteras, cliente_accesos) 010-013: Vertical contable (contribuyentes, fiel_contribuyente, facturapi_orgs, cfdi contribuyente_id) 014-017: Métricas (mensuales, acumuladas, contraparte, invalidaciones)

Autor

Carlos e Ivan (Horux 360)

---