Capítulo 14 - Diagramas de Integración y Flujos

Objetivo del Capítulo: Este capítulo presenta los diagramas detallados de integración entre componentes y los flujos de procesos críticos del sistema bancario BP, proporcionando una visión completa de las interacciones entre microservicios, servicios externos y usuarios.

Vista Global de Integraciones

Diagrama de Integración de Servicios Externos

            graph TB
                subgraph "SISTEMA BANCARIO BP"
                    AG[API Gateway
Kong/Nginx]
                    MS1[MS-Pagos
Interbancarios]
                    MS2[MS-Notificaciones]
                    MS3[MS-Autenticación]
                    MS4[MS-Auditoría]
                    MS5[MS-Datos-Cliente]
                    KAFKA[Kafka Event Bus]
                    
                    AG --> MS1
                    AG --> MS2
                    AG --> MS3
                    AG --> MS5
                    MS1 --> KAFKA
                    MS2 --> KAFKA
                    MS3 --> KAFKA
                    MS4 --> KAFKA
                end
                
                subgraph "SERVICIOS EXTERNOS"
                    ACH[ACH Network
Clearinghouse]
                    FCM[Firebase Cloud
Messaging]
                    SMTP[Email Service
SMTP/SendGrid]
                    OAUTH[OAuth Provider
Existente]
                    KYC[KYC/AML Service
Onboarding]
                    FRAUD[Fraud Detection
API]
                    BIO[Biometric Service
AWS Rekognition]
                end
                
                MS1 -.->|HTTPS/REST| ACH
                MS2 -.->|Push| FCM
                MS2 -.->|SMTP| SMTP
                MS3 -.->|OAuth 2.0| OAUTH
                MS5 -.->|REST API| KYC
                MS1 -.->|REST API| FRAUD
                MS3 -.->|REST API| BIO
                
                style AG fill:#667eea,stroke:#333,color:#fff
                style KAFKA fill:#764ba2,stroke:#333,color:#fff
                style ACH fill:#ff9800,stroke:#333,color:#fff
                style FCM fill:#ff9800,stroke:#333,color:#fff
                style FRAUD fill:#f44336,stroke:#333,color:#fff

Proceso Completo con Compensación Automática

Flujo SAGA para Transferencia Interbancaria

            sequenceDiagram
                participant U as Usuario
App Móvil
                participant AG as API Gateway
                participant MP as MS-Pagos
Interbancarios
                participant MC as MS-Datos
Cliente
                participant DB as PostgreSQL
Write DB
                participant K as Kafka
                participant ACH as ACH Network
                participant MN as MS-Notificaciones
                participant MA as MS-Auditoría
                
                U->>AG: POST /transfers/interbank
                AG->>AG: Valida JWT + Rate Limit
                AG->>MP: Enruta solicitud
                
                Note over MP: SAGA STEP 1: Validación
                MP->>MC: GET /balances/{accountId}
                MC-->>MP: Balance: $5,000
                MP->>MP: ✓ Valida saldo suficiente
                
                Note over MP: SAGA STEP 2: Débito
                MP->>DB: BEGIN TRANSACTION
                MP->>DB: Debita $1,000 de cuenta
                MP->>DB: COMMIT
                DB-->>MP: ✓ SUCCESS
                MP->>K: Event: transfer.debited
                
                Note over MP: SAGA STEP 3: Auditoría
                K->>MA: Consume event
                MA->>MA: Log inmutable registrado
                MA-->>K: ACK
                
                Note over MP: SAGA STEP 4: ACH Network
                MP->>ACH: POST /transfers
                ACH-->>MP: ✗ FAILURE (timeout)
                
                Note over MP: SAGA COMPENSATION
                MP->>MP: Inicia rollback
                MP->>DB: BEGIN TRANSACTION
                MP->>DB: Acredita $1,000 (reversa)
                MP->>DB: COMMIT
                MP->>K: Event: transfer.failed
                
                K->>MN: Consume event
                MN->>U: Push: "Transferencia fallida"
                K->>MA: Consume event
                MA->>MA: Log compensación
                
                MP-->>AG: 503 Service Unavailable
                AG-->>U: Error + Retry info

⚠️ Manejo de Compensación

