Skip to content
Santekno.com | Level Up Your Engineering Skills
EN
📖 0%
17 Nov 2026 · 25 min read ·Article 90 / 208
Go

Golang Notification Service: Kafka Consumer, Email Template, Event-Driven

Implementing the Santekno Shop Notification Service. A Kafka consumer for order/payment events, email templates with Go text/template, async processing, and the dead letter queue pattern.

IH
Ihsan Arif
Writer at Santekno · Backend Engineer

A Golang notification service with a Kafka consumer is the final component that closes the event lifecycle of Santekno Shop. This service consumes every event published by the other services via Kafka — the santekno.orders.* and santekno.payments.* topics — and then sends the relevant email notification to the customer. The pattern is clear: event-driven, async, and idempotent so that duplicate events never produce duplicate emails.

In this article we build the Notification Service from scratch: the domain entity, email templates, a Kafka consumer group with manual commit, all the way to a dead letter queue for permanent failures.


10.01 Notification Service Architecture

Before writing any code, it’s important to understand the flow of an event from the producing service until the email reaches the customer. The diagram below maps the journey of an event from the DB transaction all the way to the Kafka offset being committed.

text
 1Event Flow:
 2
 3Order/Payment Service
 4  → DB transaction + outbox_events
 5  → Outbox Worker (Article 12)
 6  → Kafka Topics:
 7      santekno.orders.placed
 8      santekno.orders.confirmed
 9      santekno.orders.cancelled
10      santekno.orders.shipped
11      santekno.payments.completed
12      santekno.payments.failed
13
14Notification Service (Kafka Consumer):
15  → Consume event
16  → Look up user email from DB
17  → Render email template
18  → Send via SMTP/email provider
19  → Log notification to DB
20  → Commit Kafka offset (acknowledge)
21
22At-least-once: if the email send fails after commit → duplicate possible
23Solution: notifications table with an idempotency key (event_id)

The key point of this diagram: because Kafka guarantees at-least-once delivery, the only way to prevent duplicate emails is the event_id idempotency key in the notifications table — that is the foundation of every handler we write next.


10.02 Domain: Notification Entity

The domain entity defines the shape of the notification data independently of the Kafka or SMTP infrastructure. The struct below stores the status, channel, and — most importantly — EventID as the idempotency key.

go
 1// internal/domain/notification/entity.go
 2
 3package notification
 4
 5import (
 6    "errors"
 7    "time"
 8    "github.com/google/uuid"
 9)
10
11var (
12    ErrNotificationFailed = errors.New("notification send failed")
13    ErrTemplateNotFound   = errors.New("notification template not found")
14)
15
16type Channel string
17const (
18    ChannelEmail Channel = "EMAIL"
19    ChannelPush  Channel = "PUSH"
20)
21
22type Status string
23const (
24    StatusPending Status = "PENDING"
25    StatusSent    Status = "SENT"
26    StatusFailed  Status = "FAILED"
27)
28
29type Notification struct {
30    ID           uuid.UUID
31    UserID       uuid.UUID
32    Channel      Channel
33    TemplateKey  string
34    Subject      string
35    Body         string
36    RecipientEmail string
37    Status       Status
38    EventID      string  // idempotency key — from the Kafka event ID
39    EventType    string  // "order.confirmed", "payment.completed", etc.
40    CreatedAt    time.Time
41    SentAt       *time.Time
42    Error        *string
43}
44
45// NotificationData: the data injected into the template
46type NotificationData struct {
47    CustomerName   string
48    OrderID        string
49    TotalAmountIDR int64
50    PaymentMethod  string
51    Items          []NotificationItem
52    PaymentURL     string
53    CancelDeadline string // formatted time
54}
55
56type NotificationItem struct {
57    ProductName  string
58    Quantity     int
59    SubtotalIDR  int64
60}

With EventID and Status as part of the entity, every notification can be traced from its originating event all the way to its status — sent or failed — the basis for an audit trail and for retries.


10.03 Email Templates

Notifications need dynamic email content per event type. The code below uses Go’s text/template to define a subject and body per template key, complete with a formatIDR helper to format rupiah amounts.

