Recomendaciones de arquitectura — Reimplementación ArcorTruck BackOffice

Este documento propone una arquitectura performante, mantenible y visualmente alineada a Material Design para reemplazar el BackOffice web descrito en el manual v2, preservando capacidades: autenticación, administración móvil (preparación de datos), reportes tabulares con exportación, tablero operativo, mapas con Google Maps y configuración técnica sensible.

1. Principios de diseño

1. Separación clara UI / API / datos: el navegador no conoce credenciales de base de datos ni API keys; solo el backend.
2. Material Design como contrato de UX: un solo sistema de diseño (tokens, elevación, tipografía, componentes) para reducir deuda de UI.
3. Dominio explícito: reparto, cobranzas, devoluciones, móvil y configuración como bounded contexts comunicados por APIs versionadas.
4. Operaciones pesadas asíncronas: “Generar todos”, exportaciones masivas y agregaciones de mapas en cola de trabajos con estado visible.

2. Stack recomendado (opción principal)

2.1 Frontend — Angular 19+ con Angular Material (MD3)

Alternativa sólida: React 19 + TypeScript + MUI (Material UI) si el equipo ya está estandarizado en React; misma línea visual Material con ecosistema más amplio de librerías.

No recomendado como primera opción solo por moda: mezclar varias librerías de UI Material-like sin sistema de diseño — genera inconsistencia visual.

2.2 Backend — Go 1.23+ (p. ej. fiber o chi) o Rust (axum)

API: REST JSON versionada (/v1/...) + OpenAPI generado desde código o anotaciones; documentación consumible por el frontend.

Autenticación: OIDC (Keycloak, Entra ID, etc.) o sesiones seguras (cookie HTTP-only) según política del distribuidor; RBAC (roles: operador, supervisor, técnico).

2.3 Datos

• Motor objetivo: PostgreSQL 16+ (si el legado es otro motor, usar capa de migración y/o foreign data wrapper solo como puente temporal).
• Read models para reportes pesados: tablas/materialized views o almacén analítico si el volumen lo exige.
• Cola de trabajos: NATS JetStream, RabbitMQ o Redis Streams para “preparar datos” y exportaciones Excel.

2.4 Mapas

• Google Maps JavaScript API en el cliente con key inyectada por backend (endpoint que entrega configuración no sensible + referencia a secret manager).
• Capa de GeoJSON generada por API para no sobrecargar el cliente con lógica de filtrado masivo.

2.5 Exportación Excel

• Backend: excelize (Go) o calamine/rust_xlsxwriter (Rust) — generar archivo en worker y devolver URL firmada temporal (S3/minio o almacenamiento local acotado).

3. Arquitectura lógica (C4 — nivel contenedor)

flowchart LR
  subgraph client [Navegador]
    SPA[SPA Angular + Material]
  end
  subgraph edge [Borde]
    GW[API Gateway / TLS]
  end
  subgraph core [Backend]
    API[API REST]
    AUTH[Servicio Auth]
    WORK[Workers cola]
  end
  subgraph data [Datos]
    PG[(PostgreSQL)]
    CACHE[(Redis opcional)]
    QUEUE[(Cola mensajes)]
  end
  subgraph ext [Externos]
    GMAPS[Google Maps APIs]
    LEGADO[ERP América / legado vía conector]
  end
  SPA --> GW --> API
  API --> PG
  API --> QUEUE
  WORK --> QUEUE
  WORK --> PG
  WORK --> LEGADO
  SPA --> GMAPS
  API --> AUTH
  API --> CACHE

4. Módulos alineados al manual

5. Seguridad y configuración (crítico por UC-16)

• Nunca persistir passwords de BD ni API keys en texto plano; usar KMS o tabla cifrada con rotación.
• Separar config runtime (URLs públicas, título, logo) de secretos.
• Auditar cada cambio (quién, cuándo, qué campo).
• Rate limiting en login y en endpoints de exportación.

6. Despliegue sugerido

• Contenedores (Docker) + orquestación ligera (Kubernetes solo si ya existe plataforma; si no, Docker Compose en VM o ECS/Fargate).
• CI/CD: lint, tests, análisis SAST, migraciones DB en pipeline.
• Entornos: dev / staging / prod con feature flags para rollout gradual.

7. Roadmap técnico sugerido

1. Fundaciones: auth, layout Material, i18n (es-AR), telemetría.
2. Reportes de mayor valor (cobranza general + reparto por hoja) con paginación y Excel async.
3. Admin móvil con cola y pantalla de estado.
4. Tablero de avance.
5. Mapas con leyenda y popups según especificación funcional ampliada.
6. Configuración endurecida y separación de secretos.

8. Resumen ejecutivo

Esta combinación cumple el objetivo de elegancia profesional Material, rendimiento en servidor y claridad arquitectónica para un backoffice B2B multi-distribuidor.

Documento orientado a la reimplementación descrita por el equipo de producto; validar integraciones reales (América, móvil) con documentación técnica adicional.