El patrón SAGA garantiza consistencia eventual mediante:

Transacciones locales: Cada microservicio maneja su propia transacción
Eventos de compensación: Si un paso falla, se ejecutan compensaciones automáticas
Estado persistente: Redis mantiene el estado del SAGA para recuperación
Idempotencia: Todas las operaciones son idempotentes (pueden repetirse sin efectos)

Proceso de Login con Biometría y OTP

Autenticación Multi-Factor Completa

            sequenceDiagram
                participant U as Usuario
App Móvil
                participant AG as API Gateway
                participant MA as MS-Autenticación
                participant REDIS as Redis Cache
                participant OAUTH as OAuth Provider
                participant BIO as Biometric Service
                participant SMS as SMS Gateway
                participant DB as PostgreSQL
                
                U->>AG: POST /auth/login
{email, password}
                AG->>MA: Valida credenciales
                MA->>DB: SELECT * FROM users
                DB-->>MA: User found
                MA->>MA: Bcrypt verify password
                
                alt Password válido
                    MA->>REDIS: Guarda sesión temporal
TTL: 5 min
                    MA->>SMS: Envía OTP 6 dígitos
                    MA-->>U: 200 OK
{sessionId, requireMFA: true}
                    
                    U->>U: Usuario ingresa OTP
                    U->>AG: POST /auth/verify-otp
{sessionId, otp}
                    AG->>MA: Valida OTP
                    MA->>REDIS: GET otp:{sessionId}
                    REDIS-->>MA: OTP: 123456
                    MA->>MA: Compara OTP
                    
                    alt OTP correcto
                        MA->>U: Solicita biometría
                        U->>U: FaceID/TouchID
                        U->>AG: POST /auth/biometric
{sessionId, biometricData}
                        AG->>MA: Valida biometría
                        MA->>BIO: Verify biometric
                        BIO-->>MA: ✓ Match 98%
                        
                        MA->>OAUTH: Request JWT tokens
                        OAUTH-->>MA: {accessToken, refreshToken}
                        MA->>REDIS: Guarda refresh token
TTL: 30 días
                        MA->>DB: UPDATE last_login
                        MA-->>U: 200 OK
{accessToken, refreshToken}
                        
                    else OTP incorrecto
                        MA->>REDIS: Incrementa intentos fallidos
                        MA-->>U: 401 Unauthorized
                    end
                    
                else Password inválido
                    MA->>REDIS: Incrementa intentos fallidos
                    MA->>DB: UPDATE failed_attempts
                    MA-->>U: 401 Unauthorized
                end

Event-Driven Architecture en Acción

Procesamiento Asíncrono de Eventos

            graph LR
                subgraph "PRODUCERS"
                    P1[MS-Pagos]
                    P2[MS-Transferencias]
                    P3[MS-Autenticación]
                end
                
                subgraph "KAFKA CLUSTER"
                    T1[Topic: payments
Partitions: 6]
                    T2[Topic: transfers
Partitions: 6]
                    T3[Topic: auth-events
Partitions: 3]
                    T4[Topic: notifications
Partitions: 3]
                    T5[Topic: audit-logs
Partitions: 12]
                end
                
                subgraph "CONSUMERS"
                    C1[MS-Notificaciones
Consumer Group: notif]
                    C2[MS-Auditoría
Consumer Group: audit]
                    C3[MS-Fraud-Detection
Consumer Group: fraud]
                    C4[MS-Analytics
Consumer Group: analytics]
                end
                
                P1 -->|Produce| T1
                P2 -->|Produce| T2
                P3 -->|Produce| T3
                
                T1 --> T4
                T2 --> T4
                T3 --> T4
                
                T1 --> T5
                T2 --> T5
                T3 --> T5
                
                T4 --> C1
                T5 --> C2
                T1 --> C3
                T2 --> C3
                T5 --> C4
                
                style T1 fill:#ff9800,stroke:#333,color:#fff
                style T2 fill:#ff9800,stroke:#333,color:#fff
                style T3 fill:#ff9800,stroke:#333,color:#fff
                style T4 fill:#764ba2,stroke:#333,color:#fff
                style T5 fill:#764ba2,stroke:#333,color:#fff

📌 Ventajas del Event-Driven con Kafka