go
  1// internal/notification/template/templates.go
  2
  3package template
  4
  5import (
  6    "bytes"
  7    "fmt"
  8    "text/template"
  9)
 10
 11type TemplateKey string
 12const (
 13    TmplOrderPlaced    TemplateKey = "order_placed"
 14    TmplOrderConfirmed TemplateKey = "order_confirmed"
 15    TmplOrderCancelled TemplateKey = "order_cancelled"
 16    TmplOrderShipped   TemplateKey = "order_shipped"
 17    TmplPaymentFailed  TemplateKey = "payment_failed"
 18)
 19
 20var templates = map[TemplateKey]emailTemplate{
 21    TmplOrderPlaced: {
 22        Subject: "Order #{{.OrderID}} Successfully Created — Santekno Shop",
 23        Body: `Hi {{.CustomerName}},
 24
 25Your order has been successfully created!
 26
 27Order Details:
 28Order ID: {{.OrderID}}
 29{{range .Items}}- {{.ProductName}} x{{.Quantity}}: {{formatIDR .SubtotalIDR}}
 30{{end}}
 31Total: {{formatIDR .TotalAmountIDR}}
 32Payment Method: {{.PaymentMethod}}
 33
 34Please complete your payment before {{.CancelDeadline}}:
 35{{.PaymentURL}}
 36
 37Thank you for shopping at Santekno Shop!
 38`,
 39    },
 40    TmplOrderConfirmed: {
 41        Subject: "Payment Confirmed — Order #{{.OrderID}} Is Being Processed",
 42        Body: `Hi {{.CustomerName}},
 43
 44Your payment has been confirmed! Your order is now being processed.
 45
 46Order ID: {{.OrderID}}
 47Total: {{formatIDR .TotalAmountIDR}}
 48
 49We'll send you a notification once your order ships.
 50
 51Thank you!
 52— The Santekno Shop Team
 53`,
 54    },
 55    TmplOrderCancelled: {
 56        Subject: "Order #{{.OrderID}} Cancelled",
 57        Body: `Hi {{.CustomerName}},
 58
 59Your order with ID {{.OrderID}} has been cancelled.
 60
 61If you cancelled it yourself: no further action is needed.
 62If the payment failed: please place a new order.
 63
 64Have questions? Contact our support team.
 65
 66— The Santekno Shop Team
 67`,
 68    },
 69    TmplPaymentFailed: {
 70        Subject: "Payment Failed — Order #{{.OrderID}}",
 71        Body: `Hi {{.CustomerName}},
 72
 73Sorry, the payment for order #{{.OrderID}} failed to process.
 74Your order has been cancelled and the stock has been restored.
 75
 76Please place a new order to continue your purchase.
 77
 78— The Santekno Shop Team
 79`,
 80    },
 81}
 82
 83type emailTemplate struct {
 84    Subject string
 85    Body    string
 86}
 87
 88type Renderer struct {
 89    funcs template.FuncMap
 90}
 91
 92func NewRenderer() *Renderer {
 93    return &Renderer{
 94        funcs: template.FuncMap{
 95            "formatIDR": func(cents int64) string {
 96                return fmt.Sprintf("Rp %.0f", float64(cents)/100)
 97            },
 98        },
 99    }
100}
101
102type RenderedEmail struct {
103    Subject string
104    Body    string
105}
106
107func (r *Renderer) Render(key TemplateKey, data interface{}) (*RenderedEmail, error) {
108    tmpl, ok := templates[key]
109    if !ok {
110        return nil, fmt.Errorf("template.Render: unknown key %s", key)
111    }
112
113    subjectTmpl, err := template.New("subject").Funcs(r.funcs).Parse(tmpl.Subject)
114    if err != nil {
115        return nil, fmt.Errorf("template.Render: parse subject: %w", err)
116    }
117    bodyTmpl, err := template.New("body").Funcs(r.funcs).Parse(tmpl.Body)
118    if err != nil {
119        return nil, fmt.Errorf("template.Render: parse body: %w", err)
120    }
121
122    var subjectBuf, bodyBuf bytes.Buffer
123    if err := subjectTmpl.Execute(&subjectBuf, data); err != nil {
124        return nil, fmt.Errorf("template.Render: execute subject: %w", err)
125    }
126    if err := bodyTmpl.Execute(&bodyBuf, data); err != nil {
127        return nil, fmt.Errorf("template.Render: execute body: %w", err)
128    }
129
130    return &RenderedEmail{
131        Subject: subjectBuf.String(),
132        Body:    bodyBuf.String(),
133    }, nil
134}

By keeping templates in a single map and rendering through Renderer, adding a new notification type only requires one entry — the send logic doesn’t need to change at all.


10.04 Email Sender Interface

Sending email is hidden behind an interface so the handler isn’t tied to a specific provider. The code below defines a Sender with two implementations: SMTP for production and NoOp for development.

go
 1// internal/notification/email/sender.go
 2
 3package email
 4
 5import "context"
 6
 7//go:generate mockgen -destination=../../../testutil/mock/email_sender_mock.go -package=mock -source=sender.go
 8
 9type Sender interface {
10    Send(ctx context.Context, msg Message) error
11}
12
13type Message struct {
14    To      string
15    Subject string
16    Body    string
17    IsHTML  bool
18}
19
20// SMTPSender: implementation via Go's net/smtp
21type SMTPSender struct {
22    host     string
23    port     int
24    from     string
25    username string
26    password string
27}
28
29func NewSMTPSender(host string, port int, from, username, password string) *SMTPSender {
30    return &SMTPSender{host: host, port: port, from: from, username: username, password: password}
31}
32
33func (s *SMTPSender) Send(ctx context.Context, msg Message) error {
34    // SMTP implementation — simplified for this article
35    // Production: use a library such as gopkg.in/gomail.v2
36    addr := fmt.Sprintf("%s:%d", s.host, s.port)
37    auth := smtp.PlainAuth("", s.username, s.password, s.host)
38
39    body := fmt.Sprintf("From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n%s",
40        s.from, msg.To, msg.Subject, msg.Body)
41
42    return smtp.SendMail(addr, auth, s.from, []string{msg.To}, []byte(body))
43}
44
45// NoOpSender: for development/testing
46type NoOpSender struct{}
47
48func (s *NoOpSender) Send(ctx context.Context, msg Message) error {
49    fmt.Printf("[NOTIFICATION] To: %s | Subject: %s\n", msg.To, msg.Subject)
50    return nil
51}

The Sender interface lets the handler be tested with a mock and run locally without an SMTP server — just swap the implementation for NoOpSender in the development environment.


10.05 Notification Repository

The repository persists every notification to the database, including an idempotency check via GetByEventID. The interface below defines its persistence contract.

