pos-system/docs/en/architecture/event-driven-architecture.md

Kiến trúc Hướng Sự kiện

Kiến trúc hướng sự kiện cho giao tiếp bất đồng bộ sử dụng Apache Kafka

Sơ đồ Tổng quan

graph TD
    subgraph "Event Producers"
        IAM[IAM Service]
        Service1[Service A]
    end
    
    subgraph "Event Broker"
        Kafka[Apache Kafka]
        Topics[Topics: user.events, auth.events]
    end
    
    subgraph "Event Consumers"
        Consumer1[Notification Service]
        Consumer2[Audit Service]
    end
    
    IAM -->|Publish| Kafka
    Service1 -->|Publish| Kafka
    Kafka --> Topics
    Topics -->|Subscribe| Consumer1
    Topics -->|Subscribe| Consumer2
    
    style IAM fill:#5E35B1,stroke:#4527A0,color:#ffffff
    style Service1 fill:#5E35B1,stroke:#4527A0,color:#ffffff
    style Kafka fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style Topics fill:#FB8C00,stroke:#EF6C00,color:#ffffff
    style Consumer1 fill:#43A047,stroke:#2E7D32,color:#ffffff
    style Consumer2 fill:#43A047,stroke:#2E7D32,color:#ffffff

Mô tả Kiến trúc

Nền tảng GoodGo triển khai Kiến trúc Hướng Sự kiện (EDA) cho giao tiếp bất đồng bộ giữa microservices.

Important

Trạng thái hiện tại: Event Bus với RabbitMQ/Kafka chưa được triển khai. Hiện tại sử dụng MediatR cho domain events nội bộ trong mỗi service.

Nguyên tắc Cốt lõi:

1. Event-First Design: Mọi thay đổi trạng thái phát ra domain events
2. Loose Coupling: Services giao tiếp qua events (nội bộ hoặc message broker)
3. Eventual Consistency: Chấp nhận inconsistency tạm thời
4. CQRS Pattern: Tách biệt read/write operations với MediatR

Công nghệ Hiện tại:

• MediatR - Domain events nội bộ service
• Entity Framework Core - Domain event dispatch qua DbContext

Công nghệ Planned:

• RabbitMQ + MassTransit - Inter-service events (Roadmap)
• Outbox Pattern - Reliable event publishing

Luồng Sự kiện

sequenceDiagram
    participant Producer as IAM Service
    participant Kafka as Kafka Broker
    participant Consumer as Notification Service
    
    Producer->>Kafka: Publish Event (user.created)
    Kafka->>Consumer: Deliver Event
    Consumer->>Consumer: Process Event
    Consumer-->>Kafka: Acknowledge

Các Bước: Publish → Distribute → Consume → Retry (nếu thất bại) → DLQ (sau retry tối đa) → Acknowledge

Cấu trúc Sự kiện

Domain Events (MediatR - Hiện tại)

// EN: Base domain event interface
// VI: Interface domain event cơ bản
public interface IDomainEvent : INotification
{
    Guid EventId { get; }
    DateTime OccurredOn { get; }
}

// EN: Example domain event
// VI: Ví dụ domain event
public record UserCreatedEvent : IDomainEvent
{
    public Guid EventId { get; } = Guid.NewGuid();
    public DateTime OccurredOn { get; } = DateTime.UtcNow;
    
    public required Guid UserId { get; init; }
    public required string Email { get; init; }
    public required string FirstName { get; init; }
}

// EN: Event handler
// VI: Handler xử lý event
public class UserCreatedEventHandler : INotificationHandler<UserCreatedEvent>
{
    private readonly ILogger<UserCreatedEventHandler> _logger;
    
    public async Task Handle(UserCreatedEvent notification, CancellationToken ct)
    {
        _logger.LogInformation("User created: {UserId}, {Email}", 
            notification.UserId, notification.Email);
        
        // TODO: Send welcome email, create profile, etc.
    }
}

Kafka Topics

