Stack y arquitectura general

Arquitectura de alto nivel

flowchart TB
  subgraph CLIENT[Dispositivos en campo y oficina]
      PWA[App móvil PWA<br/>Angular 18+]
      WEB[App web<br/>Angular 18+]
      CASETA[Vista de caseta<br/>monitor en garita]
  end

  subgraph BACKEND[Backend dedicado por cliente]
      API[API REST<br/>.NET 9 + ASP.NET Core]
      MED[Mediator/CQRS<br/>MediatR + Pipeline Behaviors]
      WORKER[Worker async<br/>procesa eventos Samsara]
      DB[(SQL Server 2022<br/>+ AuditLog inmutable)]
  end

  subgraph EXT[Sistemas externos]
      SAMSARA[Samsara GPS API<br/>flota del cliente]
      TMS[TMS / WMS / ERP<br/>del cliente]
  end

  PWA -- HTTPS + JWT --> API
  WEB -- HTTPS + JWT --> API
  CASETA -- HTTPS + JWT --> API

  API <--> MED
  MED <--> DB

  SAMSARA -- Webhook firmado --> API
  API -- Worker procesa --> WORKER
  WORKER <--> DB

  API -- Webhooks salientes<br/>firmados HMAC --> TMS
  TMS -. API REST de consulta .-> API

  style PWA fill:#1f6feb,color:#fff
  style WEB fill:#1f6feb,color:#fff
  style CASETA fill:#1f6feb,color:#fff
  style API fill:#0a2540,color:#fff
  style DB fill:#28a745,color:#fff
  style SAMSARA fill:#ffc107,color:#212529
  style TMS fill:#79b8ff,color:#0a2540

Vista de alto nivel: dispositivos en campo → backend → integraciones

🔍 Click para ampliar

---

Stack tecnológico

Resumen ejecutivo

Capa	Tecnología	Por qué
Backend	.NET 9 / ASP.NET Core	Estándar de la industria, soporte largo plazo, comunidad amplia.
Base de datos	SQL Server 2022	El cliente ya opera SQL Server en sus otros sistemas.
Frontend	Angular 18+ (PWA)	Funciona offline, instalable como app, sin dependencia de App Store ni Play Store.
GPS	Samsara API	El cliente ya tiene Samsara en su flota.
Hosting	Dedicado por cliente	Independencia total: seguridad, customización, sin riesgo de interferencia.

Detalle técnico

Capa	Tecnología	Justificación
Backend	.NET 9, ASP.NET Core, MediatR (CQRS) con Pipeline Behaviors (ADR-002), Result pattern para errores de negocio (ADR-001)	Errores tipados sin throws; flujos audit/validate/handle separados; testeable end-to-end.
ORM	Entity Framework Core 9 con DbContext per request	Compatible con multi-yard (ADR-008) y particionamiento futuro de tablas históricas (ADR-007).
Base de datos	SQL Server 2022 con filtered unique indexes, audit triggers, particionamiento por yard	Garantiza una asignación activa por trailer por yard; AuditLog inmutable.
Frontend	Angular 18+ con standalone components, Signals, PWA con outbox local (sincronización offline)	Performance, modularidad, instalable sin tienda de apps.
Mensajería	SignalR para tiempo real (eventos de patio entre dispositivos)	Notificaciones push entre operadores en el mismo yard.
Seguridad	JWT + refresh tokens, HMAC para webhooks, RBAC por UserYardAccess	Estándar industria.
Testing	xUnit (BE), Playwright E2E (FE), data-testid obligatorio (ADR-035)	Selectores estables ante refactors de UI.

---

Política de despliegue: deployment-per-customer

Cada cliente recibe su propia instancia separada

Sin multi-tenancy. El YMS no comparte base de datos ni infraestructura entre clientes. Esto significa:

• Independencia operativa total — un cliente no puede afectar el rendimiento de otro.
• Personalización segura — cambios para un cliente no impactan a los demás.
• Cumplimiento de datos — los datos del cliente viven en su infraestructura, sujetos a sus políticas.
• Despliegues simples — actualizaciones por cliente bajo su calendario.

Trade-off aceptado: mayor costo por cliente vs SaaS multi-tenant. Compensado por la robustez operativa exigida por el dominio (patios industriales con compliance aduanal).

---

Patrones arquitectónicos clave

• CQRS + MediatR — comandos y queries separados con pipeline behaviors comunes (validación, audit, logging).
• Result pattern — sin throws para errores de negocio; los handlers retornan Result<T> que el controller traduce a HTTP status.
• Eventos de dominio como records — IDomainEvent con [JsonPolymorphic] + [JsonDerivedType] para deserialización segura.
• PWA con outbox — el frontend móvil persiste operaciones en IndexedDB y las sincroniza al recuperar red, con resolución de conflictos.

Para el detalle de cada patrón y el listado completo de 36 decisiones, ver Decisiones técnicas clave y los ADRs completos.

---

Continúa el recorrido

• Decisiones técnicas clave →
• Integraciones →
• Seguridad y compliance →