go
 1// internal/domain/notification/repository.go
 2
 3package notification
 4
 5import "context"
 6
 7//go:generate mockgen -destination=../../../testutil/mock/notification_repo_mock.go -package=mock -source=repository.go
 8
 9type Repository interface {
10    Create(ctx context.Context, n *Notification) error
11    GetByEventID(ctx context.Context, eventID string) (*Notification, error) // idempotency
12    UpdateStatus(ctx context.Context, id string, status Status, errMsg *string) error
13}

The GetByEventID method is the idempotency gate at the application level; it is paired with a UNIQUE constraint in the table schema below as double protection.

The notifications table schema provides a second layer of protection through event_id UNIQUE and prepares indexes for retry queries. The migration below defines the table together with its indexes.

sql
 1-- migrations/20260701000010_create_notifications.up.sql
 2
 3CREATE TYPE notification_channel AS ENUM ('EMAIL', 'PUSH');
 4CREATE TYPE notification_status AS ENUM ('PENDING', 'SENT', 'FAILED');
 5
 6CREATE TABLE notifications (
 7    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
 8    user_id UUID NOT NULL REFERENCES users(id),
 9    channel notification_channel NOT NULL,
10    template_key VARCHAR(50) NOT NULL,
11    subject TEXT,
12    body TEXT,
13    recipient_email VARCHAR(255),
14    status notification_status NOT NULL DEFAULT 'PENDING',
15    event_id VARCHAR(255) UNIQUE,   -- idempotency key
16    event_type VARCHAR(100),
17    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
18    sent_at TIMESTAMPTZ,
19    error_message TEXT
20);
21
22CREATE INDEX idx_notifications_user_id ON notifications(user_id);
23CREATE INDEX idx_notifications_event_id ON notifications(event_id);
24CREATE INDEX idx_notifications_status ON notifications(status)
25    WHERE status = 'PENDING';

The UNIQUE constraint on event_id ensures that even if there’s a bug at the application level, the database will still reject a duplicate insert — the last line of defense against duplicate emails.


10.06 Kafka Consumer Setup

The heart of the service is a Kafka consumer group that reads messages and delegates them to a handler per topic. The code below uses sarama with manual commit — the offset only advances after a message is successfully processed.

go
 1// internal/notification/consumer/kafka_consumer.go
 2
 3package consumer
 4
 5import (
 6    "context"
 7    "encoding/json"
 8    "fmt"
 9    "log"
10
11    "github.com/IBM/sarama"
12    "github.com/santekno/santekno-shop/internal/notification/handler"
13)
14
15type KafkaConsumer struct {
16    client   sarama.ConsumerGroup
17    topics   []string
18    handlers map[string]handler.EventHandler
19}
20
21func NewKafkaConsumer(brokers []string, groupID string, handlers map[string]handler.EventHandler) (*KafkaConsumer, error) {
22    config := sarama.NewConfig()
23    config.Consumer.Group.Rebalance.GroupStrategies = []sarama.BalanceStrategy{
24        sarama.NewBalanceStrategyRoundRobin(),
25    }
26    config.Consumer.Offsets.Initial = sarama.OffsetNewest
27    config.Consumer.Offsets.AutoCommit.Enable = false // manual commit
28
29    client, err := sarama.NewConsumerGroup(brokers, groupID, config)
30    if err != nil {
31        return nil, fmt.Errorf("kafkaConsumer: create group: %w", err)
32    }
33
34    topics := make([]string, 0, len(handlers))
35    for topic := range handlers { topics = append(topics, topic) }
36
37    return &KafkaConsumer{
38        client:   client,
39        topics:   topics,
40        handlers: handlers,
41    }, nil
42}
43
44func (c *KafkaConsumer) Run(ctx context.Context) error {
45    cgHandler := &consumerGroupHandler{handlers: c.handlers}
46    for {
47        if err := c.client.Consume(ctx, c.topics, cgHandler); err != nil {
48            log.Printf("kafka consumer error: %v", err)
49        }
50        if ctx.Err() != nil {
51            return ctx.Err()
52        }
53    }
54}
55
56func (c *KafkaConsumer) Close() error {
57    return c.client.Close()
58}
59
60// consumerGroupHandler implements sarama.ConsumerGroupHandler
61type consumerGroupHandler struct {
62    handlers map[string]handler.EventHandler
63}
64
65func (h *consumerGroupHandler) Setup(sarama.ConsumerGroupSession) error   { return nil }
66func (h *consumerGroupHandler) Cleanup(sarama.ConsumerGroupSession) error { return nil }
67
68func (h *consumerGroupHandler) ConsumeClaim(
69    session sarama.ConsumerGroupSession,
70    claim sarama.ConsumerGroupClaim,
71) error {
72    for msg := range claim.Messages() {
73        topic := msg.Topic
74        eventHandler, ok := h.handlers[topic]
75        if !ok {
76            session.MarkMessage(msg, "")
77            continue
78        }
79
80        ctx := context.Background()
81        if err := eventHandler.Handle(ctx, msg.Key, msg.Value); err != nil {
82            log.Printf("event handler error [%s]: %v", topic, err)
83            // Don't commit — Kafka retries automatically
84            // For permanent failures: send to the Dead Letter Queue
85            continue
86        }
87
88        // Manual commit: only after successful processing
89        session.MarkMessage(msg, "")
90        session.Commit()
91    }
92    return nil
93}

The reliability key here is AutoCommit.Enable = false plus session.Commit(), which is only called after the handler succeeds — if the process crashes before the commit, Kafka will redeliver the same message.


10.07 Event Handlers per Topic

Each topic has its own handler that follows a uniform pattern: check idempotency, fetch the user, render the template, send the email, update the status. The code below is the handler for the order.confirmed event.