graph LR
    UserCreated[user.created<br/>Partitions: 3]
    AuthLogin[auth.login.success<br/>Partitions: 5]
    AuditEvents[audit.events<br/>Partitions: 10]
    
    style UserCreated fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style AuthLogin fill:#43A047,stroke:#2E7D32,color:#ffffff
    style AuditEvents fill:#E53935,stroke:#C62828,color:#ffffff

Quy ước Đặt tên: {domain}.{action}.{version}

Ví dụ:

• user.created.v1
• auth.login.success.v1
• audit.event.logged.v1

Xử lý Lỗi

graph TD
    Event[Event] --> Process[Process]
    Process -->|Success| Ack[Acknowledge]
    Process -->|Failure| Retry[Retry 3x]
    Retry -->|Max Retries| DLQ[Dead Letter Queue]
    DLQ --> Alert[Alert Team]

    style Event fill:#757575,stroke:#616161,color:#ffffff
    style Process fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style Ack fill:#43A047,stroke:#2E7D32,color:#ffffff
    style Retry fill:#FB8C00,stroke:#EF6C00,color:#ffffff
    style DLQ fill:#E53935,stroke:#C62828,color:#ffffff
    style Alert fill:#E53935,stroke:#C62828,color:#ffffff

Chiến lược:

1. Retry với exponential backoff (100ms → 200ms → 400ms)
2. Tối đa 3 lần thử
3. Chuyển sang DLQ sau retry tối đa
4. Xem xét thủ công và xử lý lại

Bối cảnh Hệ thống

C4Context
    title Sơ đồ Bối cảnh Event-Driven Architecture
    
    System(iam, "IAM Service", "Event producer")
    System(service_a, "Service A", "Event producer")
    System(notification, "Notification Service", "Event consumer")
    System(audit, "Audit Service", "Event consumer")
    
    System_Ext(kafka, "Apache Kafka", "Event streaming platform")
    System_Ext(registry, "Schema Registry", "Schema management")
    System_Ext(monitoring, "Monitoring", "Kafka metrics & alerts")
    
    Rel(iam, kafka, "Publishes events", "Kafka Protocol")
    Rel(service_a, kafka, "Publishes events", "Kafka Protocol")
    Rel(kafka, notification, "Delivers events", "Kafka Protocol")
    Rel(kafka, audit, "Delivers events", "Kafka Protocol")
    Rel(kafka, registry, "Validates schemas", "HTTP")
    Rel(kafka, monitoring, "Sends metrics", "JMX")

Mô tả Các Thành phần:

• Producers: IAM Service và các services khác publish domain events
• Kafka: Event broker trung tâm, quản lý topics và partitions
• Consumers: Notification và Audit services consume events
• Schema Registry: Quản lý và validate Avro schemas
• Monitoring: Thu thập metrics từ Kafka cluster

Đặc điểm Hiệu suất

Chỉ số	Mục tiêu	Ghi chú
Event Publish Latency (P95)	< 10ms	Fire-and-forget, async
Event Delivery Latency (P95)	< 100ms	End-to-end from publish to consume
Throughput	10,000 events/s	Per topic, scalable with partitions
Consumer Lag	< 1000 messages	Per partition, monitored
Event Size	< 1MB	Recommended max size
Retention	7 days	Default, configurable per topic
Replication Factor	3	For fault tolerance

Tối ưu hóa Hiệu suất:

• Batch Publishing: Group multiple events để giảm network overhead
• Compression: Sử dụng Snappy hoặc LZ4 compression
• Partitioning: Phân chia topics thành multiple partitions cho parallel processing
• Consumer Groups: Multiple consumers trong cùng group để scale horizontally
• Async Publishing: Fire-and-forget pattern, không block request handlers

Cân nhắc Bảo mật

Mã hóa Sự kiện:

• TLS in-transit cho tất cả Kafka connections
• Optional payload encryption cho sensitive data
• End-to-end encryption với custom encryption layer

Kiểm soát Truy cập:

• Kafka ACLs (Access Control Lists) per topic
• SASL/SCRAM authentication cho producers và consumers
• Separate credentials cho mỗi service
• Principle of least privilege - chỉ grant quyền cần thiết

Xác thực Schema:

• Avro schemas trong Schema Registry
• Schema evolution với backward/forward compatibility
• Reject events không match schema

Kiểm toán:

• Log tất cả event publishes và consumes
• Correlation IDs để trace event flow
• Retention policy cho audit logs (7 years)

Lưu trữ Dữ liệu:

• Default 7 days retention
• Configurable per topic
• Automatic deletion sau retention period
• Compliance với GDPR (right to erasure)

Triển khai

graph TD
    subgraph "Kafka Cluster"
        subgraph "Brokers"
            Broker1[Kafka Broker 1<br/>Leader for partitions 0,3,6]
            Broker2[Kafka Broker 2<br/>Leader for partitions 1,4,7]
            Broker3[Kafka Broker 3<br/>Leader for partitions 2,5,8]
        end
        
        subgraph "Coordination"
            ZK[Zookeeper Ensemble<br/>3 nodes]
        end
        
        Broker1 --> ZK
        Broker2 --> ZK
        Broker3 --> ZK
    end
    
    subgraph "Producers"
        IAM[IAM Service]
        ServiceA[Service A]
    end
    
    subgraph "Consumers"
        Notification[Notification Service<br/>Consumer Group: notifications]
        Audit[Audit Service<br/>Consumer Group: audit]
    end
    
    IAM --> Broker1
    IAM --> Broker2
    IAM --> Broker3
    
    ServiceA --> Broker1
    ServiceA --> Broker2
    ServiceA --> Broker3
    
    Broker1 --> Notification
    Broker2 --> Notification
    Broker3 --> Notification
    
    Broker1 --> Audit
    Broker2 --> Audit
    Broker3 --> Audit
    
    style Broker1 fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style Broker2 fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style Broker3 fill:#1E88E5,stroke:#1565C0,color:#ffffff
    style ZK fill:#8E24AA,stroke:#7B1FA2,color:#ffffff
    style IAM fill:#5E35B1,stroke:#4527A0,color:#ffffff
    style ServiceA fill:#5E35B1,stroke:#4527A0,color:#ffffff
    style Notification fill:#43A047,stroke:#2E7D32,color:#ffffff
    style Audit fill:#43A047,stroke:#2E7D32,color:#ffffff

Chiến lược Triển khai

Cấu hình Kafka Cluster:

• Brokers: 3 brokers minimum (5 for production)
• Replication Factor: 3 (for fault tolerance)
• Min In-Sync Replicas: 2 (ensure data durability)
• Partitions: 3-10 per topic (based on throughput needs)
• Zookeeper: 3-node ensemble (for coordination)

Phân bổ Tài nguyên:

Component	CPU	Memory	Disk
Kafka Broker	2 cores	4GB RAM	100GB SSD
Zookeeper	1 core	2GB RAM	20GB SSD
Schema Registry	500m	1GB RAM	10GB

Cấu hình Topic:

user.created:
  partitions: 3
  replication-factor: 3
  retention-ms: 604800000  # 7 days
  compression-type: snappy

auth.login.success:
  partitions: 5
  replication-factor: 3
  retention-ms: 604800000
  compression-type: snappy

audit.events:
  partitions: 10
  replication-factor: 3
  retention-ms: 220752000000  # 7 years
  compression-type: lz4

Tính Sẵn sàng Cao:

• Multiple brokers với partition replication
• Automatic leader election khi broker fails
• Consumer group rebalancing
• Monitoring và alerting cho broker health

Giám sát & Khả năng quan sát

Chỉ số Chính

Kafka Broker Metrics:

• kafka_server_brokertopicmetrics_messagesinpersec - Messages in/sec
• kafka_server_brokertopicmetrics_bytesinpersec - Bytes in/sec
• kafka_server_brokertopicmetrics_bytesoutpersec - Bytes out/sec
• kafka_controller_kafkacontroller_activecontrollercount - Active controller
• kafka_server_replicamanager_underreplicatedpartitions - Under-replicated partitions

