Home - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

BuenOrigen Backend

Bienvenido a la Wiki de BuenOrigen Backend, desarrollada en el marco del Bootcamp de Desarrollo Backend de la Universidad de Chile.

BuenOrigen es una plataforma de comercio electrónico orientada a conectar emprendimientos y consumidores, incorporando información sobre productos y sus características.

El backend está desarrollado con NestJS y TypeScript, utilizando una arquitectura modular y una API REST para proporcionar los servicios que requieren las aplicaciones Frontend y Mobile.

Esta Wiki centraliza la documentación funcional y técnica del proyecto, incluyendo:

Funcionalidades identificadas en los flujos, wireframes y sitemap de UX/UI.
Arquitectura del backend, módulos, dominios y servicios.
Modelos de datos y Data Transfer Objects (DTOs).
Endpoints REST y contratos de comunicación.
Validaciones y componentes transversales.
Documentación OpenAPI/Swagger.
Configuración, ejecución e infraestructura.
Flujo de desarrollo colaborativo mediante Git y GitHub.

Las páginas funcionales permiten comprender los requerimientos de BuenOrigen, mientras que las páginas técnicas describen su implementación. No todas las funcionalidades identificadas en el diseño cuentan necesariamente con endpoints implementados.

Objetivo

El objetivo de BuenOrigen Backend es proporcionar una API REST organizada y mantenible que permita gestionar y consultar la información necesaria para el funcionamiento de la plataforma.

Sus principales objetivos técnicos son:

Organizar las funcionalidades mediante módulos de NestJS.
Separar las responsabilidades de controllers, services, modelos y DTOs.
Implementar las operaciones y reglas de negocio correspondientes.
Proporcionar contratos de comunicación consistentes para Frontend y Mobile.
Validar los datos recibidos y gestionar adecuadamente las respuestas HTTP.
Incorporar mecanismos transversales de trazabilidad y manejo de errores.
Documentar los servicios mediante OpenAPI/Swagger.
Mantener una organización de código consistente y un flujo colaborativo de desarrollo.
Disponer de documentación para la configuración, ejecución y despliegue de la aplicación.

Funcionalidades de BuenOrigen

Las funcionalidades se encuentran organizadas de acuerdo con las principales áreas identificadas por el equipo UX/UI.

Cada página describe la funcionalidad correspondiente, su responsabilidad desde el backend y su relación con los contratos disponibles.

Header

Funcionalidades disponibles desde la navegación principal:

Estas funcionalidades permiten realizar búsquedas en el catálogo, acceder a productos favoritos, administrar el carrito y consultar información de la cuenta.

Página de Inicio

La página de inicio reúne funcionalidades orientadas al descubrimiento de productos y emprendimientos:

Las consultas relacionadas con ofertas, popularidad y novedades se vinculan principalmente con el dominio Productos.

Emprendedores

Funcionalidades que permiten consultar información pública de los emprendimientos disponibles en BuenOrigen:

Estas funcionalidades se relacionan principalmente con el dominio Emprendedores y las consultas de productos asociados.

Página de Subcategoría

Funcionalidades de organización y navegación del catálogo:

Permiten consultar clasificaciones del catálogo y obtener los productos correspondientes a una subcategoría.

Detalle de Producto

Funcionalidades relacionadas con la consulta de información específica de un producto:

Estas operaciones permiten acceder a información del catálogo, características ambientales, valoraciones y productos relacionados.

Cuenta de Usuario

Funcionalidades asociadas a la cuenta de los compradores:

Las funcionalidades que requieren identificación o autorización deben distinguirse de los endpoints públicos efectivamente disponibles.

Cuenta de Emprendedor

Funcionalidades relacionadas con la administración privada de los emprendimientos:

La cuenta administrativa del emprendedor se diferencia de su perfil público, destinado a la consulta de información por parte de los compradores.

Funcionalidades previstas en UX/UI

Además de las consultas públicas del catálogo, los wireframes y el sitemap consideran registro y autenticación, direcciones, historial de compras, devoluciones, Puntos Verdes, pagos y envíos; y, para emprendedores, dashboard, perfil privado, gestión de productos, ventas y funciones complementarias.

Estas necesidades se documentan en Funcionalidades Backend y Módulos y Dominios. Su presencia en UX/UI no implica que estén implementadas ni que cada una requiera un módulo independiente.

Arquitectura Backend

BuenOrigen Backend utiliza una arquitectura modular basada en NestJS.

La organización del código permite separar las responsabilidades de recepción de solicitudes, ejecución de reglas de negocio, representación de datos y gestión de componentes transversales.

Componentes principales

Componente	Responsabilidad
Module	Organiza los componentes y dependencias de una funcionalidad.
Controller	Define los endpoints y recibe las solicitudes HTTP.
Service	Ejecuta las operaciones y reglas de negocio.
Model	Representa estructuras de información del dominio.
DTO	Define contratos de transferencia de datos.
Pipe	Valida o transforma datos durante el procesamiento de solicitudes.
Middleware	Ejecuta operaciones transversales sobre solicitudes HTTP.
Guard	Controla el acceso a operaciones cuando se requiere autorización.
Exception Filter	Gestiona las excepciones y sus respuestas HTTP.