go
  1// internal/notification/handler/order_confirmed_handler.go
  2
  3package handler
  4
  5import (
  6    "context"
  7    "encoding/json"
  8    "fmt"
  9    "time"
 10
 11    "github.com/google/uuid"
 12    domainNotif  "github.com/santekno/santekno-shop/internal/domain/notification"
 13    "github.com/santekno/santekno-shop/internal/notification/email"
 14    notifTemplate "github.com/santekno/santekno-shop/internal/notification/template"
 15    domainUser    "github.com/santekno/santekno-shop/internal/domain/user"
 16)
 17
 18type EventHandler interface {
 19    Handle(ctx context.Context, key, value []byte) error
 20}
 21
 22// OrderConfirmedPayload: matches the outbox event from Article 08
 23type OrderConfirmedPayload struct {
 24    OrderID  string `json:"order_id"`
 25    UserID   string `json:"user_id"`
 26    Status   string `json:"status"`
 27}
 28
 29type OrderConfirmedHandler struct {
 30    userRepo     domainUser.Repository
 31    notifRepo    domainNotif.Repository
 32    emailSender  email.Sender
 33    renderer     *notifTemplate.Renderer
 34}
 35
 36func NewOrderConfirmedHandler(
 37    userRepo domainUser.Repository,
 38    notifRepo domainNotif.Repository,
 39    sender email.Sender,
 40    renderer *notifTemplate.Renderer,
 41) *OrderConfirmedHandler {
 42    return &OrderConfirmedHandler{
 43        userRepo: userRepo, notifRepo: notifRepo,
 44        emailSender: sender, renderer: renderer,
 45    }
 46}
 47
 48func (h *OrderConfirmedHandler) Handle(ctx context.Context, key, value []byte) error {
 49    var payload OrderConfirmedPayload
 50    if err := json.Unmarshal(value, &payload); err != nil {
 51        return fmt.Errorf("orderConfirmedHandler: unmarshal: %w", err)
 52    }
 53
 54    // Idempotency: event_id = topic + order_id
 55    eventID := "order.confirmed:" + payload.OrderID
 56    existing, err := h.notifRepo.GetByEventID(ctx, eventID)
 57    if err != nil {
 58        return fmt.Errorf("orderConfirmedHandler: check idempotency: %w", err)
 59    }
 60    if existing != nil {
 61        return nil // already sent
 62    }
 63
 64    // Get user info
 65    userID, _ := uuid.Parse(payload.UserID)
 66    u, err := h.userRepo.GetByID(ctx, userID)
 67    if err != nil || u == nil {
 68        return fmt.Errorf("orderConfirmedHandler: get user: %w", err)
 69    }
 70
 71    // Render email
 72    rendered, err := h.renderer.Render(notifTemplate.TmplOrderConfirmed,
 73        notifTemplate.NotificationData{
 74            CustomerName: u.Name,
 75            OrderID:      payload.OrderID,
 76        })
 77    if err != nil {
 78        return fmt.Errorf("orderConfirmedHandler: render: %w", err)
 79    }
 80
 81    // Create notification record
 82    notif := &domainNotif.Notification{
 83        ID:             uuid.New(),
 84        UserID:         userID,
 85        Channel:        domainNotif.ChannelEmail,
 86        TemplateKey:    string(notifTemplate.TmplOrderConfirmed),
 87        Subject:        rendered.Subject,
 88        Body:           rendered.Body,
 89        RecipientEmail: u.Email,
 90        Status:         domainNotif.StatusPending,
 91        EventID:        eventID,
 92        EventType:      "order.confirmed",
 93        CreatedAt:      time.Now().UTC(),
 94    }
 95
 96    if err := h.notifRepo.Create(ctx, notif); err != nil {
 97        return fmt.Errorf("orderConfirmedHandler: save notification: %w", err)
 98    }
 99
100    // Send email
101    sendErr := h.emailSender.Send(ctx, email.Message{
102        To:      u.Email,
103        Subject: rendered.Subject,
104        Body:    rendered.Body,
105    })
106
107    now := time.Now().UTC()
108    if sendErr != nil {
109        errMsg := sendErr.Error()
110        h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusFailed, &errMsg)
111        return fmt.Errorf("orderConfirmedHandler: send email: %w", sendErr)
112    }
113
114    h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
115    return nil
116}

Note the ordering: the notification is saved as PENDING first, then the email is sent, and only then is the status updated — so that if the send fails, we have a FAILED record that can be retried instead of an event that vanishes without a trace.


10.08 OrderPlaced Handler (Payment URL)

The order.placed handler is slightly more complex because it needs the order details and the payment URL. The code below shows the same pattern plus a sendAndLog helper to reduce duplication.

go
 1// internal/notification/handler/order_placed_handler.go
 2
 3type OrderPlacedPayload struct {
 4    OrderID        string  `json:"order_id"`
 5    UserID         string  `json:"user_id"`
 6    TotalAmountIDR int64   `json:"total_amount_idr"`
 7    ItemCount      int     `json:"item_count"`
 8}
 9
