Carpeta src #

La carpeta src (o source) es el corazón de tu aplicación, conteniendo todo el código fuente del backend. Aquí encontrarás la lógica de negocio.

Archivos #

config #

Contiene los archivos de configuración de tu aplicación, esenciales para manejar parámetros que varían entre entornos (desarrollo, pruebas, producción). Aquí puedes encontrar configuraciones para elementos como sequelize.ts, swagger.ts, o google.drive.ts.

controllers #

Aloja la lógica de negocio y el manejo de solicitudes HTTP. Los controladores son la capa intermedia que recibe peticiones, procesa sus datos, interactúa con los servicios y envía una respuesta. Son el "C" de una arquitectura MVC, orquestando el flujo de una petición sin contener lógica de negocio compleja. Se encargan de:

• Recibir y validar datos de la petición (req.body, req.params, req.query).
• Delegar la lógica de negocio a los servicios (src/services).
• Manejar errores y pasarlos a los middlewares de errores.
• Construir y enviar la respuesta HTTP (res.json(), res.status()).

interfaces #

Define los tipos TypeScript para las estructuras de datos de tu aplicación. Esto incluye tipos para peticiones/respuestas de la API, estructuras de datos complejas, tipos compartidos entre módulos y DTOs (Data Transfer Objects).

lib #

Contiene bibliotecas personalizadas o integraciones con servicios externos. Aquí se encapsula código de terceros o inicializaciones reutilizables, como la inicialización de Firebase, clientes para Google Drive o SMTP, y SDKs externos.

middlewares #

Son funciones que se ejecutan antes de que una solicitud llegue a un controlador. Procesan las peticiones HTTP para tareas comunes como:

• Autenticación (JWT, API keys).
• Validación de datos de entrada.
• Registro de peticiones (logging).
• Manejo de CORS.
• Control de tasa de solicitudes (rate limiting).
• Transformación de datos.

models #

Define los modelos de datos y su interacción con la base de datos. En frameworks como Sequelize, cada modelo:

• Define la estructura de una tabla.
• Establece relaciones con otros modelos.
• Puede incluir validaciones y hooks (lógica pre/post-operaciones).

routes #

Organiza los endpoints de la API y los asocia a sus controladores. Aquí se definen los paths (/users, /products), los métodos HTTP (GET, POST), y se asocian middlewares específicos, estructurando la API en módulos lógicos.

schemas #

Contiene las definiciones para la validación de datos usando librerías como Joi o Zod. Esto incluye esquemas para cuerpos de solicitud (request bodies), parámetros de URL, parámetros de consulta (query parameters) y formularios.

services #

El corazón de la lógica de negocio de la aplicación. Los servicios encapsulan operaciones complejas, la integración entre múltiples modelos, las reglas de negocio, cálculos y transformaciones de datos. Son invocados por los controladores y no tienen conocimiento de los detalles de HTTP.

utils #

Aloja funciones utilitarias y helpers pequeñas y reutilizables. Incluye funciones para formateo de fechas, manipulación de strings, funciones matemáticas, y helpers para trabajar con arrays y objetos.

app.ts #

El archivo principal de configuración de tu aplicación Express. Aquí se:

• Crea la instancia de Express.
• Configura los middlewares globales.
• Establece la conexión a la base de datos.
• Maneja configuraciones iniciales y errores globales.

index.ts #

El punto de entrada de la aplicación. Este archivo:

• Importa y ejecuta app.ts.
• Maneja el puerto de escucha del servidor.
• Puede incluir la configuración inicial del entorno y el manejo de señales (como SIGTERM).

Flujo de una petición en el backend #

Cliente (Frontend / API Consumer)
        |
        V
[📡 HTTP Request: POST /api/users]
        |
        V
📁 routes/
- Define la ruta `/api/users`
- Asocia el endpoint a un controlador: `userController.createUser`
        |
        V
📁 middlewares/
- Se ejecutan middlewares:
   - Autenticación (JWT, roles)
   - Validación del body (`userSchema`)
   - Logging, CORS, rate-limiting, etc.
        |
        V
📁 controllers/
- El controlador (`userController.createUser`) recibe:
   - `req.body`, `req.params`, `req.query`
- Valida datos básicos (si aplica)
- Llama al servicio correspondiente: `userService.createUser(data)`
        |
        V
📁 services/
- Contiene la lógica de negocio:
   - Comprueba reglas de negocio
   - Interactúa con modelos
   - Gestiona errores de negocio
   - Puede usar funciones de `utils/`
   - Devuelve datos ya procesados
        |
        V
📁 models/
- Interactúan con la base de datos mediante Sequelize:
   - Inserta, actualiza o consulta registros
   - Usa relaciones, validaciones o hooks
        |
        V
📁 lib/
- Si es necesario, se hacen llamadas a servicios externos:
   - Google Drive, Firebase, Email, etc.
        |
        V
📁 utils/
- Se usan funciones auxiliares para:
   - Formatear datos
   - Validar estructuras complejas
   - Transformar objetos, fechas, etc.
        |
        V
📁 interfaces/
- Define los tipos usados en todas las capas:
   - DTOs, interfaces de entrada y salida
   - Tipos comunes (`User`, `Role`, etc.)
        |
        V
📁 schemas/
- Si se usaron, ya validaron previamente los datos de entrada
   - Con Joi/Zod para `req.body`, `params`, `query`
        |
        V
📁 controllers/
- El controlador recibe los datos procesados del servicio
- Construye y envía la respuesta:
   - `res.status(201).json({ user })`
        |
        V
📁 app.ts
- Configura todos los middlewares, rutas, manejo de errores
        |
        V
📁 index.ts
- Arranca el servidor, define el puerto y entorno
        |
        V
🔙 Cliente recibe la respuesta HTTP (JSON, status code)

Resumen visual del flujo por carpetas #

[index.ts] ─▶ [app.ts] ─▶ [routes] ─▶ [middlewares]
                                │
                                ▼
                        [controllers]
                                │
                                ▼
                        [services] ───▶ [models]
                                │         │
                                ▼         ▼
                          [utils]     [lib]
                                │
                                ▼
                         [interfaces]
                            +
                         [schemas]