La aplicación organiza sus modelos y DTOs mediante convenciones de nombres en inglés, de acuerdo con la normalización realizada en el repositorio.

Dominios del backend

Entre las principales áreas funcionales con implementación documentada se encuentran:

Productos

Responsable de las consultas relacionadas con:

Búsqueda de productos.
Productos en oferta.
Productos más vendidos.
Productos nuevos.
Detalle de producto.
Huella Verde.
Valoraciones.
Productos relacionados.
Productos asociados a emprendedores.

Subcategorías

Responsable de las consultas relacionadas con:

Subcategorías disponibles.
Productos asociados a una subcategoría.
Productos populares por subcategoría.

Emprendedores

Responsable de las consultas relacionadas con:

Listado público de emprendedores.
Perfil público del emprendedor.
Productos asociados al emprendedor.

La arquitectura también contempla los dominios correspondientes a otras funcionalidades identificadas en UX/UI, cuya disponibilidad debe contrastarse con los endpoints implementados.

Organización técnica

Para conocer los módulos, responsabilidades, dependencias y servicios de la aplicación, consultar:

Estas páginas profundizan en la arquitectura y deben reflejar los nombres y archivos vigentes del código fuente.

Procesamiento de solicitudes HTTP

La API utiliza componentes de NestJS para procesar solicitudes, validar información, ejecutar operaciones de negocio y gestionar respuestas.

El siguiente diagrama representa de forma simplificada el recorrido de una solicitud:

flowchart TD
    A["Frontend / Mobile"] --> B["Solicitud HTTP"]
    B --> C["Middleware"]
    C --> D["Guard"]
    D --> E["Pipes"]
    E --> F["Controller"]
    F --> G["Service"]
    G --> H["Datos / Reglas de negocio"]
    H --> G
    G --> I["Respuesta HTTP"]
    I --> A

    D -.-> J["Exception Filter"]
    E -.-> J
    F -.-> J
    G -.-> J
    J --> I

El diagrama muestra el funcionamiento conceptual de los componentes; no significa que cada endpoint utilice necesariamente todos ellos.

Componentes transversales

Trazabilidad HTTP

El backend incorpora mecanismos de registro y trazabilidad de solicitudes HTTP.

Entre sus responsabilidades se encuentra facilitar el seguimiento de las solicitudes y registrar información útil para el diagnóstico y la observabilidad.

La implementación de trazabilidad debe considerar el tratamiento seguro de los datos contenidos en las solicitudes, evitando exponer información sensible.

Validaciones

Las validaciones permiten controlar que los datos recibidos cumplan los requisitos establecidos por los contratos de la API.

Se consideran, según corresponda:

Parámetros de ruta.
Parámetros de consulta.
Cuerpos de solicitudes.
Tipos y formatos de datos.
Valores requeridos y restricciones aplicables.

Manejo de excepciones

El backend incorpora mecanismos para gestionar errores de forma consistente, utilizando los códigos de estado HTTP correspondientes.

Estos componentes contribuyen a ofrecer respuestas comprensibles y contratos estables para los consumidores de la API.

Contratos de API

La API de BuenOrigen proporciona interfaces HTTP para la comunicación con Frontend y Mobile.

Los contratos se encuentran organizados en las siguientes páginas:

Endpoints

La página Endpoints centraliza las operaciones documentadas y permite identificar:

Método HTTP.
Ruta.
Funcionalidad asociada.
Disponibilidad en el código.
Archivo de implementación correspondiente.

La información técnica de cada endpoint debe mantener coherencia con los controllers y services implementados.

DTOs

Los DTOs permiten definir las estructuras de datos utilizadas en las solicitudes y respuestas de la API.

Su documentación permite identificar las propiedades que forman parte de los contratos de comunicación y, cuando corresponda, sus restricciones.

Los nombres técnicos deben coincidir con los DTOs vigentes en el repositorio.

OpenAPI y Swagger

BuenOrigen Backend utiliza OpenAPI/Swagger para documentar los servicios REST.

La documentación permite consultar:

Endpoints disponibles.
Métodos HTTP.
Parámetros de ruta y consulta.
Estructuras de datos.
Códigos de respuesta.
Descripción de las operaciones.

En NestJS, Swagger se configura mediante @nestjs/swagger y decoradores como @ApiTags(), @ApiOperation(), @ApiParam(), @ApiQuery() y @ApiProperty().

Estos decoradores permiten describir los contratos, pero no sustituyen los mecanismos de validación implementados por la aplicación.

Modelos y gestión de datos

El backend utiliza modelos para representar las estructuras de información del negocio.

Entre las entidades y conceptos documentados se encuentran productos, subcategorías y emprendedores, además de las estructuras requeridas por las funcionalidades correspondientes.

Datos en memoria

Las funcionalidades desarrolladas mediante estructuras en memoria utilizan los services para administrar y consultar los datos necesarios.

La arquitectura busca mantener responsabilidades claras y favorecer la reutilización de operaciones entre módulos, evitando duplicidades innecesarias.