10type OrderPlacedHandler struct {
11    userRepo    domainUser.Repository
12    orderRepo   domainOrder.Repository
13    notifRepo   domainNotif.Repository
14    emailSender email.Sender
15    renderer    *notifTemplate.Renderer
16}
17
18func (h *OrderPlacedHandler) Handle(ctx context.Context, key, value []byte) error {
19    var payload OrderPlacedPayload
20    if err := json.Unmarshal(value, &payload); err != nil {
21        return fmt.Errorf("orderPlacedHandler: %w", err)
22    }
23
24    eventID := "order.placed:" + payload.OrderID
25    if existing, _ := h.notifRepo.GetByEventID(ctx, eventID); existing != nil {
26        return nil
27    }
28
29    userID, _ := uuid.Parse(payload.UserID)
30    u, err := h.userRepo.GetByID(ctx, userID)
31    if err != nil || u == nil {
32        return fmt.Errorf("orderPlacedHandler: get user: %w", err)
33    }
34
35    // Can fetch the order detail for items if needed
36    orderID, _ := uuid.Parse(payload.OrderID)
37    o, err := h.orderRepo.GetByID(ctx, orderID)
38    if err != nil || o == nil {
39        return fmt.Errorf("orderPlacedHandler: get order: %w", err)
40    }
41
42    items := make([]notifTemplate.NotificationItem, len(o.Items))
43    for i, item := range o.Items {
44        items[i] = notifTemplate.NotificationItem{
45            ProductName: item.ProductName,
46            Quantity:    item.Quantity,
47            SubtotalIDR: item.SubtotalIDR,
48        }
49    }
50
51    deadline := o.CreatedAt.Add(24 * time.Hour).Format("02 Jan 2006 15:04 WIB")
52    paymentURL := ""
53    if o.PaymentURL != nil { paymentURL = *o.PaymentURL }
54
55    rendered, _ := h.renderer.Render(notifTemplate.TmplOrderPlaced,
56        notifTemplate.NotificationData{
57            CustomerName:   u.Name,
58            OrderID:        payload.OrderID,
59            TotalAmountIDR: payload.TotalAmountIDR,
60            Items:          items,
61            CancelDeadline: deadline,
62            PaymentURL:     paymentURL,
63        })
64
65    return h.sendAndLog(ctx, u, eventID, "order.placed", rendered, notifTemplate.TmplOrderPlaced)
66}
67
68// sendAndLog: helper to create the notif record + send + update status
69func (h *OrderPlacedHandler) sendAndLog(
70    ctx context.Context, u *domainUser.User,
71    eventID, eventType string,
72    rendered *notifTemplate.RenderedEmail,
73    tmplKey notifTemplate.TemplateKey,
74) error {
75    notif := &domainNotif.Notification{
76        ID:             uuid.New(),
77        UserID:         u.ID,
78        Channel:        domainNotif.ChannelEmail,
79        TemplateKey:    string(tmplKey),
80        Subject:        rendered.Subject,
81        Body:           rendered.Body,
82        RecipientEmail: u.Email,
83        Status:         domainNotif.StatusPending,
84        EventID:        eventID,
85        EventType:      eventType,
86        CreatedAt:      time.Now().UTC(),
87    }
88    h.notifRepo.Create(ctx, notif)
89
90    if err := h.emailSender.Send(ctx, email.Message{To: u.Email, Subject: rendered.Subject, Body: rendered.Body}); err != nil {
91        errMsg := err.Error()
92        h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusFailed, &errMsg)
93        return err
94    }
95
96    h.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
97    return nil
98}

The sendAndLog helper lifts the “create record → send → update status” pattern into one place, so the other handlers just call it and never repeat the same boilerplate.


10.09 Dead Letter Queue Pattern

A message that keeps failing must not block the consumer forever. The Dead Letter Queue pattern below moves messages that exceed the retry limit to a dedicated topic so the ops team can inspect them.

go
 1// For messages that fail after the max retry count
 2
 3const maxRetries = 3
 4
 5type RetryableHandler struct {
 6    inner      EventHandler
 7    dlqTopic   string
 8    maxRetries int
 9    producer   sarama.SyncProducer
10}
11
12func (h *RetryableHandler) Handle(ctx context.Context, key, value []byte) error {
13    retries := extractRetryCount(key) // embedded in message key
14
15    if err := h.inner.Handle(ctx, key, value); err != nil {
16        if retries >= h.maxRetries {
17            // Send to the Dead Letter Queue
18            h.producer.SendMessage(&sarama.ProducerMessage{
19                Topic: h.dlqTopic, // e.g., "santekno.notifications.dlq"
20                Key:   sarama.StringEncoder(string(key)),
21                Value: sarama.ByteEncoder(value),
22                Headers: []sarama.RecordHeader{
23                    {Key: []byte("original-topic"), Value: key},
24                    {Key: []byte("error"), Value: []byte(err.Error())},
25                    {Key: []byte("retries"), Value: []byte(fmt.Sprintf("%d", retries))},
26                },
27            })
28            return nil // acknowledge: DLQ accepted
29        }
30        return err // don't acknowledge: Kafka will retry
31    }
32    return nil
33}
34
35// DLQ monitoring: alert if there are any messages in the DLQ
36// Can be replayed manually by the ops team after fixing the issue

With a DLQ, one poison message won’t halt the entire pipeline; the message is “parked” with error metadata in its headers while the consumer keeps processing the next messages.


10.10 Notification Service Entry Point

All the components are assembled in an entry point that can run as a separate binary or as a goroutine inside the main server. The code below wires up the infrastructure, repositories, handlers, and consumer while also handling graceful shutdown.

