---
name: Event-Driven Architecture Skill
overview: Tạo skill documentation chi tiết cho Event-Driven Architecture với Apache Kafka, bao gồm patterns cho event publishing/consuming, schema versioning, tích hợp Traefik để expose events qua HTTP (SSE/WebSocket), error handling, observability, và testing patterns phù hợp với GoodGo platform standards.
todos:
  - id: create-skill-file
    content: Tạo file .cursor/skills/event-driven-architecture/SKILL.md với structure cơ bản (header, When to Use, Core Concepts)
    status: completed
  - id: kafka-setup-section
    content: Viết section Kafka Setup & Configuration (infrastructure, client config, connection management)
    status: completed
  - id: publishing-patterns
    content: Viết Event Publishing Patterns section (Publisher class, outbox pattern, best practices)
    status: completed
  - id: consuming-patterns
    content: Viết Event Consuming Patterns section (Consumer class, DLQ, processing strategies)
    status: completed
  - id: schema-versioning
    content: Viết Schema Versioning section (Schema Registry, Avro, evolution strategies)
    status: completed
  - id: traefik-integration
    content: Viết Traefik Integration section (SSE endpoints, WebSocket, routing config)
    status: completed
  - id: error-resilience
    content: Viết Error Handling & Resilience section (error patterns, retries, DLQ, replay)
    status: completed
  - id: observability
    content: Viết Observability section (logging events, metrics, tracing)
    status: completed
  - id: testing-patterns
    content: Viết Testing Patterns section (unit, integration, E2E với test containers)
    status: completed
  - id: best-practices-examples
    content: Viết Best Practices section và Complete Examples (end-to-end flows)
    status: completed
  - id: review-integration
    content: Review và ensure consistency với existing skills, add references, final polish
    status: completed
---

# Event-Driven Architecture Skill Implementation Plan

## Overview

Tạo comprehensive skill documentation cho Event-Driven Architecture patterns sử dụng Apache Kafka làm message broker. Skill này sẽ cover event publishing, consuming, schema versioning, integration với Traefik (SSE/WebSocket), error handling, observability, và testing patterns theo chuẩn GoodGo.

## Architecture Context

**Tech Stack:**

- **Message Broker**: Apache Kafka (high-throughput, streaming)
- **API Gateway**: Traefik (existing) - expose events qua HTTP/SSE/WebSocket
- **Schema Registry**: Confluent Schema Registry (Avro schemas)
- **Services**: Node.js/TypeScript microservices với Express
- **Libraries**: kafkajs (Node.js Kafka client), @goodgo/logger, @goodgo/tracing

**Traefik Integration:**

- Traefik vẫn giữ vai trò API Gateway cho synchronous HTTP/REST
- Thêm support expose event streams qua HTTP endpoints (Server-Sent Events / WebSocket)
- Services publish events vào Kafka, Traefik routes SSE/WebSocket requests tới event streaming endpoints

## Files to Create/Update

### Primary File

- `.cursor/skills/event-driven-architecture/SKILL.md` - Main skill documentation (new)

### Potential Updates (if needed)

- `.cursor/skills/project-rules/SKILL.md` - Update infrastructure section to include Kafka
- `docs/en/architecture/service-communication.md` - Add event-driven communication section
- `docs/vi/architecture/service-communication.md` - Add event-driven communication section

## Detailed Implementation Plan

### Phase 1: Skill File Structure

Tạo file `.cursor/skills/event-driven-architecture/SKILL.md` với structure:

1. **Header Metadata**

   - name: event-driven-architecture
   - description: Event-driven architecture patterns với Kafka

2. **When to Use This Skill** section

   - Khi nào nên dùng event-driven patterns
   - Use cases: async processing, decoupling services, event sourcing, CQRS

3. **Core Concepts**

   - Event-driven vs request-response
   - Kafka fundamentals (topics, partitions, consumer groups)
   - Event schema versioning
   - Traefik integration for event streaming

### Phase 2: Kafka Setup & Configuration

**Topics Covered:**

- Kafka infrastructure setup (docker-compose, Kubernetes)
- KafkaJS client configuration
- Connection management và pooling
- Environment variables (KAFKA_BROKERS, KAFKA_CLIENT_ID, etc.)

**Code Examples:**

```typescript
// Kafka client setup
// Producer configuration
// Consumer configuration
// Connection error handling
```

### Phase 3: Event Publishing Patterns

**Topics:**

- Event structure và naming conventions
- Publisher service pattern
- Transactional publishing (outbox pattern)
- Idempotency keys
- Event correlation IDs
- Publishing best practices

**Patterns:**

- Simple event publisher
- Transactional publisher với outbox pattern
- Batch publishing
- Error handling và retries

**Code Examples:**

```typescript
// EventPublisher class
// Publishing events from services
// Outbox pattern implementation
// Event metadata (correlationId, traceId, timestamp)
```

### Phase 4: Event Consuming Patterns

**Topics:**

- Consumer service patterns
- Consumer groups và partition assignment
- Processing strategies (at-least-once, exactly-once)
- Commit strategies
- Dead letter queue (DLQ) pattern
- Consumer error handling

**Patterns:**

- Simple consumer
- Batch consumer
- Transactional consumer
- DLQ handling
- Retry patterns với exponential backoff

**Code Examples:**

```typescript
// EventConsumer class
// Consumer group management
// Message processing với error handling
// DLQ implementation
```

### Phase 5: Schema Versioning & Registry

**Topics:**