Modelo entidad–relación

El repositorio incorpora un modelo entidad–relación representado mediante Mermaid.

Este diagrama documenta las entidades del negocio y sus relaciones conceptuales.

Su incorporación al README permite disponer de una referencia centralizada de la estructura de datos prevista para el proyecto.

El modelo entidad–relación es un instrumento de documentación y no implica, por sí solo, que exista una implementación de persistencia mediante base de datos.

Referencia: README de BuenOrigen Backend.

Desarrollo y ejecución

El proyecto utiliza Node.js, TypeScript y NestJS.

Requisitos generales

Para trabajar localmente es necesario disponer de:

Node.js y npm compatibles con el proyecto.
Git.
Una copia del repositorio.
Las variables de entorno requeridas por la configuración vigente.

Instalación

Desde el directorio del proyecto:

npm install

Ejecución en desarrollo

npm run start:dev

Compilación

npm run build

Los comandos corresponden a las operaciones habituales del proyecto NestJS.

La configuración de puertos, variables de entorno y documentación Swagger debe consultarse en el README y los archivos de configuración vigentes. La página Instalación y Configuración Local reunirá estas instrucciones en detalle.

Flujo de Git

El equipo utiliza un flujo colaborativo basado en ramas, issues y pull requests.

Las modificaciones se desarrollan en ramas específicas, tomando develop como referencia de integración.

Las contribuciones se revisan antes de incorporarse a la rama correspondiente.

Para conocer las convenciones de ramas, commits y revisión de cambios, consultar:

Flujo de Git

Docker y despliegue

La documentación de infraestructura complementa las instrucciones de ejecución local y describe cómo se construye, ejecuta y publica BuenOrigen Backend en los entornos utilizados por el equipo.

Su objetivo es permitir que los integrantes del equipo comprendan cómo se construye, configura, ejecuta y publica la aplicación en los entornos utilizados por BuenOrigen.

Docker

La página Docker documenta la configuración de contenedores utilizada por BuenOrigen Backend.

Incluye:

Archivos Dockerfile y .dockerignore.
Construcción de imágenes Docker.
Ejecución y verificación de contenedores.
Publicación de puertos.
Comprobación de Swagger.
Buenas prácticas de seguridad y revisión de logs.

Estado: la imagen buenorigen-backend:qa se construyó correctamente y el contenedor de QA se ejecutó tanto localmente como en la VM de Oracle Cloud.

Despliegue

La página Despliegue describe la infraestructura utilizada para ejecutar BuenOrigen Backend en Oracle Cloud.

Incluye:

Acceso a la máquina virtual mediante SSH.
Actualización del código desde GitHub.
Ejecución de contenedores en la VM.
Configuración de puertos y reglas de ingreso.
Verificación de disponibilidad de la API y Swagger.
Diagnóstico, seguridad y procedimientos de actualización.

Estado: el contenedor de QA se ejecutó en Oracle Cloud y Swagger respondió correctamente desde la VM y desde un navegador externo.

Relación entre funcionalidades y dominios

Área de la Wiki	Funcionalidades principales	Dominio relacionado
Header	Búsqueda de Productos	Productos
Header	Favoritos	Favoritos
Header	Perfil de Usuario	Usuarios
Header	Carrito de Compras	Carrito
Página de Inicio	Ofertas, Populares y Nuevos Productos	Productos
Página de Inicio	Nuestros Emprendedores	Emprendedores
Página de Inicio	Artículos del Blog	Artículos
Emprendedores	Directorio, Perfil y Productos	Emprendedores / Productos
Página de Subcategoría	Subcategorías y productos asociados	Subcategorías / Productos
Detalle de Producto	Detalle, Huella Verde, Valoraciones y Relacionados	Productos
Cuenta de Usuario	Perfil y operaciones privadas	Usuarios y dominios relacionados
Cuenta de Emprendedor	Perfil, Productos, Ventas y Dashboard	Emprendedores y dominios relacionados

Esta tabla representa relaciones funcionales. No implica necesariamente que cada dominio disponga de un módulo independiente implementado.

Navegación de la Wiki

Funcionalidades

Header

Página de Inicio

Emprendedores

Página de Subcategoría

Detalle de Producto

Cuenta de Usuario

Cuenta de Emprendedor

Arquitectura Backend

Contratos de API

Desarrollo

Infraestructura y Despliegue

Mantenimiento de la documentación

La documentación técnica debe mantenerse coherente con el código de BuenOrigen Backend.

Cuando se incorporen modificaciones que afecten el comportamiento de la API, deben actualizarse las páginas relacionadas, según corresponda.

En particular, se debe procurar la coherencia entre:

Funcionalidades documentadas.
Controllers y services.
Modelos y DTOs.
Endpoints REST.
Documentación OpenAPI/Swagger.
Configuración e infraestructura.

Las funcionalidades identificadas por UX/UI que todavía no dispongan de implementación deberán diferenciarse de las operaciones disponibles en el backend.

La página Endpoints constituye una referencia para consultar la disponibilidad documentada de las operaciones de la API.

Repositorio: BuenOrigen Backend — GitHub