En muchas bibliotecas universitarias todavía se controlan los préstamos en cuadernos, las multas se calculan a mano y los catálogos viven en hojas de cálculo dispersas. El resultado: libros perdidos, multas mal cobradas, lectores frustrados.

Quisimos resolver un problema concreto: que cualquier estudiante pueda buscar, reservar y prestar libros desde su celular, mientras el bibliotecario tiene control total y trazabilidad de cada movimiento.

Cada préstamo recorre un camino claro. El lector busca un libro y lo solicita; el bibliotecario aprueba y asigna un ejemplar físico; el lector lo usa por catorce días y lo devuelve. Si se atrasa, el sistema genera la multa de manera automática. Cada paso queda registrado en la auditoría.

• Lector — busca, solicita, retira, devuelve y, si aplica, paga la multa.
• Sistema — valida disponibilidad, calcula vencimientos y genera multas.
• Bibliotecario — aprueba solicitudes, asigna ejemplares y procesa devoluciones.

Separamos la aplicación en tres capas independientes que se comunican por contratos bien definidos. Cada capa puede evolucionar sin romper a las otras.

• Presentación — React. Lo único que sabe es cómo mostrar datos y cómo enviar peticiones HTTP. Ignora todo lo demás.
• Aplicación — Controllers + Services en .NET. Recibe peticiones, valida, orquesta lógica de negocio y devuelve respuestas.
• Datos — Entity Framework Core + PostgreSQL. Persistencia, consultas y migraciones. El esquema vive acá.

El modelo nació de las entidades del dominio real: libros, autores, categorías, ejemplares físicos, usuarios, préstamos, reservas, multas. Cada relación tiene sentido en el negocio.

• Libro → tiene muchos Ejemplares
• Préstamo conecta Usuario + Ejemplar
• Reserva tiene cola con posicionCola
• Multa deriva de un Préstamo vencido
• AuditLog registra TODO (append-only)

El backend es una API REST construida con ASP.NET Core sobre .NET 10, la versión más reciente y soportada a largo plazo. Está organizado en cuatro capas internas, todas dentro del mismo proyecto.

• Controllers — exponen los endpoints HTTP. Validan input y delegan al service correspondiente.
• Services — la lógica de negocio. Calculan multas, gestionan colas de reserva, orquestan préstamos.
• DbContext — el puente con PostgreSQL. Las migraciones se ejecutan automáticamente al arrancar.
• DTOs — modelos de transporte. Nunca exponemos entidades directas al cliente.

El backend no guarda sesiones. Cada petición protegida lleva un JSON Web Token firmado por el servidor en su header. El token contiene el ID y el rol del usuario, y expira a las 8 horas.

• Login — el usuario envía email + password. El servidor compara con BCrypt y, si coincide, emite un JWT firmado con HMAC-SHA256.
• Storage — el frontend guarda el token en localStorage.
• Cada petición — Axios agrega Authorization: Bearer <token>.
• Validación — un middleware verifica firma + expiración antes de llegar al controller.
• Roles — atributos [Authorize(Roles)] protegen los endpoints sensibles.

// Login flow
POST /api/auth/login
{
  "email": "lector@test.com",
  "password": "Lector123!"
}

// 200 OK
{
  "token": "eyJhbGciOiJIUzI1...",
  "user": {
    "id": 7,
    "nombre": "Maria Garcia",
    "rol": "Lector"
  }
}

// Peticiones siguientes
GET /api/prestamos
Authorization: Bearer eyJhbGciOiJIUzI1...

El frontend es una Single Page Application escrita en React 18 con Vite como bundler. Todo el routing es en cliente con React Router. La comunicación con el backend pasa por Axios.

• Componentes — pequeños, reutilizables, con props tipadas. Cada pantalla es una page; cada bloque visual es un componente.
• Estado global — Context API para autenticación. useAuth() expone el usuario actual, el token y la función de logout.
• Estado local — useState / useEffect en cada page.
• Servicios — capa services/ que envuelve Axios. Centraliza interceptores y manejo de errores.
• Routing — rutas públicas, privadas y de admin con componente ProtectedRoute.

// src/pages/CatalogPage.jsx
import { useState, useEffect } from 'react';
import { fetchBooks } from
  '../services/catalogService';

export default function CatalogPage() {
  const [books, setBooks] = useState([]);
  const [filters, setFilters] = useState({
    search: '',
    categoriaId: ''
  });

  useEffect(() => {
    fetchBooks(filters).then(setBooks);
  }, [filters]);

  return (
    <Layout>
      <Filters value={filters} onChange={setFilters} />
      <BookGrid books={books} />
    </Layout>
  );
}

La interfaz usa una paleta cálida con tonos pastel: lavanda como primario, durazno y menta como acentos, sobre un fondo crema. La tipografía es Plus Jakarta Sans para que se sienta moderna pero seria.

• Componentes reutilizables — BookCard, PageHeader, DataCard, StatusMessage.
• Portadas reales de libros — pedimos las tapas a la API pública de Open Library por ISBN; si no encuentra, caemos a Unsplash por categoría; si todo falla, mostramos un gradiente pastel con iniciales.
• Responsive — diseño mobile-first. Funciona en celular, tablet y escritorio sin recargar layout.

Cualquier visitante puede buscar libros, ver detalles y revisar disponibilidad. La búsqueda es por texto libre (título, autor, ISBN), con filtros por categoría y disponibilidad.