go
 1// cmd/notification/main.go
 2// A separate binary from the HTTP server (optional — could also be a goroutine inside the server)
 3
 4package main
 5
 6import (
 7    "context"
 8    "fmt"
 9    "os"
10    "os/signal"
11    "syscall"
12
13    "github.com/santekno/santekno-shop/config"
14    "github.com/santekno/santekno-shop/internal/notification/consumer"
15    "github.com/santekno/santekno-shop/internal/notification/email"
16    notifTemplate "github.com/santekno/santekno-shop/internal/notification/template"
17    "github.com/santekno/santekno-shop/internal/notification/handler"
18    postgresRepo "github.com/santekno/santekno-shop/internal/repository/postgres"
19    // ...
20)
21
22func main() {
23    cfg, _ := config.Load()
24
25    // Infrastructure
26    db, _    := pgxpool.New(context.Background(), cfg.Database.URL)
27    sender   := email.NewSMTPSender(cfg.SMTP.Host, cfg.SMTP.Port, cfg.SMTP.From, cfg.SMTP.Username, cfg.SMTP.Password)
28    renderer := notifTemplate.NewRenderer()
29
30    // Repositories
31    userRepo  := postgresRepo.NewUserRepository(db)
32    orderRepo := postgresRepo.NewOrderRepository(db)
33    notifRepo := postgresRepo.NewNotificationRepository(db)
34
35    // Handlers per topic
36    handlers := map[string]handler.EventHandler{
37        "santekno.orders.placed":    handler.NewOrderPlacedHandler(userRepo, orderRepo, notifRepo, sender, renderer),
38        "santekno.orders.confirmed": handler.NewOrderConfirmedHandler(userRepo, notifRepo, sender, renderer),
39        "santekno.orders.cancelled": handler.NewOrderCancelledHandler(userRepo, notifRepo, sender, renderer),
40        "santekno.payments.failed":  handler.NewPaymentFailedHandler(userRepo, notifRepo, sender, renderer),
41    }
42
43    // Kafka consumer
44    kafkaConsumer, _ := consumer.NewKafkaConsumer(
45        cfg.Kafka.Brokers,
46        "santekno-notification-service",
47        handlers,
48    )
49    defer kafkaConsumer.Close()
50
51    ctx, cancel := context.WithCancel(context.Background())
52    defer cancel()
53
54    go func() {
55        fmt.Println("Notification Service started")
56        kafkaConsumer.Run(ctx)
57    }()
58
59    // Graceful shutdown
60    quit := make(chan os.Signal, 1)
61    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
62    <-quit
63    fmt.Println("Notification Service stopping...")
64    cancel()
65}

The topic → handler map structure makes adding a new consumer as simple as one registration line — an architecture that scales easily as the number of notification types grows.


10.11 Notification Tests

The handler must be tested for the happy path, idempotency, and email failure. The test suite below uses gomock to isolate the handler from the database and SMTP.

go
 1// internal/notification/handler/order_confirmed_handler_test.go
 2
 3type OrderConfirmedHandlerSuite struct {
 4    suite.Suite
 5    ctrl        *gomock.Controller
 6    userRepo    *mock.MockUserRepository
 7    notifRepo   *mock.MockNotificationRepository
 8    emailSender *mock.MockEmailSender
 9    handler     *handler.OrderConfirmedHandler
10}
11
12func (s *OrderConfirmedHandlerSuite) SetupTest() {
13    s.ctrl       = gomock.NewController(s.T())
14    s.userRepo   = mock.NewMockUserRepository(s.ctrl)
15    s.notifRepo  = mock.NewMockNotificationRepository(s.ctrl)
16    s.emailSender = mock.NewMockEmailSender(s.ctrl)
17    renderer    := notifTemplate.NewRenderer()
18
19    s.handler = handler.NewOrderConfirmedHandler(
20        s.userRepo, s.notifRepo, s.emailSender, renderer)
21}
22
23// Happy path: valid event → email sent
24func (s *OrderConfirmedHandlerSuite) TestHandle_ValidEvent_SendsEmail() {
25    userID  := uuid.New()
26    orderID := uuid.New()
27    payload := handler.OrderConfirmedPayload{
28        OrderID: orderID.String(), UserID: userID.String(), Status: "CONFIRMED",
29    }
30    value, _ := json.Marshal(payload)
31
32    u := &domainUser.User{ID: userID, Email: "user@example.com", Name: "John"}
33
34    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), "order.confirmed:"+orderID.String()).Return(nil, nil)
35    s.userRepo.EXPECT().GetByID(gomock.Any(), userID).Return(u, nil)
36    s.notifRepo.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
37    s.emailSender.EXPECT().Send(gomock.Any(), gomock.Any()).Return(nil)
38    s.notifRepo.EXPECT().UpdateStatus(gomock.Any(), gomock.Any(), domainNotif.StatusSent, nil).Return(nil)
39
40    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
41    s.NoError(err)
42}
43
44// Idempotent: the same event doesn't re-send
45func (s *OrderConfirmedHandlerSuite) TestHandle_DuplicateEvent_Idempotent() {
46    orderID := uuid.New()
47    payload := handler.OrderConfirmedPayload{OrderID: orderID.String(), UserID: uuid.New().String()}
48    value, _ := json.Marshal(payload)
49
50    existing := &domainNotif.Notification{Status: domainNotif.StatusSent}
51    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), "order.confirmed:"+orderID.String()).Return(existing, nil)
52    // emailSender.Send MUST NOT be called
53
54    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
55    s.NoError(err)
56}
57
58// Email fails: status FAILED, error returned (Kafka does not commit)
59func (s *OrderConfirmedHandlerSuite) TestHandle_EmailFails_UpdatesStatusFailed() {
60    userID  := uuid.New()
61    orderID := uuid.New()
62    payload := handler.OrderConfirmedPayload{OrderID: orderID.String(), UserID: userID.String()}
63    value, _ := json.Marshal(payload)
64    u := &domainUser.User{ID: userID, Email: "user@example.com", Name: "Test"}
65
66    s.notifRepo.EXPECT().GetByEventID(gomock.Any(), gomock.Any()).Return(nil, nil)
67    s.userRepo.EXPECT().GetByID(gomock.Any(), userID).Return(u, nil)
68    s.notifRepo.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
69    s.emailSender.EXPECT().Send(gomock.Any(), gomock.Any()).Return(fmt.Errorf("SMTP connection refused"))
70    s.notifRepo.EXPECT().UpdateStatus(gomock.Any(), gomock.Any(), domainNotif.StatusFailed, gomock.Any()).Return(nil)
71
72    err := s.handler.Handle(context.Background(), []byte(orderID.String()), value)
73    s.Error(err) // error → Kafka doesn't commit → retry
74}
75
76func TestOrderConfirmedHandlerSuite(t *testing.T) {
77    suite.Run(t, new(OrderConfirmedHandlerSuite))
78}

