1. Propósito del documento

Este documento define los fundamentos técnicos y conceptuales para construir el ecosistema QUIPU como una plataforma SaaS empresarial, no como una colección de aplicaciones aisladas.

Qué busca resolver

• Evitar código duplicado entre balance.plus, logistica.plus, reserva.plus, SATD y futuros productos.
• Mantener una arquitectura simple para un desarrollador individual, pero preparada para escalar.
• Definir reglas claras de seguridad, multi-tenancy, APIs, base de datos, permisos y auditoría.
• Separar conceptos: aplicación web, API, módulo, dominio, motor, monolito modular y microservicio.
• Crear una guía permanente para revisar decisiones antes de programar.

Cómo debe usarse

Antes de crear un nuevo módulo, tabla, ruta o pantalla, revisa este documento. La pregunta principal debe ser: ¿esto pertenece al núcleo común, a un motor reutilizable o a un producto específico?

2. Visión general de QUIPU

QUIPU debe evolucionar como una plataforma empresarial modular. Encima de ella pueden nacer múltiples SaaS, cada uno especializado en un problema concreto, pero todos compartiendo una misma infraestructura.

La diferencia clave

3. Principios rectores

Estos principios deben guiar todas las decisiones técnicas del proyecto.

4. Conceptos base

Antes de programar, conviene diferenciar correctamente los conceptos que sostienen la arquitectura.

API

Una API es una puerta de entrada. Recibe solicitudes, valida datos, ejecuta reglas de negocio y devuelve respuestas. No significa necesariamente que exista un microservicio.

Monolito

Es una sola aplicación que contiene todos los módulos. Puede ser desordenado si todo se mezcla, o muy sólido si se organiza correctamente.

Monolito modular

Es una sola aplicación, pero separada internamente por módulos. Este es el enfoque recomendado para QUIPU.

Microservicio

Es una aplicación independiente, con su propio proceso, despliegue, configuración y normalmente su propia responsabilidad. Los microservicios se comunican entre sí usando APIs, colas o eventos.

5. Arquitectura recomendada

La arquitectura recomendada es un monolito modular con APIs internas versionadas, preparado para evolucionar hacia servicios separados si en el futuro existe una razón real.

Stack obligatorio

Qué significa “preparado para escalar”

No significa usar microservicios desde el primer día. Significa que cada módulo debe tener límites claros, interfaces limpias y poca dependencia directa de otros módulos.

6. Capas de la plataforma

QUIPU debe organizarse por capas para evitar mezclar infraestructura, reglas de negocio y productos comerciales.

Capa 1: Núcleo SaaS

Es la base común de todos los productos. No pertenece solo a logística ni solo a balance.plus. Pertenece a todo el ecosistema.

• Autenticación y sesiones.
• Tenants y configuración.
• Usuarios, roles y permisos.
• Suscripciones, planes y módulos habilitados.
• Auditoría.
• Notificaciones.
• Catálogos globales: países, monedas, idiomas, impuestos, unidades.
• Gestión de archivos.

Capa 2: Motores reutilizables

Son bloques de lógica que pueden ser usados por varios productos. Por ejemplo, un motor de documentos puede servir para logística, SATD, ventas, compras y balance.plus.

Capa 3: Productos SaaS

Son las aplicaciones visibles para el cliente final. Cada producto activa ciertos módulos y vistas, pero no debe duplicar la infraestructura.

7. Dominios de negocio

Un dominio representa un área de negocio con sus propias reglas, datos y procesos. Pensar por dominios evita que el sistema se convierta en una mezcla desordenada de tablas y pantallas.

Mapa conceptual

Regla para identificar un dominio

Si un conjunto de funcionalidades tiene vocabulario propio, reglas propias y datos propios, probablemente pertenece a un dominio.

8. Motores reutilizables

Un motor es una pieza de lógica reutilizable. No es solo una tabla ni una pantalla. Es un conjunto de reglas de negocio que puede servir a más de un producto.

Cómo reconocer si algo debe ser un motor

