Instruction file imported from Bencev04/andrew-microserivce (.github/instructions/kafka-events.instructions.md). Copyright stays with the author.

Kafka Event Conventions

Topics

Event Shape

Every event is a JSON dict with these required fields:

{
    "event_type": "ShiftCreated",       # PascalCase, descriptive
    "shift_id": "uuid-string",          # Primary entity ID
    "timestamp": "2024-04-09T10:30:00", # ISO 8601 from datetime.utcnow().isoformat()
    # ... additional entity-specific fields
}

Event Types by Service

shift-events

• ShiftCreated — includes van_id, driver_id, planned_stock, planned_date
• ShiftLoading, ShiftAwaitingConfirmation, ShiftActivated, ShiftException
• ShiftReturned, ShiftUnderReview, ShiftClosed

van-stock-events

• StockLoaded — van_id, shift_id, items loaded
• StockDeducted — van_id, shift_id, item_name, quantity, current_quantity
• StockRestored — compensating action for failed saga
• WasteRecorded — van_id, shift_id, item_name, waste_quantity

transaction-events

• TransactionCreated — shift_id, van_id, items, total_amount
• TransactionConfirmed — after successful payment
• TransactionVoided — compensating action for failed payment

payment-events

• PaymentProcessed — transaction_id, amount, status=SUCCESS
• PaymentFailed — transaction_id, reason

reconciliation-events

• ReconciliationStarted — shift_id, van_id
• ReconciliationCompleted — shift_id, matched (bool), result

Consumer Subscriptions

Rules

• Always serialize with json.dumps(v, default=str).encode("utf-8")
• Always deserialize with json.loads(v.decode("utf-8"))
• Use group_id="<service-name>-group" for consumers
• Consumer handlers should dispatch on event["event_type"]
• Never publish events before the DB transaction commits