FleetFlow AI — Explainer

1. Concepto

FleetFlow AI es un SaaS de optimización de rutas para pymes de logística (e-commerce, distribución local, reparto de alimentos, servicios de campo) con flotas de 5-50 vehículos. Sustituye la planificación manual de rutas por un solver de VRP (Vehicle Routing Problem) que combina paradas de entrega y vehículos disponibles en rutas óptimas por coste y tiempo, ajustables con datos de tráfico en tiempo real.

Problema que resuelve: pymes sin acceso a software de optimización asequible pierden dinero en combustible, tiempo y capacidad de flota mal utilizada.

Monetización: SaaS por niveles — plan FREE (2 vehículos, 50 paradas/mes) y planes de pago por número de vehículos y funcionalidades avanzadas (API de tráfico, analítica extendida). El límite FREE está aplicado en VehicleService y CsvParsingService.

2. Arquitectura

Spring Boot 4.0.4 / Java 25, capas estándar controller → service → repository → model, persistencia JPA (H2 embebido en dev, PostgreSQL listo para producción vía %%INLINE3%% + driver %%INLINE4%%).

controller/    REST endpoints (Auth, Vehicle, DeliveryStop, Route, Analytics)
service/       Lógica de negocio (AuthService, VehicleService, CsvParsingService,
               DeliveryStopService, RouteOptimizationService, AnalyticsService)
repository/    Spring Data JPA repositories, todos filtrados por companyId (tenant)
model/         Entidades JPA: Company, User, Role, Vehicle, DeliveryStop, OptimizedRoute
dto/           Records inmutables para request/response
security/      JWT (JwtService, JwtAuthenticationFilter, CustomUserDetailsService,
               AuthenticatedCompanyResolver)
client/        TrafficApiClient (Feign) — integración con proveedor de tráfico externo
config/        SecurityConfig, FeignConfig (JacksonConfig pre-existente)

Multi-tenancy: cada %%INLINE5%% pertenece a una %%INLINE6%%. Todas las consultas de dominio (vehículos, paradas, rutas) se filtran por company.getId() resuelto desde el JWT autenticado vía AuthenticatedCompanyResolver, aislando datos entre clientes.

Solver VRP (RouteOptimizationService): heurística de dos fases —

1. Clustering de paradas pendientes por vehículo respetando capacidad (capacityKg).
2. Ordenación nearest-neighbor dentro de cada vehículo, usando distancias

traffic-aware (Feign) con fallback a Haversine si el proveedor no responde.

Cada ruta de vehículo se calcula en su propio virtual thread (Executors.newVirtualThreadPerTaskExecutor()), ya que el cálculo es I/O-bound (llamadas al proveedor de tráfico) y paralelizable por vehículo sin coordinación.

Integración de tráfico: %%INLINE12%% es un %%INLINE13%% apuntando a fleetflow.traffic-api.base-url (por defecto TomTom, configurable). Sin credenciales reales, el servicio degrada automáticamente a estimación por fórmula de Haversine — la arquitectura queda lista para conectar una clave de API real en producción.