- Schema Registry setup (Confluent)
- Avro schema definitions
- Schema evolution (backward/forward compatible)
- Schema versioning strategy
- Schema validation

**Code Examples:**

```typescript
// Schema definitions
// Schema registry integration
// Schema evolution examples
// Validation patterns
```

### Phase 6: Traefik Integration (SSE/WebSocket)

**Topics:**

- Exposing events qua HTTP endpoints
- Server-Sent Events (SSE) pattern
- WebSocket support (optional)
- Traefik routing configuration
- Authentication/authorization cho event streams
- Rate limiting cho event streams

**Patterns:**

- SSE endpoint implementation
- Event filtering và subscription
- Connection management
- Traefik labels configuration

**Code Examples:**

```typescript
// SSE endpoint implementation
// Event stream service
// Traefik routing config
// Client subscription patterns
```

### Phase 7: Error Handling & Resilience

**Topics:**

- Event publishing failures
- Consumer error handling
- Retry strategies
- Circuit breaker cho Kafka operations
- Dead letter queue management
- Event replay patterns

**Integration với existing skills:**

- Reuse resilience-patterns (circuit breaker, retry)
- Reuse error-handling-patterns (custom errors)

**Code Examples:**

```typescript
// Error handling trong publisher
// Error handling trong consumer
// DLQ processing
// Event replay service
```

### Phase 8: Observability

**Topics:**

- Logging events (structured logging)
- Metrics (events published/consumed, lag, throughput)
- Distributed tracing với OpenTelemetry
- Health checks cho Kafka connectivity
- Monitoring consumer lag

**Integration:**

- Use @goodgo/logger
- Use @goodgo/tracing
- Prometheus metrics

**Code Examples:**

```typescript
// Event logging
// Metrics collection
// Tracing events
// Health check endpoints
```

### Phase 9: Testing Patterns

**Topics:**

- Unit testing publishers/consumers
- Integration testing với Kafka
- Test containers cho local testing
- Mocking Kafka trong tests
- E2E event flow testing

**Code Examples:**

```typescript
// Unit test examples
// Integration test setup
// Test containers usage
// Mocking strategies
```

### Phase 10: Best Practices & Patterns

**Topics:**

- Event naming conventions (`domain.action.version`)
- Topic naming (`domain.entity.action`)
- Partition key selection
- Event ordering guarantees
- Event size limits
- Performance optimization
- Common anti-patterns to avoid

**Examples:**

- Complete event flow example
- Service integration examples
- Real-world use cases

### Phase 11: Documentation Examples

**Complete Examples:**

1. UserCreated event flow (Auth Service → Notification Service)
2. OrderPlaced event với multiple consumers
3. SSE endpoint với filtering
4. Outbox pattern implementation
5. Event replay scenario

**Integration Examples:**

- Service publishing events
- Service consuming events
- Traefik routing SSE endpoints
- Error recovery flows

## Skill File Structure (Detailed Outline)

```markdown
---
name: event-driven-architecture
description: Event-driven architecture patterns with Apache Kafka for GoodGo microservices. Use when implementing async communication, event publishing/consuming, event sourcing, CQRS, or integrating event streams with HTTP endpoints.
---

# Event-Driven Architecture Patterns

## When to Use This Skill
[Use cases và scenarios]

## Core Concepts
[Event-driven fundamentals, Kafka basics, Traefik integration]

## Kafka Setup & Configuration
[Infrastructure, client setup, configuration]

## Event Publishing Patterns
[Publisher patterns, outbox pattern, best practices]

## Event Consuming Patterns
[Consumer patterns, DLQ, processing strategies]

## Schema Versioning
[Schema Registry, Avro, evolution strategies]

## Traefik Integration (SSE/WebSocket)
[Exposing events via HTTP, SSE endpoints, routing]

## Error Handling & Resilience
[Error patterns, retries, DLQ, replay]

## Observability
[Logging, metrics, tracing events]

## Testing Patterns
[Unit, integration, E2E testing]

## Best Practices
[Naming conventions, patterns, anti-patterns]

## Complete Examples
[End-to-end examples]

## Resources
[Links to related skills, docs]
```

## Key Design Decisions

1. **Kafka over RabbitMQ**: User selected Kafka for high-throughput and streaming capabilities
2. **Traefik Integration**: Expose events via SSE/WebSocket through Traefik, keeping Traefik as API Gateway
3. **Schema Registry**: Use Confluent Schema Registry với Avro for schema versioning
4. **Outbox Pattern**: Include outbox pattern for transactional event publishing
5. **Consistency với existing skills**: Reuse patterns từ resilience-patterns, error-handling-patterns, observability-monitoring

## Dependencies & Integration Points

**Existing Skills to Reference:**

- `resilience-patterns` - Circuit breaker, retry patterns
- `error-handling-patterns` - Error classes và handling
- `observability-monitoring` - Logging, metrics, tracing
- `middleware-patterns` - SSE endpoint middleware
- `project-rules` - Coding standards, naming conventions

**Infrastructure:**

- Kafka cluster setup (docker-compose, K8s)
- Schema Registry setup
- Traefik configuration updates

## Acceptance Criteria

- [ ] Skill file created với comprehensive coverage
- [ ] All code examples are working và follow GoodGo patterns
- [ ] Bilingual comments (EN/VI) trong code examples
- [ ] Integration examples với Traefik SSE/WebSocket
- [ ] Error handling patterns documented
- [ ] Observability patterns documented
- [ ] Testing patterns documented
- [ ] References to related skills
- [ ] Complete end-to-end examples
- [ ] Consistent với existing skill format và style