Skip to content

Agsergio04/Fluster

BranchesTags

Repository files navigation

Fluster

Aplicación web para que empresas PYME de logística controlen y gestionen los costes de Demurrage & Detention (D&D) de contenedores marítimos.

CI Security License: MIT

Tabla de contenidos

  1. ¿Qué es Fluster?
  2. Demo
  3. Características principales
  4. Stack tecnológico
  5. Estructura del proyecto
  6. Inicio rápido
  7. Desarrollo local (sin Docker)
  8. Datos de prueba (seed)
  9. Variables de entorno
  10. Pruebas
  11. Documentación

¿Qué es Fluster?

Las empresas PYME de logística (importadores, transitarios, transportistas) gestionan contenedores marítimos con hojas de cálculo, fotos por WhatsApp y correos dispersos. Cuando un contenedor supera los días libres acordados con la naviera, comienzan a acumularse costes de Demurrage (contenedor en puerto) y Detention (contenedor con el cliente), que pueden alcanzar cientos de euros por día.

Fluster centraliza todo el ciclo de vida del contenedor, calcula automáticamente los costes D&D según tarifas por tramos, y ofrece un semáforo de riesgo visual para actuar antes de que los costes se disparen.

Demo

Entorno URL
Frontend https://fluster-frontend.onrender.com
Backend API https://fluster-vd09.onrender.com
Documentación API (Swagger) https://fluster-vd09.onrender.com/api-docs
Diseño Figma Archivo de diseño
Prototipo interactivo Prototipo navegable
Wireframes Wireframes
Diagrama de flujo (FigJam) Diagrama de Flujo — Fluster
GitHub Projects Tablero de planificación

Características principales

  • Ciclo de vida completo del contenedor — registro de eventos con foto, timestamp y código BIC a lo largo de los estados INACTIVO, PUERTO, CLIENTE y VUELTA_PUERTO.
  • Cálculo automático de D&D — costes calculados en tiempo real mediante tablas de tarifas por tramos configurables por naviera.
  • Semáforo de riesgo visual — indicador verde/naranja/rojo basado en los días libres restantes para anticipar costes.
  • OCR con Tesseract.js — lectura y validación automática del código BIC del contenedor a partir de una foto.
  • Generación de informes PDF — exportación de resumen de costes con jsPDF para cotejar con las facturas de las navieras.
  • Control de acceso por roles — admin, gestor y operador con permisos diferenciados.
  • Documentación interactiva — Swagger UI disponible en /api-docs.
  • Tema claro/oscuro — alternancia de tema persistente en la interfaz.
  • Despliegue con Docker Compose — entorno completo reproducible en un solo comando.

Stack tecnológico

Capa Tecnologías
Frontend React Vite · React Router 7 · Axios · SCSS/ITCSS · Atomic Design
Backend Node.js Express MongoDB API Docs · Mongoose · JWT · Bcrypt · Tesseract.js
Infraestructura Docker · GitHub Actions (CI/CD) · Render (despliegue) · Jest · Vitest + React Testing Library

Estructura del proyecto

Fluster/
├── backend/                # API REST (Express + MongoDB)
│   ├── src/
│   │   ├── routes/         # Definición de endpoints
│   │   ├── controllers/    # Entrada/salida HTTP
│   │   ├── services/       # Lógica de negocio
│   │   ├── models/         # Esquemas de Mongoose
│   │   ├── middlewares/    # Auth, roles, errores
│   │   ├── scripts/        # Seed de datos
│   │   ├── app.js          # App Express (sin arrancar el servidor)
│   │   └── index.js        # Punto de entrada (arranque)
│   ├── tests/              # Tests unitarios y de integración (Jest)
│   └── Dockerfile
├── frontend/               # SPA (React + Vite)
│   ├── src/
│   │   ├── components/     # Atomic Design: átomos, moléculas, organismos
│   │   ├── pages/          # Vistas por ruta
│   │   ├── hooks/          # Hooks reutilizables
│   │   ├── services/       # Cliente HTTP (Axios)
│   │   └── styles/         # ITCSS + SCSS
│   ├── tests/              # Tests Vitest (unitarios) y Playwright (e2e/)
│   ├── nginx/              # Configuración del reverse proxy
│   └── Dockerfile
├── docs/                   # Documentación del proyecto (01–10 + diseño)
├── .github/workflows/      # CI, CD, Docker y escaneo de seguridad
└── docker-compose.yml      # Orquestación de los 3 servicios

Inicio rápido

Requisitos previos: Docker y Docker Compose instalados.

# 1. Clonar el repositorio
git clone https://github.com/Agsergio04/Fluster.git
cd Fluster

# 2. Copiar y configurar las variables de entorno
cp backend/.env.example backend/.env
# Editar backend/.env con los valores correspondientes

# 3. Levantar todos los servicios
docker compose up --build

Una vez iniciado, la aplicación estará disponible en http://localhost (puerto 80, servido por nginx). La API es accesible a través del proxy en http://localhost/api.

Desarrollo local (sin Docker)

