Saltar al contenido principal

Backend: arquitectura tecnica

Resumen​

El backend esta construido como una API Express con modulos TypeScript y una separacion por capas relativamente clara entre configuracion, dominio, infraestructura y presentacion.

Stack confirmado​

AreaTecnologia
RuntimeNode.js 22
APIExpress 5
LenguajeTypeScript ESM
Base de datosFirestore
Auth server-sideFirebase Admin
Buildtsup
LogsWinston

Estructura principal del codigo​

src/
  config/
  data/
  domain/
  infrastructure/
  presentation/

Significado practico​

  • config/: variables de entorno y configuraciones base
  • data/: inicializacion de Firestore
  • domain/: interfaces, utilidades puras y errores del dominio
  • infrastructure/: logger, middlewares y clientes de integracion
  • presentation/: rutas, controladores, DTOs y servicios de aplicacion

Bootstrap​

El arranque documentado ocurre desde src/app.ts.

Pasos generales:

  1. leer FIREBASE_CREDENTIALS_PATH
  2. inicializar Firebase Admin
  3. levantar Firestore
  4. construir el servidor Express
  5. registrar rutas y middlewares
  6. escuchar en PORT

La tabla de rutas incluye un GET /health liviano antes de montar los modulos funcionales. Este endpoint no requiere sesion y devuelve estado basico del proceso.

Pipeline HTTP actual​

El orden de middlewares es importante porque define seguridad y comportamiento global:

  1. cors({ origin: "*" })
  2. helmet()
  3. parseo de JSON y formularios
  4. requestLogger
  5. rateLimitMiddleware
  6. authMiddleware
  7. businessIdHeaderMiddleware
  8. rutas
  9. notFoundRoute
  10. errorHandler

Multiempresa​

Cutlyy es multiempresa, por lo que muchas peticiones privadas dependen del header businessId.

Antes de dejar pasar una operacion, el middleware puede validar:

  • que el negocio exista
  • que tenga planId
  • que su suscripcion este activa
  • que el plan exista y este activo

Errores y logging​

Logging​

El backend registra:

  • metodo
  • URL
  • usuario solicitante
  • duracion de la request

Ademas Winston escribe en consola y en archivos de log locales.

Errores​

El sistema usa CustomError para errores controlados y un errorHandler central para convertirlos a respuesta HTTP.

Capa de servicios​

Aunque existen rutas por modulo, gran parte de la logica real vive en servicios de aplicacion bajo src/presentation/services.

Eso incluye dominios como:

  • bookings
  • appointments
  • memberships
  • business
  • metrics
  • reviews
  • push notifications
  • WhatsApp
  • outbox y dispatch externo

Patrones a tener presentes​

  • persistencia via FirestoreService
  • soft delete y timestamps
  • side effects encadenados despues de cambios de estado
  • validaciones cruzadas entre negocio, sede, empleado, servicio y plan
  • eventos diferidos en outbox para procesos reintentables o desacoplados del request principal

Limitaciones y observaciones actuales​

  • el healthcheck actual solo valida que el proceso HTTP responda
  • no existe Swagger u OpenAPI formal
  • el script test aun no representa una suite real
  • persisten nombres legacy como bigopets-backend y BUSSINESS

Documentos relacionados​