Consumer Metrics:

• kafka_consumer_fetch_manager_records_lag_max - Max consumer lag
• kafka_consumer_fetch_manager_records_consumed_rate - Records consumed/sec
• kafka_consumer_coordinator_commit_latency_avg - Commit latency

Producer Metrics:

• kafka_producer_record_send_total - Total records sent
• kafka_producer_record_error_total - Total send errors
• kafka_producer_request_latency_avg - Request latency

Application Metrics:

// Custom metrics cho event processing
const eventPublished = new Counter({
  name: 'events_published_total',
  help: 'Total events published',
  labelNames: ['event_type', 'topic']
});

const eventConsumed = new Counter({
  name: 'events_consumed_total',
  help: 'Total events consumed',
  labelNames: ['event_type', 'topic', 'consumer_group']
});

const eventProcessingDuration = new Histogram({
  name: 'event_processing_duration_seconds',
  help: 'Event processing duration',
  labelNames: ['event_type'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5]
});

Quy tắc Cảnh báo:

# High consumer lag
- alert: HighConsumerLag
  expr: kafka_consumer_fetch_manager_records_lag_max > 10000
  for: 5m
  severity: warning
  annotations:
    summary: "High consumer lag detected"
    description: "Consumer lag is {{ $value }} messages"

# Broker down
- alert: KafkaBrokerDown
  expr: kafka_server_kafkaserver_brokerstate != 3
  for: 1m
  severity: critical
  annotations:
    summary: "Kafka broker is down"

# Under-replicated partitions
- alert: UnderReplicatedPartitions
  expr: kafka_server_replicamanager_underreplicatedpartitions > 0
  for: 5m
  severity: warning
  annotations:
    summary: "Under-replicated partitions detected"

# Offline partitions
- alert: OfflinePartitions
  expr: kafka_controller_kafkacontroller_offlinepartitionscount > 0
  for: 1m
  severity: critical
  annotations:
    summary: "Offline partitions detected"

Dashboards:

• Kafka Cluster Overview (brokers, topics, partitions)
• Producer Performance (throughput, latency, errors)
• Consumer Performance (lag, throughput, errors)
• Topic Metrics (messages/sec, bytes/sec, retention)

Logging:

// Structured logging cho events
logger.info('Event published', {
  eventId: event.eventId,
  eventType: event.eventType,
  topic: 'user.created',
  correlationId: event.correlationId
});

logger.info('Event consumed', {
  eventId: event.eventId,
  eventType: event.eventType,
  topic: 'user.created',
  consumerGroup: 'notifications',
  processingTime: duration
});

Tài liệu Liên quan

• System Design - Kiến trúc tổng thể
• IAM Architecture - Triển khai Event sourcing

---

Cập nhật Lần cuối: 2026-01-14
Tác giả: GoodGo Architecture Team

Mẹo Nhanh

Bảng Màu Mermaid

Loại Node	Màu Nền	Màu Viền	Màu Chữ	Sử dụng
Core/Broker	#1E88E5 (Blue)	#1565C0	#ffffff	Kafka Brokers, Main Components
Topic/Data	#FB8C00 (Orange)	#EF6C00	#ffffff	Topics, Queues, Data Stores
Success/Safe	#43A047 (Green)	#2E7D32	#ffffff	Successful flows, Safe states
Error/Danger	#E53935 (Red)	#C62828	#ffffff	Errors, DLQ, Critical issues
Coordination	#8E24AA (Purple)	#7B1FA2	#ffffff	Zookeeper, Orchestrators

Các Chỉ báo Trực quan

• 🔄 Retry Loop: Chỉ báo thử lại tự động
• ⚠️ DLQ/Warning: Đường dẫn xử lý lỗi
• 📝 Log/Audit: Điểm ghi log
• 🔐 Lock/Auth: Kiểm tra bảo mật