Saltar a contenido

Arquitectura

Visión general

NovaMarket es una plataforma POS distribuida para supermercados y cadenas comerciales a gran escala: múltiples cajas, sedes, usuarios y transacciones concurrentes.

El cliente (Angular) consume una API Gateway; los servicios se registran en Eureka (varias instancias por dominio) y obtienen configuración desde Config Server. La identidad la provee Keycloak (OAuth2/OIDC) para toda la red de puntos de venta.

flowchart TB
    subgraph Cliente
        NG[market-ng :4200]
    end

    subgraph Identidad
        KC[Keycloak :41880]
    end

    subgraph Infra
        GW[Gateway :18080]
        EU[Eureka :18761]
        CFG[Config :18888]
    end

    subgraph Negocio
        RUB[ms-rubro]
        ART[ms-articulo]
        VEN[ms-venta]
        PAG[ms-pago]
    end

    subgraph Mensajería
        KF[Kafka]
    end

    subgraph Observabilidad
        PR[Prometheus]
        LK[Loki]
        GF[Grafana]
    end

    NG -->|OIDC login| KC
    NG -->|Bearer JWT| GW
    GW --> RUB & ART & VEN & PAG
    RUB & ART & VEN & PAG --> EU
    RUB & ART & VEN & PAG --> CFG
    VEN -->|Feign sync| ART & PAG
    VEN -->|orden-eventos| KF
    KF --> PAG
    GW & ART & VEN --> PR
    VEN & PAG & ART --> LK --> GF

Microservicios

Servicio Eureka ID Responsabilidad
ms-rubro ms-rubro Categorías / rubros de productos
ms-articulo ms-articulo Artículos, stock, circuit breaker hacia rubro
ms-venta ms-venta Ventas POS, boletas, publicador Kafka
ms-pago ms-pago Registro de pagos, consumidor Kafka

Infraestructura transversal

Componente Función
Config Server YAML centralizados (infra/config-repo/*-{dev,prod}.yml)
Eureka Descubrimiento; el gateway usa lb://nombre-servicio
Gateway Enrutamiento, CORS, validación JWT (resource server)
Keycloak Login, realm novamarket, roles en claim roles

Flujo de una venta (caja)

sequenceDiagram
    participant UI as Angular POS
    participant KC as Keycloak
    participant GW as Gateway
    participant V as ms-venta
    participant A as ms-articulo
    participant P as ms-pago
    participant K as Kafka

    UI->>KC: Login OIDC
    KC-->>UI: access_token
    UI->>GW: POST /api/v1/ventas + Bearer
    GW->>V: crear venta
    V->>A: validar / descontar stock (Feign)
    V->>P: registrar pago (Feign sync)
    V->>K: publicar orden-eventos
    K->>P: consumir (async, idempotente)
    V-->>UI: boleta

Resiliencia (Circuit Breaker)

ms-articulo consulta categorías en ms-rubro vía OpenFeign. Resilience4j protege la llamada:

  • Instancia: catalogo
  • Fallback: devuelve producto con categoria: null
  • Endpoints: /actuator/circuitbreakers, /actuator/circuitbreakerevents

Seguridad en capas

Capa Mecanismo
Gateway OAuth2 Resource Server — issuer-uri Keycloak
ms-articulo Mismo issuer; POST/PUT/DELETE productos → rol ADMIN
ms-rubro, venta, pago (vía GW) Rutas públicas en gateway para operación POS (configurable)

Detalle en Seguridad.


Entornos

Aspecto DEV PROD
Ejecución MS Maven (spring-boot:run) Docker
Red Docker market-dev-net market-prod-net
Perfil Spring dev prod
Puertos gateway 18080 28082

Ver Puertos y Desarrollo / Producción.