Saltar a contenido

Entendiendo la Estructura de Nuestro Proyecto Monorepo

¡Bienvenido(a) al proyecto! Está entrando en un entorno de desarrollo moderno y organizado, que utiliza una estructura de monorepo con varios servicios. No se preocupe por entender todo de una vez. Este documento es una guía práctica para que se familiarice con la arquitectura y sepa dónde encontrar lo que necesita. Muchas de las técnicas y patrones los aprenderá en el día a día.

1. Visión General del Monorepo

Nuestro proyecto es un monorepo, lo que significa que todo el código fuente (frontend, backend, gateway) reside en un único repositorio. Esto facilita la colaboración y la consistencia entre los diferentes módulos.

Está compuesto por:

  • 1 Frontend: Construido con Next.js (React).
  • 5 Microservicios de Backend:
    • 3 en Java: Usando Spring Boot.
    • 1 en Python: Usando FastAPI y Peewee.
    • 1 Gateway en Node.js: Usando Express y un Nginx como reverse proxy.

2. Estructura de Carpetas y Componentes

Vamos a sumergirnos en la organización de las carpetas para que sepa dónde encontrar cada parte del proyecto.

2.1. frontend/ (Next.js)

Aquí reside toda la aplicación web con la que interactúan los usuarios finales.

  • src/: Contiene el código fuente principal de Next.js.
    • app/: Las rutas de Next.js.
      • (private)/: Páginas que requieren autenticación para su acceso (ej: feedback/, userlist/).
      • (public)/: Páginas de acceso público (ej: login/, setpassword/).
    • components/: Componentes de React reutilizables en diversas páginas (ej: NavBar/).
    • dtos/: Modelos de datos (Data Transfer Objects) que definen la estructura de la información intercambiada con el backend.
    • services/: Funciones para hacer llamadas a la API del backend. Es aquí donde configurará cómo el frontend "conversa" con los microservicios.
    • utils/: Funciones de utilidad generales.
    • __tests__/: Carpeta para las pruebas de la aplicación frontend.
  • Archivos de Configuración: package.json, next.config.ts, tsconfig.json, Dockerfile, etc. son archivos de configuración del proyecto Next.js y del entorno de ejecución.

2.2. java_backend/ (Spring Boot)

Esta carpeta agrupa los tres microservicios de Java.

  • libs/: Contiene librerías compartidas entre los microservicios de Java.
    • security/: Una librería de seguridad personalizada (JWT) que es reutilizada por los otros microservicios. Es aquí donde está la lógica para manejar los tokens de autenticación.
  • microservices/: Cada subcarpeta aquí es un microservicio de Java independiente:
    • feedbackrequest/: Responsable de gestionar las solicitudes de feedback.
    • feedbackresponse/: Maneja las respuestas de feedback.
    • usermanagement/: Gestiona usuarios (colaboradores, PDMs, administradores).
  • Dentro de cada microservicio de Java, encontrará la siguiente estructura práctica (siguiendo las capas de un DDD simplificado):
    • controller/: Recibe las peticiones HTTP del frontend (o del gateway), valida la entrada y llama a la capa de service.
    • service/: Contiene la lógica de negocio principal. Es aquí donde va a implementar las reglas de cómo funcionan las cosas en nuestro dominio. Utiliza los repositorys para interactuar con los datos.
    • entity/: Representa las entidades del dominio, es decir, los objetos que poseen una identidad única y son persistidos en la base de datos (ej: User, FeedbackRequest).
    • repository/: Interfaces que definen cómo el service va a guardar, buscar o actualizar las entitys en la base de datos. Abstrae los detalles de cómo funciona la comunicación con la base de datos.
    • dto/: Clases para Data Transfer Objects (DTOs), usadas para recibir datos de las peticiones y enviar datos en las respuestas, facilitando la comunicación entre las capas.
    • exceptions/: Clases para tratar errores específicos de la aplicación.
    • configuration/: Configuraciones específicas del microservicio (ej: seguridad, base de datos).
  • pom.xml: Archivos de configuración de Maven para cada microservicio y para el módulo java_backend como un todo, definiendo las dependencias.
  • Dockerfile: Archivos para construir las imágenes Docker de los microservicios.

