Decisiones Clave de Arquitectura

Este documento registra las decisiones arquitectónicas fundamentales tomadas para el backend del proyecto "Gestiona tu Loteo a tu Agrado".

1. Stack Tecnológico Principal

• Framework Backend: NestJS (sobre Node.js, usando TypeScript)
• Interfaz API Principal: GraphQL (Code-First con @nestjs/graphql y Apollo Server)
• Base de Datos: PostgreSQL
• ORM: TypeORM (con enfoque "Entity-First" para la evolución del esquema a partir de la línea base)

2. Principios de Diseño Arquitectónico

• Modularidad: Alta modularidad con módulos NestJS por dominio funcional.
• Bajo Acoplamiento, Alta Cohesión: Módulos independientes con responsabilidades claras.
• Separación de Responsabilidades:
  • Entidades TypeORM: Definición de la estructura de datos y mapeo a la BD.
  • Servicios (*.service.ts): Contienen la lógica de negocio principal, interactúan con los repositorios TypeORM.
  • Resolvers GraphQL (*.resolver.ts): Exponen la lógica de los servicios a través de Queries, Mutations y (futuras) Subscriptions.
  • Inputs/Args/Types GraphQL (*.input.ts, *.args.ts, *.type.ts): Definen los contratos de datos para la API GraphQL.
• Configuración Centralizada: Uso de @nestjs/config y archivos .env para toda la configuración externalizable.
• Asincronía y Manejo de Procesos Largos:
  • Uso de Colas (planificado: BullMQ con Redis) para tareas como envío masivo de emails, procesamiento de carga masiva.
  • Patrón Saga para orquestar procesos de negocio complejos y de múltiples pasos (ej. Onboarding de Loteo, Carga Masiva) para asegurar consistencia o permitir compensaciones.
• Desacoplamiento con Eventos: Uso de @nestjs/event-emitter para comunicación interna desacoplada entre módulos cuando sea apropiado.
• Capa de Abstracción para APIs de Terceros: Creación de "Servicios Wrapper" dedicados (en un IntegrationsModule futuro) para cada API externa (Pasarela de Pago, Validación de Identidad, APIs de Cámaras, APIs de QR, Clima, etc.), adoptando un enfoque "Plug and Play".
• Seguridad por Diseño: Autenticación basada en JWT, autorización por roles (rolPlataforma, rolEnLoteo, rolEnComite) mediante Guards de GraphQL, validación de todas las entradas de API (class-validator en Inputs/Args).
• Monitoreo y Observabilidad (Planificado): Preparación para integrar Prometheus (métricas), Grafana (dashboards) y Loki (logging).
• Contenerización (Planificado): Uso de Docker y Docker Compose para desarrollo y despliegue.
• Escalabilidad: Diseño modular y uso de patrones asíncronos para facilitar el escalado horizontal y vertical en la nube.