Desacoplamiento: Los productores no conocen a los consumidores
Escalabilidad: Particiones permiten procesamiento paralelo
Resiliencia: Replicación x3 garantiza durabilidad
Replay: Posibilidad de re-procesar eventos históricos
Throughput: Millones de mensajes por segundo

Stack de Observabilidad Completo

Integración ELK + Prometheus + Grafana + Jaeger

            graph TB
                subgraph "MICROSERVICIOS"
                    MS1[MS-Pagos]
                    MS2[MS-Transferencias]
                    MS3[MS-Autenticación]
                    MS4[MS-Notificaciones]
                end
                
                subgraph "LOGGING - ELK Stack"
                    FB[Filebeat
Log Shipper]
                    LS[Logstash
Processing]
                    ES[Elasticsearch
Storage]
                    KB[Kibana
Visualization]
                end
                
                subgraph "METRICS - Prometheus"
                    PROM[Prometheus
Metrics Server]
                    GRAF[Grafana
Dashboards]
                    AM[AlertManager
Alerts]
                end
                
                subgraph "TRACING - Jaeger"
                    JAEG[Jaeger
Tracing Server]
                    JUI[Jaeger UI
Trace Viewer]
                end
                
                MS1 -->|Logs| FB
                MS2 -->|Logs| FB
                MS3 -->|Logs| FB
                MS4 -->|Logs| FB
                
                MS1 -->|Metrics| PROM
                MS2 -->|Metrics| PROM
                MS3 -->|Metrics| PROM
                MS4 -->|Metrics| PROM
                
                MS1 -->|Traces| JAEG
                MS2 -->|Traces| JAEG
                MS3 -->|Traces| JAEG
                MS4 -->|Traces| JAEG
                
                FB --> LS
                LS --> ES
                ES --> KB
                
                PROM --> GRAF
                PROM --> AM
                
                JAEG --> JUI
                
                style ES fill:#764ba2,stroke:#333,color:#fff
                style PROM fill:#667eea,stroke:#333,color:#fff
                style JAEG fill:#ff9800,stroke:#333,color:#fff

Componente	Función	Métricas Clave	Alertas
Elasticsearch	Almacenamiento de logs indexados	Logs/segundo, Disk usage, Query latency	Disk > 80%, Query > 5s
Prometheus	Métricas y time-series	CPU, Memory, Request rate, Error rate	Error rate > 5%, Memory > 90%
Grafana	Visualización y dashboards	Response time, Throughput, SLA	SLA < 99.9%, Response > 2s
Jaeger	Distributed tracing	Trace duration, Span count, Error traces	Trace > 10s, Error span detected

Integración y Despliegue Continuo

Pipeline GitOps con ArgoCD

            graph LR
                DEV[Developer
Push Code] --> GIT[GitHub
Repository]
                GIT --> GHA[GitHub Actions
CI Pipeline]
                
                GHA --> TEST[Unit Tests
Coverage > 80%]
                TEST --> LINT[Linting
SonarQube]
                LINT --> SEC[Security Scan
Trivy + SAST]
                SEC --> BUILD[Docker Build
Multi-stage]
                BUILD --> PUSH[Docker Push
Harbor Registry]
                
                PUSH --> ARGO[ArgoCD
GitOps]
                ARGO --> K8S_DEV[K8s Dev
Auto Deploy]
                
                K8S_DEV --> SMOKE[Smoke Tests
Health Checks]
                SMOKE --> APPROVE[Manual Approval
QA Team]
                
                APPROVE --> K8S_STAGE[K8s Staging
Auto Deploy]
                K8S_STAGE --> E2E[E2E Tests
Selenium/Cypress]
                E2E --> PERF[Performance Tests
JMeter/k6]
                PERF --> APPROVE2[Manual Approval
DevOps Lead]
                
                APPROVE2 --> K8S_PROD[K8s Production
Blue-Green Deploy]
                K8S_PROD --> MONITOR[Monitor
Grafana/Prometheus]
                
                style GIT fill:#333,stroke:#333,color:#fff
                style ARGO fill:#667eea,stroke:#333,color:#fff
                style K8S_PROD fill:#4caf50,stroke:#333,color:#fff

✅ Etapas del CI/CD Pipeline