• Será usado por más de un producto.
• Contiene reglas de negocio propias.
• Necesita configuración por tenant.
• Puede tener API propia.
• Puede evolucionar sin depender totalmente de una pantalla específica.

9. Estrategia API

Las APIs deben existir desde el inicio porque permiten que web, PWA, Android e integraciones compartan las mismas reglas de negocio.

Convención base

/api/v1/{resource}

/api/v1/auth
/api/v1/products
/api/v1/inventory
/api/v1/warehouses
/api/v1/sales
/api/v1/reports

APIs del núcleo SaaS

APIs logísticas y comerciales

Reglas de diseño API

• Versionar desde el inicio: /api/v1.
• Usar JSON como formato de intercambio.
• No recibir tenant_id desde frontend.
• Validar inputs antes de llegar al service.
• Aplicar rate limit por IP, usuario y tenant según la ruta.
• Registrar auditoría en operaciones críticas.
• Usar respuestas de error consistentes.

Formato sugerido de respuesta

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "req_123",
    "version": "v1"
  }
}

Formato sugerido de error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Los datos enviados no son válidos.",
    "details": []
  },
  "meta": {
    "requestId": "req_123",
    "version": "v1"
  }
}

10. Multi-tenancy

El multi-tenancy es el fundamento más crítico del SaaS. En QUIPU se recomienda base de datos compartida, con aislamiento estricto mediante tenant_id.

Regla absoluta

Flujo correcto

Middleware recomendado

request
  → securityMiddleware
  → authMiddleware
  → tenantResolverMiddleware
  → subscriptionMiddleware
  → permissionsMiddleware
  → moduleAccessMiddleware
  → controller

Reglas de base de datos

• Todas las tablas transaccionales deben tener tenant_id.
• Todas las consultas deben filtrar por tenant_id.
• Los índices deben incluir tenant_id en tablas de alto uso.
• Las relaciones deben evitar mezclar registros de tenants distintos.
• La auditoría debe registrar siempre tenant_id.

Ejemplo conceptual de consulta correcta

SELECT id, sku, name
FROM products
WHERE tenant_id = ?
  AND id = ?
  AND deleted_at IS NULL;

Consulta peligrosa

SELECT id, sku, name
FROM products
WHERE id = ?;

11. Seguridad

La seguridad no debe agregarse al final. Debe estar presente en rutas, middlewares, queries, vistas, formularios, APIs, archivos, sesiones y logs.

Controles base

Headers y middlewares sugeridos

• helmet para headers de seguridad.
• express-rate-limit o Redis-based rate limit.
• zod, joi o validadores propios para inputs.
• bcrypt o argon2 para passwords.
• Cookies seguras si se usan tokens en cookies: httpOnly, secure, sameSite.

Auditoría mínima

12. Datos y MySQL

MySQL será el centro transaccional de QUIPU. El diseño debe priorizar consistencia, aislamiento por tenant, trazabilidad y performance.

Reglas de modelado

• Usar tenant_id en toda tabla de datos empresariales.
• Separar catálogos globales de catálogos por tenant.
• Usar claves primarias internas y códigos visibles separados.
• Usar timestamps estándar: created_at, updated_at, deleted_at.
• Usar soft delete cuando el histórico sea importante.
• No borrar movimientos de inventario: se corrigen con movimientos inversos o ajustes auditados.
• Crear índices pensando en consultas reales, no por costumbre.

Campos estándar sugeridos

id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT UNSIGNED NOT NULL,
created_by BIGINT UNSIGNED NULL,
updated_by BIGINT UNSIGNED NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NULL ON UPDATE CURRENT_TIMESTAMP,
deleted_at DATETIME NULL

Índices multi-tenant

En tablas grandes, los índices deben considerar que casi todas las consultas filtran por tenant.

INDEX idx_products_tenant_sku (tenant_id, sku),
INDEX idx_movements_tenant_date (tenant_id, movement_date),
INDEX idx_stock_tenant_product_location (tenant_id, product_id, warehouse_id, location_id)

Inventario: regla conceptual

El stock no debe ser solo un número editado manualmente. Debe ser el resultado de movimientos: ingreso, salida, ajuste, transferencia, devolución, inventario inicial.

