Vista técnica

Arquitectura del MVP

Resumen ejecutivo para equipos técnicos. El detalle completo está en README.md del repositorio.

Capas

┌────────────────────────────────────────────────────────────┐
│  Next.js 14 (App Router)                                   │
│  UI · API Routes · Server Actions                          │
├────────────────────────────────────────────────────────────┤
│  Dominio (src/lib)                                         │
│  pricing · matching · chain-of-custody · payments · storage │
├────────────────────────────────────────────────────────────┤
│  Procesos auxiliares                                       │
│  Socket.io (tracking en vivo)                              │
├────────────────────────────────────────────────────────────┤
│  PostgreSQL + PostGIS · Redis · MinIO/S3                   │
└────────────────────────────────────────────────────────────┘

Decisiones clave

• Monolito Next.js para reducir superficie operativa hasta que el negocio lo justifique. La capa de dominio está aislada — extraer un backend independiente es un movimiento mecánico.
• Socket.io corre como proceso separado y publica/suscribe vía Redis para escalar horizontalmente.
• PostGIS para consultas geo: radio de matching, intersección con rutas de buses.
• Cadena de custodia con hash SHA-256 encadenado y trigger SQL contra UPDATE/DELETE — append-only verificable.

Cadena de custodia (envíos estatales)

Cada evento de tracking calcula:

hash = SHA-256(prev_hash + shipmentId + type + actorId + payload + timestamp)

prev_hash es el hash del evento anterior del mismo envío. El admin estatal recorre la cadena y verifica integridad. La tabla está bloqueada a UPDATE/DELETE vía trigger; cualquier intento de alteración rompe la cadena.

Matching

1. Filtrar transportistas activos con vehículo apto para el tipo de paquete.
2. Filtrar por radio geográfico (PostGIS ST_DWithin).
3. Si la modalidad es via_bus, buscar rutas de buses cuya geometría intersecte el par origen-destino.
4. Rankear: score = w1·distancia + w2·calificación + w3·disponibilidad.
5. Modo subasta: publicar a los top-N y aceptar la mejor oferta.

Multi-tramo

Un envío puede tener N tramos (legs). Caso típico: moto recoge en origen → bus interurbano cubre el trayecto largo → moto entrega en destino. El envío sólo se marca como entregado cuando todos sus legs lo están. El tracking público muestra el leg activo en cada momento.

Stack