Seguridad: JWT stateless (jjwt 0.12.6). /api/auth/** es público; todo lo demás requiere Authorization: Bearer <token>. Contraseñas con BCrypt.

3. Endpoints

Método	Path	Descripción	Auth
POST	/api/auth/register	Crea compañía (si no existe) + usuario admin, devuelve JWT	No
POST	/api/auth/login	Autentica y devuelve JWT	No
POST	/api/v1/vehicles	Registra vehículo (placa, capacidad, coste/km)	Sí
GET	/api/v1/vehicles	Lista vehículos del tenant	Sí
POST	%%INLINE21%%	Sube CSV de paradas (%%INLINE22%%)	Sí
GET	/api/v1/stops	Lista paradas del tenant	Sí
POST	/api/v1/routes/optimize	Ejecuta el solver VRP sobre paradas/vehículos pendientes	Sí
GET	/api/v1/analytics/dashboard	Métricas: rutas, distancia, tiempo, ahorro	Sí
GET	/	UI estática (Leaflet) para probar el flujo completo	No

4. Referencias

• Business case: AI Logistics SaaS for Routing and Forecasting Optimization

(https://www.linkedin.com/pulse/ai-saas-2026-building-products-think-weyhc)

• jjwt 0.12.x API: https://github.com/jwtk/jjwt
• Spring Cloud OpenFeign: https://docs.spring.io/spring-cloud-openfeign/reference/
• Leaflet.js: https://leafletjs.com/

5. Análisis de negocio

• ROI directo y medible: cada optimización expone estimatedSavings frente a una

ruta naive, dato que se agrega en el dashboard — argumento de venta cuantificable.

• Nicho desatendido: pymes de 5-50 vehículos no pueden pagar suites enterprise

(ej. soluciones de $50k+/año); FleetFlow AI ofrece un plan FREE de entrada y escalado por número de vehículos, alineado con monetizationAngle.

• Fricción de adopción baja: solo requiere un CSV de paradas y datos básicos de

flota — sin integración compleja con ERPs para el MVP.

• Expansión natural: el TrafficApiClient desacoplado permite añadir proveedores

(Google Maps, TomTom) o forecasting de demanda sin tocar el solver.

6. Cómo ejecutar

cd solutions/2026-07-21-fleetflow-ai
mvn spring-boot:run

La app arranca en http://localhost:8080 con H2 en memoria (autoconfigurado por Spring Boot al detectar el driver H2 sin spring.datasource.url explícito).

Flujo de prueba (UI en /):

1. Registrar compañía/usuario → obtiene JWT (se guarda en localStorage).
2. Añadir 1-2 vehículos (placa, capacidad, coste/km).
3. Subir CSV de paradas con cabecera address,latitude,longitude,demandKg.
4. Pulsar "Run optimization" → rutas dibujadas en el mapa Leaflet.
5. "Refresh metrics" → panel de analítica (distancia, tiempo, ahorro).

Vía curl:

curl -X POST localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"companyName":"Acme Logistics","username":"admin","password":"password123"}'

# usar el token devuelto:
curl -X POST localhost:8080/api/v1/vehicles \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"licensePlate":"1234ABC","capacityKg":500,"costPerKm":0.35}'

curl -X POST localhost:8080/api/v1/stops/upload \
  -H "Authorization: Bearer <TOKEN>" -F "file=@stops.csv"

curl -X POST localhost:8080/api/v1/routes/optimize -H "Authorization: Bearer <TOKEN>"

Producción: activar perfil PostgreSQL definiendo spring.datasource.url, %%INLINE36%% y %%INLINE37%% + credenciales reales del proveedor de tráfico.

---

FinOps Analysis

Estimación de Costos Operativos Mensuales

Para FleetFlow AI, los costos operativos se han desglosado para reflejar el uso típico de una micro-startup SaaS en la nube:

• Tokens LLM (OpenAI): ~$15/mes

* Estimación de ~500,000 tokens/mes, utilizando principalmente %%INLINE38%% para resúmenes y algunas interacciones, con un pequeño porcentaje de %%INLINE39%% para tareas más complejas. Esto incluye la interpretación de algunas reglas o la generación de informes simplificados. El uso directo de LLMs para la optimización de rutas es limitado, apoyándose más en algoritmos heurísticos.

• Infraestructura Cloud (AWS): ~$45/mes

* Compute: ~$30/mes (ej. una instancia t3.small de EC2 para el Spring Boot backend, incluyendo costos de red, almacenamiento EBS y monitoreo básico con CloudWatch). * Base de Datos: ~$15/mes (ej. una instancia db.t3.micro de RDS para PostgreSQL, incluyendo almacenamiento y I/O).

• APIs Externas (Mapas y Tráfico): ~$100/mes

* La integración con APIs de mapas y tráfico (ej. Google Maps Platform para geocodificación y direcciones con tráfico) representa el costo más significativo. Se estima un volumen moderado de llamadas para 20 clientes, incluyendo un margen después de aplicar créditos gratuitos iniciales.

Costo Operativo Mensual Total Estimado: ~$160

Estimación de Ingresos Mensuales

Basado en un modelo de monetización SaaS por niveles, con un plan gratuito y planes de pago por número de vehículos:

• Clientes: Se estima un base inicial de 20 clientes de pago.
• Precio Promedio: Asumiendo un precio promedio de $25/mes por cliente (mezcla de planes básicos y pro).

Ingreso Mensual Estimado: ~$500

Margen de Beneficio

Calculado como ((Ingresos - Costos) / Ingresos) * 100:

($500 - $160) / $500 100 = 68%

Este margen del 68% es saludable para una micro-startup, indicando una buena viabilidad financiera inicial.

Optimizaciones de Costos (FinOps)

Para mantener o mejorar este margen a medida que la startup escala, se recomiendan las siguientes optimizaciones:

1. Optimizar el Uso de APIs de Mapas: Dado que es el mayor costo, explorar proveedores de mapas de menor coste (ej. Mapbox, HERE, o soluciones open-source como OSRM para auto-hosting) y cachear agresivamente los resultados de geocodificación para direcciones de entrega recurrentes. Esto reducirá significativamente las llamadas a APIs de pago.
2. Gestión Eficiente de LLM: Priorizar el uso de modelos de bajo coste como %%INLINE43%% para la mayoría de las interacciones (resúmenes, insights básicos) y reservar modelos más caros (ej. %%INLINE44%%) solo para tareas de muy alto valor que requieran mayor complejidad o precisión. Implementar caché de respuestas para prompts recurrentes o resultados comunes.
3. Ajuste de Infraestructura Cloud: Monitorear de cerca el uso de recursos (CPU, RAM, I/O de DB) para asegurar que las instancias (EC2 %%INLINE45%% y RDS %%INLINE46%%) no estén sobredimensionadas. A medida que el uso se estabilice, considerar planes de ahorro (AWS Savings Plans o Reserved Instances) para reducir el costo de las instancias base.