13. Redis

Redis debe utilizarse para acelerar y controlar el sistema, no como reemplazo de MySQL.

Regla de uso

Ejemplos de cache recomendada

• Configuración del tenant.
• Permisos del usuario.
• Módulos habilitados por plan.
• Catálogos globales de baja variación.
• Preferencias de idioma y moneda.

Qué no guardar solo en Redis

• Movimientos de inventario definitivos.
• Órdenes de compra o venta finales.
• Auditoría legal.
• Datos que no puedan perderse.

14. Web SSR, PWA y Android

La aplicación web debe ser el centro administrativo. PWA y Android deben complementar procesos operativos, no duplicar la plataforma.

Web con EJS SSR

Ideal para administración, configuración, dashboards, tablas, formularios, reportes y operaciones de oficina.

PWA

Permite mejorar la experiencia móvil desde la web: acceso tipo app, service worker, cache controlada, push notifications y mejor rendimiento percibido.

Android

Debe usarse donde realmente aporta valor operativo:

• Picking en almacén.
• Inventario físico.
• Recepción de mercadería.
• Despachos y evidencias.
• Ventas de campo.
• Lectura de QR, código de barras o NFC.

Principio clave

Windows de escritorio

Solo debe considerarse cuando exista integración fuerte con hardware local o una necesidad offline muy específica: cámaras industriales, básculas, microscopios, PLCs, impresoras especiales o instrumentos de medición.

15. Estructura de proyecto

La estructura debe ser suficientemente ordenada para escalar, pero no tan compleja que dificulte el avance individual.

Estructura recomendada

quipu-saas/
├── docs/
│   ├── 00-project-vision.md
│   ├── 01-architecture.md
│   ├── 02-multi-tenancy.md
│   └── 03-api-guidelines.md
│
├── public/
│   ├── assets/
│   ├── css/
│   ├── js/
│   ├── manifest.json
│   └── service-worker.js
│
├── src/
│   ├── app.js
│   ├── server.js
│   │
│   ├── config/
│   │   ├── app.config.js
│   │   ├── database.config.js
│   │   ├── redis.config.js
│   │   └── security.config.js
│   │
│   ├── shared/
│   │   ├── database/
│   │   ├── redis/
│   │   ├── middlewares/
│   │   ├── validators/
│   │   ├── errors/
│   │   ├── utils/
│   │   └── services/
│   │
│   ├── modules/
│   │   ├── auth/
│   │   ├── tenants/
│   │   ├── users/
│   │   ├── roles/
│   │   ├── subscriptions/
│   │   ├── products/
│   │   ├── inventory/
│   │   ├── warehouses/
│   │   ├── sales/
│   │   ├── purchases/
│   │   ├── documents/
│   │   ├── reports/
│   │   └── notifications/
│   │
│   ├── routes/
│   │   ├── web.routes.js
│   │   └── api.v1.routes.js
│   │
│   ├── views/
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── products/
│   │   ├── inventory/
│   │   └── errors/
│   │
│   ├── layouts/
│   │   ├── main.ejs
│   │   ├── auth.ejs
│   │   └── error.ejs
│   │
│   └── partials/
│       ├── head.ejs
│       ├── sidenav.ejs
│       ├── topbar.ejs
│       └── scripts.ejs
│
├── tests/
├── .env.example
├── package.json
└── README.md

Estructura interna de un módulo

modules/products/
├── products.routes.js
├── products.controller.js
├── products.service.js
├── products.repository.js
├── products.validator.js
├── products.policy.js
└── products.constants.js

16. Flujos críticos

Los flujos críticos deben diseñarse antes de crear pantallas, porque definen seguridad, datos y responsabilidades.

Flujo de login

Flujo de request autenticado

Flujo de movimiento de inventario

Flujo de pedido a despacho

17. Reportes e inteligencia

La inteligencia del sistema aparece cuando los datos están bien estructurados y auditados. No se empieza por IA; se empieza por datos confiables.

Reportes base por dominio

Inteligencia progresiva

