Visión general de la arquitectura

Zentto es un ERP modular diseñado para empresas medianas en Latinoamérica. La arquitectura se basa en un monorepo que contiene una API centralizada, 13 micro-aplicaciones frontend independientes y paquetes compartidos. Todo orquestado con Docker y desplegado automáticamente vía GitHub Actions.

Diagrama de infraestructura


  Cliente (Browser)
       │
       ▼
  ┌─────────────┐
  │  Cloudflare  │  DNS + CDN + SSL
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │    Nginx     │  Reverse proxy (zentto.net)
  └──────┬──────┘
         │
    ┌────┴─────────────────────────────────┐
    │           Docker Network              │
    │                                       │
    │  ┌──────────┐    ┌────────────────┐  │
    │  │ API:4000 │    │  Shell:3000    │  │
    │  │ Express  │    │  Next.js       │  │
    │  └────┬─────┘    └────────────────┘  │
    │       │          ┌────────────────┐  │
    │       │          │ Apps:3001-3012 │  │
    │       │          │ 12 micro-apps  │  │
    │       │          └────────────────┘  │
    └───────┼──────────────────────────────┘
            │
    ┌───────┴───────┐
    │   Database    │
    │  SQL Server   │  ← DB_TYPE=sqlserver
    │  PostgreSQL   │  ← DB_TYPE=postgres
    └───────────────┘

Componentes principales

API (Express + TypeScript)

Servidor REST en web/api/. Toda la lógica de negocio vive aquí. Interactúa con la BD exclusivamente via stored procedures.

Micro-frontends (Next.js)

13 apps independientes en web/modular-frontend/apps/. Cada módulo es una app Next.js con su propio puerto y ciclo de deploy.

Dual Database

Soporta SQL Server y PostgreSQL simultáneamente. La variable DB_TYPE controla cuál motor se usa. Paridad obligatoria entre ambos.

Contratos OpenAPI

Especificación en web/contracts/openapi.yaml. Todo endpoint se documenta antes de implementar en frontend.

Estructura de directorios clave

zentto-web/
├── web/
│   ├── api/                      # API Express + TypeScript
│   │   ├── src/
│   │   │   ├── modules/          # Módulos de negocio
│   │   │   ├── db/               # query.ts, connection pools
│   │   │   ├── middleware/        # Auth, datetime, errors
│   │   │   └── app.ts            # Registro de rutas
│   │   ├── sqlweb/               # Scripts SQL Server
│   │   │   └── includes/sp/      # Stored procedures (.sql)
│   │   └── sqlweb-pg/            # Scripts PostgreSQL
│   │       └── includes/sp/      # Functions plpgsql (.sql)
│   ├── modular-frontend/
│   │   ├── apps/                 # 13 micro-apps Next.js
│   │   │   ├── shell/            # App principal (puerto 3000)
│   │   │   ├── contabilidad/     # Puerto 3001
│   │   │   ├── pos/              # Puerto 3002
│   │   │   └── ...               # Demás módulos
│   │   └── packages/             # Paquetes compartidos
│   │       ├── shared-ui/
│   │       ├── shared-auth/
│   │       └── shared-api/
│   └── contracts/
│       └── openapi.yaml          # Contrato API
├── docker/                       # Dockerfiles
├── .github/workflows/            # CI/CD
└── nginx/                        # Configuración reverse proxy

Flujo de una solicitud típica

El navegador solicita https://zentto.net/inventario
Cloudflare resuelve DNS y pasa la solicitud a Nginx
Nginx enruta a la micro-app de inventario (localhost:3005)
La app Next.js renderiza la página y hace fetch a https://api.zentto.net/v1/inventario
Nginx enruta la llamada API al contenedor Express (localhost:4000)
Express valida JWT, convierte fechas a UTC, ejecuta el stored procedure correspondiente
La BD retorna datos, la API convierte fechas a timezone local y responde JSON

Principios de diseño

Lógica en API, no en UI — el frontend es solo presentación
SQL parametrizado siempre — cero SQL directo en TypeScript
Paridad dual-DB — todo cambio de esquema en ambos motores
UTC-0 a fuego — todas las fechas se almacenan en UTC
Contratos primero — OpenAPI se actualiza antes de codificar
Deploy automático — push a main despliega a producción