Commit Stage: Unit tests, linting, security scanning (5-10 min)
Build Stage: Docker multi-stage build + push to registry (3-5 min)
Deploy DEV: ArgoCD auto-sync a Kubernetes dev (2 min)
Testing Stage: Smoke tests + QA approval (manual)
Deploy STAGING: ArgoCD sync a staging + E2E tests (15-20 min)
Deploy PRODUCTION: Blue-Green deployment con rollback automático (5 min)
Monitoring: Validación de métricas post-deployment (continuo)

Tiempo total de pipeline: ~45-60 minutos desde commit hasta producción

HashiCorp Vault + Kubernetes Integration

Secrets Management con Vault

            sequenceDiagram
                participant POD as K8s Pod
MS-Pagos
                participant SA as ServiceAccount
vault-auth
                participant VAULT as HashiCorp Vault
                participant DB as PostgreSQL
                participant K8S as K8s API
                
                Note over POD: Pod inicia
                POD->>K8S: Lee ServiceAccount token
                K8S-->>POD: JWT token
                
                POD->>VAULT: POST /v1/auth/kubernetes/login
{jwt, role}
                VAULT->>VAULT: Valida JWT con K8s API
                VAULT-->>POD: Vault token (TTL: 1h)
                
                POD->>VAULT: GET /v1/secret/data/database
Header: X-Vault-Token
                VAULT->>VAULT: Valida permisos (policy)
                VAULT-->>POD: {username, password, host}
                
                POD->>DB: Conecta con credenciales
                DB-->>POD: Connection established
                
                Note over POD: Cada 45 min
                POD->>VAULT: POST /v1/auth/token/renew
                VAULT-->>POD: Token renovado
                
                Note over POD: Si token expira
                POD->>VAULT: Re-autenticación completa

Tipo de Secret	Ubicación en Vault	TTL	Rotación
Database Passwords	`secret/database/postgres`	1 hora	Automática cada 24h
API Keys	`secret/external/ach-network`	7 días	Manual con alertas
JWT Signing Keys	`secret/auth/jwt-keys`	30 días	Automática mensual
TLS Certificates	`pki/issue/api-gateway`	90 días	Automática (cert-manager)
Encryption Keys	`transit/keys/customer-data`	365 días	Key rotation sin downtime

Estrategia de Backup y Recuperación

Proceso de Disaster Recovery

        graph TB
            subgraph "REGIÓN PRIMARIA - us-east-1"
                K8S1[Kubernetes Cluster
Primary]
                DB1[PostgreSQL
Master]
                KAFKA1[Kafka Cluster
Primary]
            end
            
            subgraph "BACKUP AUTOMÁTICO"
                VELERO[Velero
K8s Backup]
                PGBACK[pg_basebackup
+ WAL Archiving]
                MINIO[MinIO S3
Backup Storage]
            end
            
            subgraph "REGIÓN SECUNDARIA - us-west-2"
                K8S2[Kubernetes Cluster
Standby]
                DB2[PostgreSQL
Read Replica]
                KAFKA2[Kafka Cluster
Mirror Maker 2]
            end
            
            K8S1 -->|Daily Snapshot| VELERO
            DB1 -->|Streaming Replication| DB2
            DB1 -->|Incremental Backup| PGBACK
            KAFKA1 -->|Mirror Topics| KAFKA2
            
            VELERO --> MINIO
            PGBACK --> MINIO
            
            MINIO -.->|Restore| K8S2
            MINIO -.->|Restore| DB2
            
            style K8S1 fill:#4caf50,stroke:#333,color:#fff
            style K8S2 fill:#ff9800,stroke:#333,color:#fff
            style MINIO fill:#667eea,stroke:#333,color:#fff

Componente	RPO	RTO	Estrategia de Backup
PostgreSQL (Transaccional)	< 5 minutos	< 30 minutos	Streaming replication + WAL archiving a S3
Kubernetes Cluster	< 1 hora	< 2 horas	Velero daily snapshots (ConfigMaps, Secrets, PVs)
Kafka Topics	< 10 minutos	< 1 hora	MirrorMaker 2 a región secundaria + retention 7 días
Redis Cache	< 1 hora	< 15 minutos	RDB snapshots cada 15 min + AOF persistencia
Elasticsearch Logs	< 24 horas	< 4 horas	Snapshot repository a S3 (daily)