1. Reportes descriptivos: qué ocurrió.
2. Indicadores: cómo estamos.
3. Alertas: qué requiere atención.
4. Predicción: qué podría ocurrir.
5. Recomendación: qué conviene hacer.
6. Asistente: consulta por texto o voz.

Uso futuro de Python

Node.js debe seguir siendo el núcleo transaccional. Python puede incorporarse después para tareas analíticas: predicción de demanda, modelos estadísticos, procesamiento de documentos o IA. La comunicación puede hacerse mediante colas, jobs o APIs internas.

18. Escalabilidad

Escalar no es solo soportar más usuarios. También significa mantener el código comprensible, la base de datos eficiente y los procesos controlados.

Escalabilidad técnica

• Pool de conexiones MySQL.
• Índices correctos.
• Cache Redis para datos repetitivos.
• Jobs para procesos lentos.
• Paginación obligatoria en listados.
• Evitar consultas N+1.
• Rate limit en APIs.
• Logs estructurados.

Escalabilidad organizacional

Aunque al inicio haya un solo desarrollador, el proyecto debe poder ser entendido por otro programador en el futuro. Por eso importan los comentarios iniciales por archivo, los nombres claros, los documentos .md y la consistencia de carpetas.

Cuándo considerar microservicios

19. Roadmap recomendado

El roadmap debe reducir riesgo. Primero se construye el núcleo, luego los motores, después los productos.

Etapa 0: Documentación base

• Visión del proyecto.
• Arquitectura base.
• Reglas multi-tenant.
• Convenciones API.
• Convenciones de carpetas.

Etapa 1: Núcleo SaaS

• Login seguro.
• JWT corto.
• Redis para sesión/revocación.
• Tenants.
• Usuarios.
• Roles y permisos.
• Planes y módulos.
• Auditoría.

Etapa 2: Base operativa

• Catálogos globales.
• Productos.
• Almacenes.
• Ubicaciones.
• Inventario inicial.
• Movimientos y kardex.

Etapa 3: Logística avanzada

• Lotes.
• Vencimientos.
• Seriales.
• Variantes.
• Picking.
• Despacho.
• Evidencias.

Etapa 4: Comercial

• Clientes y proveedores.
• Listas de precios.
• Cotizaciones.
• Pedidos.
• Compras.
• Recepciones.

Etapa 5: Reportes e inteligencia

• Dashboards.
• KPIs.
• Alertas.
• Predicción de stock.
• Sugerencias de compra.
• Asistente por texto/voz.

20. Checklists

Usa estas listas antes de aprobar cualquier módulo, API o tabla.

Checklist de módulo nuevo

• ¿Pertenece al núcleo, a un motor o a un producto específico?
• ¿Tiene rutas, controller, service, repository y validator separados?
• ¿Todas sus queries filtran por tenant_id?
• ¿Valida permisos?
• ¿Valida plan y módulo habilitado?
• ¿Registra auditoría si cambia datos críticos?
• ¿Tiene paginación si lista registros?
• ¿Evita duplicar lógica existente?

Checklist de tabla nueva

• ¿Necesita tenant_id?
• ¿Tiene timestamps estándar?
• ¿Necesita soft delete?
• ¿Tiene índices acordes a las consultas?
• ¿Tiene campos de auditoría si corresponde?
• ¿Evita guardar datos calculados sin justificación?
• ¿Sus relaciones respetan el tenant?

Checklist de endpoint API

• ¿Está bajo /api/v1?
• ¿Tiene rate limit si es sensible?
• ¿Valida autenticación?
• ¿Valida permisos?
• ¿Valida inputs?
• ¿Devuelve errores consistentes?
• ¿No expone información interna?
• ¿Registra auditoría si corresponde?

Checklist de seguridad

• No concatenar SQL.
• No confiar en datos del frontend.
• No aceptar tenant_id enviado por cliente.
• No guardar contraseñas sin hash fuerte.
• No mostrar errores internos al usuario final.
• No servir archivos privados sin autorización.
• No permitir endpoints sin rate limit cuando puedan ser abusados.

21. Glosario

Definiciones breves para revisar conceptos con rapidez.

Conclusión fundacional