How jeissemi123/paquetes-con-criterio works
Tipo y propósito del proyecto (según README + árbol)
Este es un microservicio HTTP (Node.js + TypeScript + Express) que expone un endpoint POST /events/package-scan para recibir eventos de lectura de paquetes, validarlos (Zod), normalizar unidades (cm/kg), aplicar reglas de negocio (warnings/rechazo) y idempotencia por eventId (rechazar duplicados).
Está implementado con arquitectura hexagonal (ports & adapters): dominio puro, aplicación (use case) y adaptadores de infraestructura (repos en memoria y esquema SQL opcional para Postgres).
Qué te dice el file tree sobre la arquitectura (mapeo a “capas”)
Usa este mapeo como base para tu diagrama (es lo más fiel al código):
Entrada / API (Inbound adapter)
• src/api/httpServer.ts (bootstrap del servidor Express)
• src/api/routes.ts (routing)
• src/api/controllers/packageScan.controller.ts (controlador del endpoint)
• src/main.ts (punto de entrada, wiring/DI manual probablemente)
Rol en el diagrama: “HTTP API (Express) / Controller” como adaptador de entrada.
Aplicación (Use case)
• src/application/usecases/processPackageScan.usecase.ts
Rol: orquestación del flujo: validar → normalizar → decidir → idempotencia → persistencias/auditoría → respuesta.
Dominio (core)
• Entidades:
• src/domain/entities/packageScanEvent.ts
• src/domain/entities/decision.ts
• Servicios de dominio:
• src/domain/services/validator.ts (validación semántica de negocio, además de Zod)
• src/domain/services/normalizer.ts (conversión a cm/kg)
• src/domain/services/decisionEngine.ts (reglas accepted/with_warnings/rejected)
• Value Objects:
• src/domain/valueObjects/units.ts
• src/domain/valueObjects/reasons.ts
Rol: “Business rules” y objetos del dominio, independientes de Express/DB.
Puertos (interfaces)
• src/ports/processedEventRepository.port.ts (idempotencia: ya procesado o no)
• src/ports/eventAuditRepository.port.ts (registro/auditoría de eventos/decisiones)
Rol: contratos para infraestructura (outbound).
Adaptadores de persistencia (Outbound adapters)
• Memoria:
• src/adapters/persistence/memory/processedEventRepository.memory.ts
• src/adapters/persistence/memory/eventAuditRepository.memory.ts
• Postgres (opcional):
• src/adapters/persistence/postgres/schema.sql
• docker-compose.yml (Postgres local para simular persistencia)
Rol: “Repositories implementation” conectando los puertos con tecnología concreta.
Tests
• test/packageScan.e2e.test.ts (contrato end-to-end del endpoint)
Qué diagrama dibujar (recomendación: 3 vistas tipo C4 + flujo)
Para ser “lo más preciso”, no intentes un único diagrama gigante. Dibuja 4 artefactos:
Sequence / data-flow del caso POST /events/package-scan – la interacción real
Esto captura arquitectura + comportamiento, que en un servicio de decisión/idempotencia es clave.
Actores / sistemas externos
• Event producer (ej. edge-camera u otro upstream) → envía HTTP POST con JSON
• (Opcional) Operator / QA usando curl o cliente API
• (Opcional) Database: Postgres si se usa docker-compose
Contenedor principal
• Package Scan Service (Node.js/TS/Express)
• Inbound: Express + Controller + Routes
• Application: ProcessPackageScanUseCase
• Domain: Validator + Normalizer + DecisionEngine + Entities/VOs
• Outbound: ProcessedEventRepositoryPort, EventAuditRepositoryPort
• Adapters: Memory repos / Postgres repos (aunque el código mostrado tiene schema, puedes dibujar Postgres como “opcional/alternativo”)
Datastores / persistencia
• Processed Events store (para idempotencia por eventId)
• Event Audit store (para registrar entrada/decisión)
• Si no hay implementación Postgres en código aún, dibújalo como:
• “In-memory repository (default)”
• “Postgres (optional) — schema provided”
En vista “Container”
• Producer → HTTP API (Express) : POST /events/package-scan
• HTTP API → Application (Use case) : processPackageScan(input)
• Use case → Domain services : validate/normalize/decide
• Use case → ProcessedEventRepositoryPort : isProcessed(eventId) / markProcessed(eventId) (o equivalente)
• Use case → EventAuditRepositoryPort : append(...) / saveDecision(...)
• Ports → Adapter (Memory o Postgres)
• Adapter → Datastore (Memory = proceso; Postgres = DB)
En vista “Component” (hexagonal clara)
Dibuja un hexágono o un “core” con:
• Domain (centro): decisionEngine, normalizer, validator, entities, valueObjects
• Application alrededor: ProcessPackageScanUseCase (orquesta)
• Inbound adapter: controller/routes/httpServer
• Outbound adapters: repos memory/postgres
• Ports como interfaces entre application/domain y adapters
Patrones/principios importantes a resaltar en el diagrama (y dónde ponerlos)
• Hexagonal (Ports & Adapters):
• Señala explícitamente que src/ports/* son interfaces y src/adapters/persistence/* son implementaciones.
• Use Case / Application Service:
• processPackageScan.usecase.ts como “orchestrator” (no reglas profundas, solo coordina).
• Idempotencia:
• Un bloque/nota: “Idempotency by eventId → reject duplicates (duplicate_event)”
• Relación directa con ProcessedEventRepositoryPort.
• Validation split:
• Inbound/DTO validation (Zod, tolera extras) en la frontera API/app.
• Business validation en dominio (validator.ts).
• Normalization:
• normalizer.ts convierte unidades a estándar (cm/kg) antes de decidir.
• Decisioning:
• decisionEngine.ts produce Decision { status, reasons, normalizedEvent|null }.
UseCase → ProcessedEventRepositoryPort : check eventId
• Si duplicado → rejected duplicate_event
UseCase → domain/validator.ts : validate dims/required fields
• inválido → rejected invalid_dimensions etc.
UseCase → Controller → Producer : JSON response
Esto evita que el diagrama sea “bonito” pero incorrecto.
Paso B — Luego, sintetiza a C4-L2/L3
• En L2, deja 5–7 cajas máximo.
• En L3, detalla dentro del servicio: controller/usecase/domain services/ports/adapters.
Qué etiquetas, colores y formas usar (para que se lea rápido)
• Formas recomendadas
• Rectángulos: componentes/capas
• Cilindro: datastore (Postgres)
• “Documento”/log: audit trail (si quieres diferenciarlo)
• Interfaces/ports: caja con estereotipo <<port>> o borde punteado
• Colores (consistentes)
• Inbound (API/HTTP): azul
• Application (use case): morado
• Domain (core): verde
• Ports (interfaces): gris con borde punteado
• Outbound adapters (repos): naranja
• Datastores: negro/gris oscuro
• Flechas
• Sólidas: llamadas/flujo principal
• Punteadas: dependencias (ej. controller depende del use case)
• Etiqueta flechas con verbos: validate, normalize, decide, check idempotency, persist audit.
Detalles específicos de ESTE proyecto que no debes omitir
• El endpoint exacto: POST /events/package-scan y healthcheck GET /health (aunque sea secundario).
• Tolerancia a campos extra (Zod .passthrough()): anótalo en la frontera de entrada.
• Razones/códigos (src/domain/valueObjects/reasons.ts) como output de decisión (es parte del contrato).
• Persistencia dual:
• Default: in-memory repositories
• Optional: Postgres (solo schema en repo; dibuja como “optional persistence target”).
• Idempotencia por eventId como regla central.
Plantilla de diagrama (texto guía para el ingeniero)
• External: Producer
• Service: Express API (routes/controller)
• Application: ProcessPackageScanUseCase
• Domain: Normalizer + Validator + DecisionEngine + Entities/VOs
• Ports: ProcessedEventRepositoryPort + EventAuditRepositoryPort
• Adapters: MemoryProcessedEventRepo / MemoryEventAuditRepo (+ Postgres option)
• Datastore: Postgres (optional)
Con eso, tu diagrama va a ser “máximamente” fiel al repo: cada bloque corresponde a una carpeta/archivo real, y las flechas reflejan el flujo descrito en el README.