The TestHandle_DuplicateEvent_Idempotent test is the most important one: it proves that emailSender.Send is never called for a duplicate event — the guarantee that a customer will never receive a duplicate email.


10.12 Final Specify Audit: All 29 ACs

Once all the handlers are done, we run specify audit to measure AC coverage automatically. The command below parses the JSON output into a score summary.

bash
 1specify audit --output json | jq '{
 2  score: .score,
 3  total_covered: .covered,
 4  total_acs: .total
 5}'
 6
 7# Expected after Article 10:
 8# {
 9#   "score": 95,
10#   "total_covered": 25,
11#   "total_acs": 29
12# }
13#
14# Note: 29 ACs from the spec → 25 tracked by specify audit
15# (4 ACs aren't auto-detected because their pattern is in the event consumer, not HTTP)
16# Manual verification for the notification ACs

A score of 95 shows that most ACs are covered automatically; the 4 event-consumer-based notification ACs need manual verification because their pattern isn’t an HTTP endpoint that the audit tool can detect.


10.13 Notification Status Dashboard

For observability, we expose a notification statistics endpoint. The handler below aggregates the count of SENT, FAILED, and PENDING notifications over the last 24 hours.

go
 1// delivery/http/handler/admin_handler.go (preview — Article 14)
 2
 3// GET /admin/notifications/stats
 4func (h *AdminHandler) NotificationStats(c echo.Context) error {
 5    ctx := c.Request().Context()
 6
 7    var stats struct {
 8        Sent   int `json:"sent"`
 9        Failed int `json:"failed"`
10        Pending int `json:"pending"`
11    }
12
13    h.db.QueryRow(ctx,
14        `SELECT
15            COUNT(*) FILTER (WHERE status = 'SENT') as sent,
16            COUNT(*) FILTER (WHERE status = 'FAILED') as failed,
17            COUNT(*) FILTER (WHERE status = 'PENDING') as pending
18         FROM notifications
19         WHERE created_at > NOW() - INTERVAL '24 hours'`,
20    ).Scan(&stats.Sent, &stats.Failed, &stats.Pending)
21
22    return c.JSON(http.StatusOK, stats)
23}

This simple endpoint gives the ops team fast visibility: a spike in the FAILED count is an early signal of an SMTP or email-provider problem before customers even complain.


10.14 Consumer Group Strategy

A Kafka consumer group enables horizontal scaling by splitting the partitions across several instances. The diagram below shows how 3 partitions are divided among 3 consumer instances.

text
 1Consumer Group: santekno-notification-service
 2
 3Kafka Partition Assignment:
 4  santekno.orders.placed     [p0, p1, p2]
 5  santekno.orders.confirmed  [p0, p1, p2]
 6  ...
 7
 8With 3 partitions and 3 consumer instances:
 9  Instance A: partition 0 of all topics
10  Instance B: partition 1 of all topics
11  Instance C: partition 2 of all topics
12
13Benefits:
14  - Horizontal scaling: add instances without changing code
15  - Ordering per partition: events per order_id are routed to one partition via the key
16  - Fault tolerance: if instance A goes down, B/C take over
17
18Key design: use order_id as the Kafka message key
19  → All events for the same order land in the same partition
20  → Ordering guarantee per order

The design key here is choosing order_id as the message key: all events for a single order always fall into the same partition, so the placed → confirmed → shipped order is guaranteed to stay consistent.


10.15 Graceful Shutdown Consumer

When it receives SIGTERM, the consumer must stop cleanly without losing messages that are being processed. The code below summarizes the safe shutdown steps.

go
 1// When SIGTERM is received:
 2
 3func (c *KafkaConsumer) GracefulShutdown(ctx context.Context) {
 4    // 1. Stop accepting new messages
 5    c.cancel()
 6
 7    // 2. Wait for in-flight messages to finish
 8    // the sarama consumer group handles this automatically via context
 9    // with a 30-second timeout
10
11    // 3. Commit the last offset
12    // done via session.Commit() already called on each message
13
14    // 4. Close the consumer group
15    c.client.Close()
16    fmt.Println("Notification consumer stopped gracefully")
17}

Because the offset is committed after each successful message, a clean shutdown guarantees no message is lost or processed twice beyond the idempotency guarantee already in place.


10.16 Retry Logic with Backoff

SMTP failures are often transient, so retrying with exponential backoff can save many notifications. The code below wraps Sender with tiered retry logic.