⚠️ Plan de Disaster Recovery

Escenario 1: Fallo de región completa (AWS us-east-1)

Detección automática de fallo (health checks cada 30s)
DNS failover a región us-west-2 (Route 53 - 60s)
Promoción de PostgreSQL replica a master (< 5 min)
Activación de Kafka en región secundaria (< 10 min)
Deploy de aplicaciones desde Velero backup (< 30 min)
Total RTO: < 1 hora

Protocolo de Comunicación Interbancaria

Flujo de Transferencia ACH

            sequenceDiagram
                participant MS as MS-Pagos
Interbancarios
                participant GW as ACH Gateway
Clearinghouse
                participant VALID as ACH Validation
Service
                participant SETTLE as Settlement
Engine
                participant BANK as Banco Destino
                
                Note over MS,BANK: FASE 1: Iniciación (Día T)
                MS->>GW: POST /ach/transfer
{amount, routing, account}
                GW->>VALID: Valida routing number
                VALID-->>GW: ✓ Valid bank
                GW->>VALID: Valida account format
                VALID-->>GW: ✓ Valid account
                GW-->>MS: 202 Accepted
{ach_trace_number}
                
                Note over MS,BANK: FASE 2: Procesamiento (Día T+1)
                GW->>GW: Batch processing
(10:00 PM cutoff)
                GW->>SETTLE: Envía lote ACH
NACHA format
                SETTLE->>SETTLE: Valida formato NACHA
                SETTLE->>BANK: Notifica transferencia entrante
                BANK-->>SETTLE: ACK recibido
                
                Note over MS,BANK: FASE 3: Settlement (Día T+2)
                SETTLE->>BANK: Acredita cuenta destino
                BANK->>BANK: Post to account
                BANK-->>SETTLE: Confirmation
                SETTLE-->>GW: Settlement complete
                GW-->>MS: Webhook: transfer.completed
                
                Note over MS,BANK: FASE 4: Notificación
                MS->>MS: Actualiza estado a COMPLETED
                MS->>MS: Genera evento Kafka

📋 Códigos de Transacción ACH (SEC Codes)

PPD (Prearranged Payment): Transferencias persona-a-persona
CCD (Corporate Credit): Transferencias corporativas
WEB (Internet-Initiated): Iniciadas desde web/mobile
TEL (Telephone-Initiated): Iniciadas por teléfono

Tiempo de liquidación estándar: 2-3 días hábiles (T+2 o T+3)

Same-Day ACH: Disponible con fee adicional (liquidación en 24h)

Sistema Externo	Protocolo	Autenticación	Timeout	Retry Policy	Circuit Breaker
ACH Network	HTTPS/REST	API Key + mTLS	30s	3 retries (exp backoff)	5 fallos → open 60s
Firebase Cloud Messaging	HTTP/2 + JSON	OAuth 2.0	10s	2 retries (linear)	10 fallos → open 30s
SendGrid (Email)	HTTPS/REST	API Key	15s	3 retries (exp backoff)	5 fallos → open 60s
OAuth Provider	OAuth 2.0 / OIDC	Client credentials	5s	2 retries (linear)	3 fallos → open 30s
KYC/AML Service	HTTPS/REST	API Key + Signature	20s	No retry (manual)	N/A
Fraud Detection API	HTTPS/REST	Bearer Token	5s	1 retry (fast fail)	10 fallos → open 120s
AWS Rekognition	AWS SDK (HTTP)	AWS SigV4	10s	AWS default (3x)	AWS SDK built-in

✅ Conclusiones del Capítulo 14

Los diagramas de integración presentados demuestran:

Arquitectura robusta: Patrón SAGA para consistencia distribuida
Observabilidad completa: Stack ELK + Prometheus + Jaeger integrados
Seguridad end-to-end: MFA + mTLS + Vault para secrets
Alta disponibilidad: Multi-región con DR automático (RTO < 1h)
CI/CD maduro: GitOps con ArgoCD + pipeline completo
Integraciones estándar: ACH Network con protocolo NACHA
Resiliencia: Circuit breakers + retry policies en todas las integraciones