Si prefieres ejecutar los servicios directamente (por ejemplo, para desarrollar con recarga en caliente), necesitas Node.js 22+ y una instancia de MongoDB (local o Atlas).

# 1. Clonar el repositorio
git clone https://github.com/Agsergio04/Fluster.git
cd Fluster

# 2. Backend
cd backend
npm ci
cp .env.example .env          # configurar MONGO_URI, JWT_SECRET (y CORS_ORIGIN si aplica)
npm run dev                   # arranca en http://localhost:3000 con recarga (nodemon)

# 3. Frontend (en otra terminal)
cd frontend
npm ci
cp .env.example .env          # configurar VITE_API_URL=http://localhost:3000/api
npm run dev                   # arranca en http://localhost:5173 (Vite)

El frontend de desarrollo (Vite) queda en http://localhost:5173 y llama al backend mediante la variable VITE_API_URL.

Datos de prueba (seed)

El backend incluye scripts para poblar la base de datos sin tener que crear los datos a mano:

cd backend

# Crear un usuario administrador inicial
npm run seed

# Poblar la BD con datos de demostración (usuarios, navieras, clientes,
# contenedores en distintos estados, ciclos y eventos)
npm run seed:datos

Tras npm run seed:datos, la consola muestra las credenciales de los usuarios de ejemplo (admin, gestor y operador) para iniciar sesión.

Variables de entorno

El archivo backend/.env debe contener las siguientes variables:

Variable Descripción Ejemplo
MONGO_URI URI de conexión a MongoDB Atlas mongodb+srv://user:pass@cluster.mongodb.net/fluster
PORT Puerto en el que escucha el servidor Express 3000
JWT_SECRET Clave secreta para firmar los tokens JWT una_clave_secreta_larga_y_aleatoria
CORS_ORIGIN Orígenes permitidos por CORS, separados por comas. Si se omite, se permite cualquier origen (solo recomendable en local) https://fluster-frontend.onrender.com

El archivo frontend/.env debe contener:

Variable Descripción Ejemplo
VITE_API_URL URL base de la API que consume el frontend http://localhost:3000/api

Pruebas

Ámbito Comando Herramienta
Backend (unitarios + integración) cd backend && npm test Jest + mongodb-memory-server + Supertest
Backend (con cobertura) cd backend && npm run test:coverage Jest
Frontend (unitarios) cd frontend && npm test Vitest + React Testing Library
Frontend (end-to-end) cd frontend && npm run test:e2e Playwright

La integración continua (GitHub Actions) ejecuta los tests del backend y la build del frontend en cada push y Pull Request a main y dev.

Documentación

# Documento Descripción
01 Introducción Origen, objetivos, análisis comparativo y alcance del MVP
02 Descripción del sistema Visión general del sistema y sus componentes
03 Instalación Guía de instalación y configuración del entorno
04 Guía de estilos Convenciones de código, SCSS/ITCSS y Atomic Design
05 Diseño Diagrama ER, casos de uso, diagramas de flujo, arquitectura y diseño de la API REST
06 Desarrollo Secuencia de sprints, decisiones técnicas y fragmentos de código representativos
07 Pruebas Estrategia de tests, cobertura y ejecución con Jest (backend) y Vitest (frontend)
08 Despliegue CI/CD con GitHub Actions, configuración de Render y Docker
09 Manual de usuario Guía de uso por rol: admin, gestor y operador
10 Conclusiones Valoración del proyecto, mejoras futuras y aprendizajes

Documentación de recuperación

Contribuir

Las contribuciones son bienvenidas. Consulta la guía de contribución completa para los detalles de entorno, convención de commits y proceso de Pull Request, y respeta el Código de Conducta. En resumen, el flujo de trabajo es:

  1. Crear una rama desde dev con un nombre descriptivo (feat/nombre-feature o fix/descripcion-bug).
  2. Desarrollar y añadir tests si corresponde.
  3. Abrir una Pull Request hacia dev. Los checks de CI (lint + tests) deben pasar antes de hacer merge.
  4. Las releases a producción se realizan mediante PR de dev a main.

Por favor, respeta el estilo de código existente y añade tests para cualquier nueva funcionalidad: Jest en el backend (backend/tests/) y Vitest en el frontend (frontend/tests/).

Los cambios entre versiones se documentan en el CHANGELOG.

Seguridad

El proyecto incorpora medidas de seguridad básicas: autenticación JWT con roles, contraseñas hasheadas con bcrypt, cabeceras HTTP con Helmet, CORS configurable, escaneo de dependencias con Dependabot y de vulnerabilidades con Trivy en CI.

Si descubres una vulnerabilidad, no abras un issue público: sigue la política de seguridad.

Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más información.

About

Gestión de costes de Demurrage & Detention (D&D) de contenedores marítimos para PYMEs de logística.

fluster-frontend.onrender.com

Topics

react nodejs docker express mongodb rest-api swagger scss logistics demurrage detention

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Fluster v1.0.0 Latest
May 22, 2026

Packages

 
 
 

Contributors

Languages