go
 1// Retry with exponential backoff for email send
 2
 3type RetryEmailSender struct {
 4    inner      email.Sender
 5    maxRetries int
 6}
 7
 8func (r *RetryEmailSender) Send(ctx context.Context, msg email.Message) error {
 9    var lastErr error
10    for attempt := 0; attempt <= r.maxRetries; attempt++ {
11        if err := r.inner.Send(ctx, msg); err != nil {
12            lastErr = err
13            if attempt < r.maxRetries {
14                // Exponential backoff: 1s, 2s, 4s
15                backoff := time.Duration(1<<attempt) * time.Second
16                select {
17                case <-time.After(backoff):
18                case <-ctx.Done():
19                    return ctx.Err()
20                }
21                continue
22            }
23        } else {
24            return nil // success
25        }
26    }
27    return fmt.Errorf("send failed after %d retries: %w", r.maxRetries, lastErr)
28}

Because RetryEmailSender also implements the Sender interface, it can be plugged in transparently in front of SMTPSender without changing a single line in the handler — the power of composition through interfaces.


10.17 Monitoring: Failed Notifications

Notifications that fail after all retries need to be re-run on a schedule. The job below scans for FAILED notifications and attempts to re-send them every 15 minutes.

go
 1// Scheduled job to retry failed notifications (Article 18)
 2// Runs every 15 minutes
 3
 4func (s *RetryJob) Run(ctx context.Context) {
 5    failedNotifs, _ := s.notifRepo.ListFailed(ctx, 100)
 6
 7    for _, notif := range failedNotifs {
 8        // Re-send
 9        if err := s.sender.Send(ctx, email.Message{
10            To:      notif.RecipientEmail,
11            Subject: notif.Subject,
12            Body:    notif.Body,
13        }); err != nil {
14            // Still failing — leave for the ops team
15            continue
16        }
17
18        now := time.Now().UTC()
19        s.notifRepo.UpdateStatus(ctx, notif.ID.String(), domainNotif.StatusSent, nil)
20    }
21}
22
23// Alert: if the failed count > threshold within 1 hour
24// → PagerDuty / Slack alert

This job completes the safety net: notifications that slip past the inline retry still get a second chance on a schedule, and those that keep failing are flagged for manual investigation.


10.18 Event Consumer Summary

As a recap, here’s the complete map of topics to handlers and the standard steps every handler runs. This list serves as a quick reference when adding a new event type.

text
 1Topics and registered handlers:
 2
 3santekno.orders.placed     → OrderPlacedHandler
 4  → Send "Order created, pay soon" email
 5
 6santekno.orders.confirmed  → OrderConfirmedHandler
 7  → Send "Payment confirmed, order being processed" email
 8
 9santekno.orders.cancelled  → OrderCancelledHandler
10  → Send "Order cancelled" email
11
12santekno.orders.shipped    → OrderShippedHandler (Topic 5 Part 3)
13  → Send "Order shipped, tracking no: xxx" email
14
15santekno.payments.failed   → PaymentFailedHandler
16  → Send "Payment failed, order cancelled" email
17
18Every handler:
19  1. Idempotency check (event_id unique)
20  2. Get user info from DB
21  3. Render template
22  4. Create notification record (PENDING)
23  5. Send email
24  6. Update status (SENT / FAILED)
25  7. Return nil (commit) or error (no commit = retry)

These seven uniform steps are what make the service easy to maintain: every new handler just follows the same pattern, and a reviewer can immediately verify its completeness.


10.19 Part 2 Completion: Score Summary

The Notification Service marks the completion of Part 2 of the e-commerce series. The summary below shows the specify score progression from skeleton to notification.

text
 1TOPIC 5 PART 2 — COMPLETE
 2
 3Article 05 (Skeleton):     go build PASS, specify 5/100
 4Article 06 (User Service): bcrypt + JWT + Redis, specify 35/100
 5Article 07 (Product):      full-text search, optimistic lock, specify 50/100
 6Article 08 (Order):        atomic PlaceOrder + CancelOrder, specify 80/100
 7Article 09 (Payment):      HMAC webhook + idempotency, specify 90/100
 8Article 10 (Notification): Kafka consumer + email + DLQ, specify 95/100
 9
10Total ACs covered: 25/29 (4 notification ACs = event-driven, not in the initial spec)
11Pipeline status: FULLY GREEN
12
13Next:
14Part 3 (Articles 11-15): Infrastructure — Database indexing, Kafka integration,
15                        Redis caching, API Gateway, Docker + Kubernetes
16Part 4 (Articles 16-20): Production Baseline — Testing, CI/CD, Observability,
17                        Performance, Bridge to Topic 6

The steadily rising score across every article proves the value of SDD: each new feature adds measurable coverage, not just a vague feeling that “it seems to work”.


10.20 Summary

The Notification Service completes the core services of Santekno Shop with a reliable notification pipeline:

Kafka Consumer Group with manual commit — only commits after successful processing, retries automatically on failure.

Idempotency via event_id in the notifications table — a duplicate event doesn’t re-send the email.

Email Templates with text/template — subject and body rendered from dynamic data.

Dead Letter Queue for permanent failures — doesn’t block the main consumer, ops can replay.

Notification Log for every notification — audit trail, monitoring, and retry support.

Santekno Shop now has a full event-driven notification pipeline — from an order being placed to the customer receiving the confirmation email, everything runs async and reliably. In the next article we tidy up the database foundation: a solid migration workflow, the right index strategy for e-commerce queries, and pgvector ready for AI features.

Related Articles

💬 Comments