How cymetriagroup/back_talent_pool works
Para elaborar el diagrama de arquitectura y diseño del sistema teniendo en cuenta este proyecto, seguí estos pasos y recomendaciones específicas:
Identificar el tipo y propósito del proyecto
• Se trata de una API desarrollada con Express.js y TypeScript, implementada con una arquitectura hexagonal (Ports and Adapters). La idea central es mantener un núcleo de dominio puro desacoplado de frameworks externos y detalles de infraestructura.
• El README destaca que la aplicación maneja rutas versionadas (por ejemplo, /api/v1/hello) y define entidades (como User y Companies) a través de una separación clara entre las capas del dominio y la infraestructura (HTTP, base de datos).
Análisis de la estructura de archivos
• Carpeta raíz y archivos de configuración (.env.example, tsconfig.json, package.json, etc.) para el entorno y la compilación.
• La carpeta src contiene el código fuente:
• app.ts e index.ts: inician la aplicación y configuran Express.
• config/: contiene configuraciones globales (variables de entorno, configuración de base de datos, etc.).
• decorators/: funciones de orden superior (por ejemplo, para manejo de excepciones).
• domain/: contiene la lógica de negocio “pura”, con subdirectorios para entidades, DTOs y puertos (interfaces) que definen contratos (por ejemplo, repositorios).
• infrastructure/: adapta el dominio al mundo exterior, dividiéndose en:
• db/…: implementación de repositorios para la base de datos, incluyendo una subestructura para Sequelize, que sugiere un uso de ORM.
• http/: controladores, rutas, servicios (incluyendo servicios de seguridad y validación), middlewares y tests.
• La separación “de afuera hacia adentro” es clara: los controladores en la capa HTTP llaman a servicios, los cuales implementan las interfaces (puertos) definidas en el dominio.
Componentes principales a incluir en el diagrama
a. Núcleo del Dominio (Domain):
• Entidades: clases definidas en domain/entities.
• DTOs y esquemas: para transformar y validar los datos.
• Puertos: interfaces en domain/ports que abstraen la lógica de negocio a nivel de repositorios o servicios.
b. Infraestructura:
• Adaptadores de Base de Datos: Implementaciones concretas (repositorios) en infrastructure/db/sequelize que interactúan con los modelos definidos.
• Adaptadores HTTP: Controladores, Rutas y Servicios en infrastructure/http que exponen la API y manejan la lógica de enrutado y middleware.
• Middlewares y gestión de errores: presentes en infrastructure/http/middlewares y errors.
c. Configuración y Bootstrap:
• app.ts y index.ts sirven para levantar el servidor Express, configurar middlewares y enrutar solicitudes.
Relaciones e interacciones
• Los controladores (en Infrastructure/HTTP) reciben las solicitudes HTTP y delegan la lógica al servicio correspondiente.
• Los servicios implementan la lógica de negocio, invocando métodos definidos en los puertos del dominio.
• Los repositorios (también en la capa de Infrastructure, en db) implementan la persistencia, interactuando con modelos ORM (Sequelize) para acceder a la base de datos.
• La dependencia siempre apunta “desde afuera hacia el núcleo” (inversión de control): la capa de dominio no conoce detalles de la infraestructura.
• Además, la comunicación entre los diferentes componentes se puede representar mediante flechas direccionales que indiquen flujo de datos (por ejemplo, de HTTP Controller a Servicio, de Servicio a Repositorio, etc.).
Pautas para el diagrama
• Utilizá cajas etiquetadas de forma clara para cada componente principal:
• Capa de Dominio: incluir entidades, DTOs y puertos (interfaces de repositorios).
• Capa de Infraestructura: dividir en adaptadores HTTP (rutas, controladores, middlewares), adaptadores de Base de Datos (repositorios y modelos Sequelize).
• Configuración/Bootstrap: app.ts e index.ts como el punto de inicio.
• Usá flechas direccionales para mostrar la comunicación:
• Por ejemplo, la ruta “/api/v1/companies” direcciona a un controlador, que invoca un servicio, el cual a su vez utiliza un repositorio implementado.
• Las flechas deben destacar el flujo de dependencia inversa, de modo que las componentes externas dependan del dominio y no viceversa.
• Incluya etiquetas adicionales si es necesario: ejemplo de versiones de rutas (v1), y destacar el manejo de errores o el uso de middlewares.
Consideraciones de diseño específicas para una aplicación full-stack
• Aunque este proyecto es una API y no tiene un frontend tradicional, enfatizá la separación entre la lógica del dominio (modelo de negocio) y los adaptadores – que en este caso son HTTP para la exposición de la API y DB para persistencia.
• Si en el futuro se extienden funcionalidades (como autenticación JWT, validación con Zod o Joi, documentación con Swagger), se deben reservar espacios o cajas adicionales en el diagrama para estos módulos.
Detalles adicionales a documentar
• Etiquetado claro de cada componente con su nombre y función.
• Marcas o notas que indiquen ejemplos específicos, como “companies.controller”, “companies.repository.sequelize”, etc.
• Es importante capturar tanto la estructura como los flujos de datos: request-response en HTTP, llamadas a servicios y repositorios, y la inicialización del servidor.
En resumen, el diagrama debe ser muy detallado, con una división clara por capas (Domain, Infraestructura y Configuración), flechas que representen el flujo de datos y dependencias, y el uso de colores o formas diferentes para destacar la arquitectura hexagonal. Esto permitirá entender mejor cómo cada parte del sistema interactúa y cómo se logran los principios de desacoplamiento y escalabilidad dentro del proyecto.