ankouros/samakia-mail repository overview

⁠samakia-mail

⁠Overview

Samakia Mail is a NestJS microservice running as a RabbitMQ consumer. It processes mail.send messages (activation, profile updates, etc.) and sends emails via SMTP (Gmail in prod).

⁠Technology & Stack

• Runtime: Node.js 20 (Alpine)
• Framework: NestJS 11 (Microservice transport: RMQ)
• Messaging: RabbitMQ (amqplib)
• SMTP: Nodemailer
• Logging: Pino
• Dockerfile: ops/docker/samakia-mail.Dockerfile

⁠Purpose

• Offload email delivery from platform identity workflows.
• Centralize instrumentation and retry/backoff for outbound mail.

⁠Configuration

Loaded via @samakia-platform/config (sourced from Vault during make docker-publish). Keys: RABBITMQ_*, RABBITMQ_MAIL_QUEUE, SMTP_*.

Prod gating:

• publish-mail verifies SMTP_USER, SMTP_PASS, and SMTP_FROM in the Vault export; worker exits early if missing.

⁠Queue and Flow

• Consumes: ${RABBITMQ_MAIL_QUEUE} (default mail.send)
• Produces: SMTP messages to SMTP_HOST:SMTP_PORT

flowchart LR
  A[Platform services]
  Q[(RabbitMQ: mail.send)]
  M[Mail Worker]
  S[(Gmail SMTP)]
  E[(mail.send.dlq)]
  A --> Q
  Q --> M
  M --> S
  M --> E
  classDef dlq fill:#fff5f5,stroke:#ff6666,color:#c00
  class E dlq

⁠Deployment

• Kubernetes: ops/k8s/base/deployments/samakia-mail.yaml
• Image: docker.io/<namespace>/samakia-mail:<tag>
• Queue connection: ${RABBITMQ_PROTOCOL}://${RABBITMQ_USERNAME}:***@${RABBITMQ_HOST}:${RABBITMQ_PORT}${RABBITMQ_VHOST}

⁠DLQ Behavior

sequenceDiagram
  participant M as Mail Worker
  participant Q as RabbitMQ
  participant S as SMTP
  Q-->>M: mail.send { to, subject, html }
  M->>S: sendMail
  alt SMTP error
    M-->>Q: nack (requeue=false)
    Q-->>Q: route to mail.send.dlq
  else OK
    M-->>Q: ack
  end

⁠Tests

• Unit: present where applicable under apps/samakia-mail/src/app/**.spec.ts
• E2E: apps/samakia-mail-e2e orchestrates build/serve/queue probes

⁠Runbook

• Restart worker: kubectl rollout restart deploy/samakia-mail -n samakia-platform
• Logs: kubectl logs deploy/samakia-mail -n samakia-platform -f

⁠Visual Map

flowchart TD
  n1["Overview"]
  n2["Technology & Stack"]
  n3["Purpose"]
  n4["Configuration"]
  n5["Queue and Flow"]
  n6["Deployment"]
  n7["DLQ Behavior"]
  n8["Tests"]
  n1 --> n2
  n1 --> n3
  n1 --> n4
  n1 --> n5
  n1 --> n6
  n6 --> n7
  n1 --> n8