Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/camiloivcode/biblioteca-la-palabra/llms.txt

Use this file to discover all available pages before exploring further.

Biblioteca Popular La Palabra está construida como un sistema full-stack desacoplado: un backend REST en Node.js/Express con Prisma ORM, y un frontend estático generado con Astro. Ambos servicios, junto con MySQL 8 y phpMyAdmin, se orquestan mediante Docker Compose, lo que permite levantar todo el entorno con un solo comando.

​
Estructura del proyecto

El repositorio organiza el código en dos workspaces independientes (backend/ y frontend/) más una carpeta de documentación y los archivos de configuración de Docker en la raíz. 
biblioteca-la-palabra/
├── backend/                        # API Express (CommonJS)
│   ├── prisma/
│   │   ├── schema.prisma           # Modelo de datos
│   │   ├── seed.js                 # Datos de semilla
│   │   └── init.sql                # Inicialización MySQL
│   └── src/
│       ├── server.js               # Entry point
│       ├── app.js                  # Configuración Express
│       ├── config/
│       │   ├── database.js         # Singleton Prisma
│       │   ├── jwt.config.js       # JWT secret/expiración
│       │   └── mailer.js           # Transporter nodemailer
│       ├── controllers/            # Handlers de rutas
│       ├── services/               # Lógica de negocio
│       ├── routes/
│       │   └── index.js            # Montaje de rutas
│       ├── middlewares/
│       │   ├── auth.middleware.js   # Verificación JWT
│       │   ├── role.middleware.js   # Restricción por rol
│       │   ├── error.middleware.js  # Manejador global de errores
│       │   └── validate.middleware.js # Validación express-validator
│       └── utils/
│           ├── ApiResponse.js       # Formato de respuesta
│           └── AppError.js          # Clase de error personalizada
├── frontend/                       # Astro (output static)
│   ├── src/
│   │   ├── layouts/
│   │   │   ├── BaseLayout.astro    # Layout raíz (API_URL, scripts globales)
│   │   │   └── DashboardLayout.astro # Layout interno (sidebar)
│   │   ├── pages/
│   │   │   ├── login.astro
│   │   │   ├── forgot-password.astro
│   │   │   ├── reset-password.astro
│   │   │   ├── register.astro
│   │   │   └── dashboard/          # Páginas internas
│   │   ├── scripts/                # JS del lado cliente
│   │   │   ├── shared.js           # Utilidades globales
│   │   │   ├── api.js              # Cliente HTTP con auto-refresh
│   │   │   └── ...                 # Scripts por módulo
│   │   ├── components/
│   │   │   └── ui/                 # Componentes reutilizables
│   │   └── styles/
│   └── public/                     # Archivos estáticos
├── docs/                           # Documentación
├── docker-compose.yml
└── .env.example

​
Patrón MVC + Servicios

El backend aplica una variante del patrón MVC que extrae toda la lógica de negocio a una capa de servicios independiente. Los controllers se limitan a orquestar la request/response, delegando el trabajo real a los servicios, que a su vez hablan con la base de datos a través de Prisma. 
Ruta → Controller → Service → Prisma → MySQL
                        ↓
                  AppError → error.middleware.js
Cuando una operación viola una regla de negocio o encuentra un error inesperado, el servicio lanza una instancia de AppError. El middleware centralizado error.middleware.js intercepta esta excepción antes de que llegue al cliente, formatea la respuesta de error y gestiona también los códigos de error nativos de Prisma (P2002 constraint única, P2025 registro no encontrado, P2003 clave foránea).

​
Flujo de una request

Cada petición HTTP atraviesa una cadena determinista de capas antes de producir una respuesta:
1

Express recibe la request

El servidor Express en el puerto 4000 acepta la conexión entrante.
2

Middlewares globales

La request pasa por helmet (cabeceras de seguridad), cors (origen permitido configurado por FRONTEND_URL) y morgan (logging HTTP).
3

Validación de ruta

El middleware validate.middleware.js ejecuta las reglas de express-validator definidas para esa ruta. Si hay errores de validación, responde inmediatamente con 400.
4

Middleware de autenticación

Si la ruta requiere auth, auth.middleware.js verifica el JWT del encabezado Authorization: Bearer <token> y adjunta el usuario decodificado en req.user.
5

Controller

El handler del controller recibe (req, res, next), extrae los parámetros necesarios y llama al servicio correspondiente.
6

Service + Prisma

El servicio aplica las reglas de negocio y ejecuta las queries mediante el cliente Prisma contra MySQL.
7

Manejo de errores

Si el servicio lanza un AppError (o cualquier otro error), error.middleware.js lo captura, determina el statusCode adecuado y devuelve { success: false, message }.
8

Respuesta exitosa

Si todo fue bien, el controller llama a ApiResponse.success() (o created() / paginated()) para devolver la respuesta normalizada al cliente.

​
Formato de respuesta estándar

Todas las respuestas exitosas de la API siguen la misma estructura, emitida por la clase ApiResponse: 
{
  "success": true,
  "message": "Operación exitosa",
  "data": { },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5
  }
}
El campo meta solo está presente en respuestas paginadas (ApiResponse.paginated()). Las respuestas de creación omiten meta y retornan HTTP 201. Los errores operacionales (reglas de negocio, validación, auth) y los errores de Prisma se devuelven siempre con este formato: 
{
  "success": false,
  "message": "Descripción del error"
}
Cuando la validación de express-validator falla, el campo opcional errors puede acompañar al mensaje con el detalle de cada campo inválido.

​
Servicios Docker

El archivo docker-compose.yml en la raíz del repositorio define cuatro servicios que arrancan en el orden correcto: primero la base de datos, luego el backend (que ejecuta prisma db push + seed al iniciar) y finalmente el frontend.
ServicioImagen / DockerfilePuerto expuesto
dbMySQL 8.0 (imagen oficial)3307
backendNode 20 Alpine (backend/Dockerfile)4000
frontendNode 20 Alpine (frontend/Dockerfile)3000
phpmyadminphpMyAdmin (imagen oficial)8080
Para levantar todo el stack desde cero: 
cp .env.example .env
docker-compose up --build -d
phpMyAdmin está disponible en http://localhost:8080 una vez levantado el stack. Es útil para inspeccionar el estado de las tablas, verificar datos del seed y depurar queries sin necesidad de conectarse directamente al contenedor MySQL.

Build docs developers (and LLMs) love

Get started for freeTalk to us