• Búsqueda en tiempo real
• Filtros por autor, categoría, formato
• Ordenamiento (A-Z, por año, por disponibilidad)
• Paginación cliente-servidor
• Tapas reales desde Open Library

La página de detalle muestra la sinopsis, autor, categoría, año, ISBN, editorial, formato y ubicación física. Si hay ejemplares disponibles, el botón es Solicitar préstamo; si no, es Reservar.

• Información completa del libro
• Lista de ejemplares físicos disponibles
• Acción adaptativa según disponibilidad
• Si no hay sesión, redirige a login

Al iniciar sesión, el lector ve su panel personal con tres tarjetas resumen: préstamos activos, reservas pendientes y multas por pagar.

• Préstamos activos (máximo 3)
• Reservas con cuenta regresiva
• Total de multas en pesos dominicanos
• Acceso rápido a cada sección

El lector ve todos sus préstamos con estado, ejemplar asignado y fecha de vencimiento. Si está activo, puede renovar. Si vence, se genera multa automática.

• Estados: Pendiente, Activo, Devuelto, Vencido, Renovado
• Renovación con un clic
• Fechas de devolución calculadas (14 días estándar)
• Multa automática por retraso (RD$50 por día)

Cuando todos los ejemplares de un libro están prestados, el lector se anota en la cola. El sistema le asigna posición y, cuando llega su turno, le da 48 horas para retirarlo.

• Posición en cola visible
• Notificación cuando se asigna el ejemplar
• 48 horas para retirar antes de pasar al siguiente
• Cancelable desde el panel

Las multas se calculan automáticamente al devolver un préstamo vencido. El usuario ve el detalle y puede iniciar un pago simulado (no se conecta a un banco real; es una pasarela de demostración con recibos y referencias generadas).

• Cálculo automático por días de retraso
• Pasarela simulada con aprobación/rechazo
• Historial de intentos de pago
• Recibo con número de referencia

El dashboard de administrador muestra de un vistazo el pulso de la biblioteca: cantidad de libros, usuarios, préstamos activos, vencidos, reservas y multas pendientes.

• Seis KPIs principales en tarjetas pastel
• Top libros más prestados
• Usuarios más activos
• Préstamos por mes (gráfico de barras)
• Categorías populares

El administrador puede ver todos los usuarios registrados, su rol (lector o administrador) y su estado (activo o inactivo). Puede activar o desactivar cuentas con un clic.

• Lista completa con búsqueda
• Roles: Lector, Administrador
• Activación/desactivación con confirmación
• Auditoría: cada cambio queda registrado

El bibliotecario gestiona el catálogo desde acá: agrega libros nuevos, define autores y categorías, edita la información existente o elimina entradas (con confirmación destructiva).

• Tres formularios paralelos
• Validación servidor + cliente
• Confirmación antes de borrar
• Stock inicial al crear

El corazón operativo del sistema. Cuando un lector solicita un préstamo, queda en estado pendiente. El bibliotecario revisa la solicitud, asigna un ejemplar físico disponible y aprueba.

• Solicitudes pendientes de aprobación
• Préstamos activos (con devolución)
• Reservas listas para retirar
• Asignación de ejemplar físico

El sistema distingue entre libro (la entrada del catálogo) y ejemplar (la copia física). Cada ejemplar tiene su código único, estado y ubicación en la biblioteca.

• Códigos únicos por ejemplar
• Estados: Disponible, Prestado, Reservado
• Tipo: Físico o Digital
• Ubicación: estante físico

La auditoría es append-only: una vez que un evento entra, nadie puede borrarlo ni modificarlo. Es la garantía de trazabilidad para la institución.

• Quién hizo la acción
• Qué entidad cambió
• Cuándo (con timestamp)
• Resultado (éxito o fallo)

Cada componente del sistema corre en un contenedor Docker aislado. Una sola red interna los conecta. Ningún puerto está abierto al exterior — el acceso es exclusivo a través del túnel.

• postgres — base de datos con volumen persistente
• backend — ASP.NET con build multi-stage (sdk → runtime)
• frontend — Vite build sobre nginx alpine
• cloudflared — el túnel hacia Cloudflare

# docker-compose.prod.yml
services:
  postgres:
    image: postgres:16-alpine
    volumes: [biblioteca_postgres_data:/var/lib/postgresql/data]

  backend:
    build: { dockerfile: backend/Dockerfile }
    depends_on:
      postgres: { condition: service_healthy }

  frontend:
    build: { dockerfile: frontend/Dockerfile }

  cloudflared:
    image: cloudflare/cloudflared:latest
    environment:
      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}

networks:
  biblioteca: { driver: bridge }

El servidor está en una PC vieja en casa. No abrimos puertos del router. No pagamos hosting. Cloudflare Tunnel actúa como puente: el agente cloudflared abre conexiones salientes hacia los edges de Cloudflare. Cuando alguien visita nuestro dominio, Cloudflare manda la petición por el túnel.

• Cero puertos abiertos en el router
• HTTPS automático con certificado de Cloudflare
• IP pública oculta — Cloudflare es la cara
• Sobrevive a cambios de IP del ISP
• Protección DDoS incluida en el plan Free

Cada vez que se modifica el código, los tests se ejecutan automáticamente. Si algo se rompe, lo sabemos antes de que un usuario lo descubra. Es la red de seguridad del proyecto.