2.3. python_backend/ (FastAPI)

Aquí está el microservicio de Python, que probablemente se encarga de la visualización de las respuestas de feedback.

  • feedbackresponseview/: El directorio raíz del microservicio.
    • app/: Contiene el código fuente de la aplicación FastAPI.
      • routes/: Donde definirá los endpoints de la API (equivalente a los controllers en Java).
      • services/: Contiene la lógica de negocio (similar a la capa service en Java).
      • models/: Representa las entidades y modelos de datos para Peewee (equivalente a entity y dto en Java, pero para Python/ORM).
      • repositories/: Donde estará la lógica para interactuar con la base de datos usando Peewee (similar a la capa repository en Java).
      • config/: Configuraciones de la aplicación, como la conexión con la base de datos.
      • auth/, exceptions/, middleware/: Otras carpetas para la organización de funcionalidades de autenticación, manejo de errores y middlewares.
    • tests/: Carpeta para las pruebas unitarias y de integración del microservicio de Python.
    • pyproject.toml: Archivo de configuración del proyecto y dependencias (similar a pom.xml o package.json).
  • Dockerfile: Archivo para construir la imagen Docker del microservicio de Python.

2.4. node_backend/ (Express Gateway)

Este es nuestro Gateway de API, construido con Node.js y Express.

  • api_gateway/: El directorio del gateway.
    • src/: Contiene el código del gateway.
      • app.ts, index.ts: Archivos principales donde se define la lógica de enrutamiento y proxy hacia los microservicios.
      • app.spec.ts: Pruebas para el gateway.
  • package.json, tsconfig.json: Archivos de configuración del proyecto Node.js.
  • Dockerfile: Archivo para construir la imagen Docker del gateway.

2.5. gateway/ (Nginx)

Esta carpeta contiene el archivo de configuración de Nginx, que actúa como un reverse proxy para dirigir las peticiones al Gateway de Node.js y, posteriormente, a los microservicios correctos.

  • nginx.conf: El archivo de configuración principal de Nginx.

3. Herramientas y Patrones Esenciales

Nuestro proyecto sigue algunas convenciones y utiliza herramientas específicas:

  • Monorepo: Todo en el mismo lugar.
  • Docker y Docker Compose: Los usamos para estandarizar el entorno de desarrollo y producción. Encontrará docker-compose-dev.yml (para desarrollo) y docker-compose.yml (para producción) en la raíz.
  • Estructura de Capas (Controller, Service, Entity/Model, Repository): Esta es la organización principal de cada microservicio backend para separar responsabilidades.
    • Controller: Maneja la entrada y salida de la API (HTTP).
    • Service: Contiene la lógica de negocio.
    • Entity/Model: Representa los datos y su comportamiento.
    • Repository: Abstrae la comunicación con la base de datos.
  • JWT (JSON Web Tokens): Para la autenticación de usuarios, garantizando que solo personas autorizadas accedan a ciertas funcionalidades.
  • Bitbucket Pipelines: Para la automatización de CI/CD (integración y entrega continua), configurado en bitbucket-pipelines.yml.

4. Próximos Pasos y Dónde Encontrar Ayuda

¡No se sienta abrumado(a)! La belleza del monorepo y de la organización por capas es que puede enfocarse en una parte a la vez.

  • Para Empezar: Concéntrese en las tareas que le sean asignadas. Entienda el controller, service y repository de ese microservicio específico.
  • Documentación: Tenemos una vasta documentación interna. No dude en consultarla o preguntarle a su Tutor Tech Lead o a un colega de equipo. ¡Ellos están aquí para ayudar!
  • Aprenda en el Día a Día: Muchas de las técnicas y patrones (como DDD, JWT, y los detalles de cada framework) se comprenderán a medida que vaya desarrollando las funcionalidades. No es necesario dominar todo antes de empezar.

Está listo(a) para embarcarse en este viaje. ¿Qué parte de la aplicación tiene más curiosidad por explorar primero?