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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 issueWith 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.
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.
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.
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 ACsA 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.
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.
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 orderThe 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.
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.
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.
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 alertThis 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.
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.
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 6The 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.