# jeissemi123/paquetes-con-criterio architecture

> Architecture diagram of the GitHub repository jeissemi123/paquetes-con-criterio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeissemi123/paquetes-con-criterio
- Repository: https://github.com/jeissemi123/paquetes-con-criterio

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% C4-L1 Context (vertical)
    %% =========================
    subgraph L1["C4-L1 Context"]
        Producer["External: Event Producer<br/>(edge-camera / upstream)"]:::external
        Operator["External: Operator / QA<br/>(curl / API client)"]:::external

        Service["Package Scan Service<br/>(Node.js + TypeScript + Express)"]:::service

        Producer -->|"POST /events/package-scan"| Service
        Operator -->|"GET /health"| Service
        Operator -->|"POST /events/package-scan"| Service
    end

    %% =========================
    %% C4-L2 Container (vertical)
    %% =========================
    subgraph L2["C4-L2 Container"]
        API["HTTP API (Express)<br/>Routes + Controller"]:::inbound
        App["Application<br/>ProcessPackageScanUseCase"]:::application

        subgraph Stores["Persistence Targets"]
            MemStore["In-memory stores<br/>(default runtime)"]:::datastore
            PG[("Postgres DB<br/>(optional)")]:::datastore
            Schema["Postgres schema.sql<br/>(provided)"]:::note
            Compose["docker-compose<br/>(local Postgres)"]:::note
            Compose -->|"starts"| PG
            Schema -.->|"defines tables for"| PG
        end

        Service -->|"handles HTTP"| API
        API -->|"processPackageScan(input)"| App

        App -->|"idempotency: isProcessed/markProcessed"| MemStore
        App -->|"audit: append(input+decision)"| MemStore
        App -.->|"optional persistence"| PG
    end

    %% =========================
    %% C4-L3 Component (hexagonal)
    %% =========================
    subgraph L3["C4-L3 Component (Hexagonal: Ports & Adapters)"]
        subgraph Inbound["Inbound Adapter (HTTP)"]
            Main["main.ts<br/>(entry point / wiring)"]:::inbound
            HttpServer["httpServer.ts<br/>(Express bootstrap)"]:::inbound
            Routes["routes.ts<br/>(/events/package-scan, /health)"]:::inbound
            Controller["packageScan.controller.ts<br/>(POST /events/package-scan)"]:::inbound

            Main -->|"wire dependencies"| HttpServer
            HttpServer -->|"mount"| Routes
            Routes -->|"dispatch"| Controller
        end

        subgraph ApplicationLayer["Application Layer"]
            UseCase["processPackageScan.usecase.ts<br/>(orchestrator)"]:::application
        end

        subgraph DomainCore["Domain Core (pure)"]
            EntityEvent["PackageScanEvent<br/>(entity)"]:::domain
            EntityDecision["Decision<br/>(entity)"]:::domain

            Normalizer["normalizer.ts<br/>(to cm/kg)"]:::domain
            Validator["validator.ts<br/>(business validation)"]:::domain
            DecisionEngine["decisionEngine.ts<br/>(accepted/with_warnings/rejected)"]:::domain

            Units["units.ts<br/>(value object)"]:::domain
            Reasons["reasons.ts<br/>(decision codes)"]:::domain
        end

        subgraph Ports["Ports (interfaces)"]
            ProcessedPort["processedEventRepository.port.ts<br/>&lt;&lt;port&gt;&gt;"]:::port
            AuditPort["eventAuditRepository.port.ts<br/>&lt;&lt;port&gt;&gt;"]:::port
        end

        subgraph Outbound["Outbound Adapters (persistence)"]
            MemProcessed["processedEventRepository.memory.ts<br/>(in-memory)"]:::adapter
            MemAudit["eventAuditRepository.memory.ts<br/>(in-memory)"]:::adapter
            PGSchema2["schema.sql<br/>(Postgres optional)"]:::adapter
        end

        %% Inbound -> Application
        Controller -->|"DTO (Zod .passthrough())"| UseCase

        %% Application -> Domain
        UseCase -->|"normalize"| Normalizer
        UseCase -->|"validate business rules"| Validator
        UseCase -->|"decide"| DecisionEngine
        DecisionEngine -->|"produces"| EntityDecision
        Normalizer -->|"uses"| Units
        DecisionEngine -->|"uses"| Reasons
        UseCase -->|"creates"| EntityEvent

        %% Application -> Ports
        UseCase -->|"check idempotency"| ProcessedPort
        UseCase -->|"persist audit"| AuditPort

        %% Ports -> Adapters
        ProcessedPort -.->|"implemented by"| MemProcessed
        AuditPort -.->|"implemented by"| MemAudit
        MemProcessed -.->|"optional alt target"| PGSchema2
        MemAudit -.->|"optional alt target"| PGSchema2
    end

    %% =========================
    %% Sequence / Data-flow (happy path + branches)
    %% =========================
    subgraph SEQ["Sequence: POST /events/package-scan"]
        S1["1) Producer sends HTTP POST JSON payload"]:::step
        S2["2) Controller calls UseCase with DTO<br/>(Zod parse, .passthrough() tolerates extras)"]:::step
        S3["3) UseCase checks idempotency by eventId"]:::step
        S4["4) Normalize units to cm/kg"]:::step
        S5["5) Business validation (semantic)"]:::step
        S6["6) DecisionEngine computes Decision<br/>(accepted / with_warnings / rejected + reasons)"]:::step
        S7["7) Append audit (input + decision)"]:::step
        S8["8) Mark eventId processed (if applicable)"]:::step
        S9["9) Respond JSON Decision"]:::step

        B1["Branch: invalid payload -> rejected (invalid_payload)"]:::branch
        B2["Branch: duplicate eventId -> rejected (duplicate_event)"]:::branch
        B3["Branch: invalid dimensions/fields -> rejected (e.g., invalid_dimensions)"]:::branch

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9
        S2 -.->|"parse fails"| B1
        S3 -.->|"already processed"| B2
        S5 -.->|"validation fails"| B3
    end

    %% =========================
    %% Cross-links from sequence to components (kept vertical)
    %% =========================
    S2 -->|"invokes"| Controller
    Controller -->|"calls"| UseCase
    S3 -->|"uses"| ProcessedPort
    S4 -->|"uses"| Normalizer
    S5 -->|"uses"| Validator
    S6 -->|"uses"| DecisionEngine
    S7 -->|"uses"| AuditPort

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click HttpServer "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/api/httpServer.ts"
    click Routes "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/api/routes.ts"
    click Controller "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/api/controllers/packageScan.controller.ts"
    click UseCase "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/application/usecases/processPackageScan.usecase.ts"
    click EntityEvent "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/entities/packageScanEvent.ts"
    click EntityDecision "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/entities/decision.ts"
    click Validator "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/services/validator.ts"
    click Normalizer "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/services/normalizer.ts"
    click DecisionEngine "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/services/decisionEngine.ts"
    click Units "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/valueObjects/units.ts"
    click Reasons "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/domain/valueObjects/reasons.ts"
    click ProcessedPort "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/ports/processedEventRepository.port.ts"
    click AuditPort "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/ports/eventAuditRepository.port.ts"
    click MemProcessed "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/adapters/persistence/memory/processedEventRepository.memory.ts"
    click MemAudit "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/adapters/persistence/memory/eventAuditRepository.memory.ts"
    click PGSchema2 "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/adapters/persistence/postgres/schema.sql"
    click Compose "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/docker-compose.yml"
    click Main "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/src/main.ts"

    %% Tests
    TestE2E["E2E Test<br/>packageScan.e2e.test.ts"]:::test
    TestE2E -->|"calls endpoint"| API
    click TestE2E "https://github.com/jeissemi123/paquetes-con-criterio/blob/main/test/packageScan.e2e.test.ts"

    %% =========================
    %% Styles (colorful + consistent)
    %% =========================
    classDef external fill:#111827,stroke:#E5E7EB,color:#F9FAFB,stroke-width:1px
    classDef service fill:#0B3B5A,stroke:#93C5FD,color:#E0F2FE,stroke-width:1px
    classDef inbound fill:#1D4ED8,stroke:#93C5FD,color:#EFF6FF,stroke-width:1px
    classDef application fill:#6D28D9,stroke:#C4B5FD,color:#F5F3FF,stroke-width:1px
    classDef domain fill:#166534,stroke:#86EFAC,color:#ECFDF5,stroke-width:1px
    classDef port fill:#6B7280,stroke:#D1D5DB,color:#F9FAFB,stroke-width:2px,stroke-dasharray: 6 4
    classDef adapter fill:#C2410C,stroke:#FDBA74,color:#FFF7ED,stroke-width:1px
    classDef datastore fill:#374151,stroke:#9CA3AF,color:#F9FAFB,stroke-width:1px
    classDef note fill:#0F172A,stroke:#94A3B8,color:#E2E8F0,stroke-width:1px,stroke-dasharray: 3 3
    classDef step fill:#0EA5E9,stroke:#BAE6FD,color:#082F49,stroke-width:1px
    classDef branch fill:#B91C1C,stroke:#FCA5A5,color:#FEF2F2,stroke-width:1px,stroke-dasharray: 4 3
    classDef test fill:#7C2D12,stroke:#FDBA74,color:#FFF7ED,stroke-width:1px
```
