# williamnyongesa/sms-notification-system architecture

> Architecture diagram of the GitHub repository williamnyongesa/sms-notification-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/williamnyongesa/sms-notification-system
- Repository: https://github.com/williamnyongesa/sms-notification-system

## Overview

This is an asynchronous SMS notification system: clients submit validated single or bulk requests, the REST API creates queued messages and publishes them to Kafka, and a consumer dispatches each message through a mock provider. The README also documents health checks, Kafka UI monitoring, and optional real-provider integration. The consumer logs delivery outcomes; the sampled code does not show delivery-state persistence or retry handling. The principal processing code was sampled; Kafka UI and deployment services are represented from README documentation.

Main entry points: [`sms-api/src/main/java/com/sms/controller/SmsController.java`](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/controller/SmsController.java) (SMS controller), [`sms-api/src/main/java/com/sms/service/SmsProducerService.java`](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/service/SmsProducerService.java) (SMS producer), [`sms-consumer/src/main/java/com/sms/consumer/SmsKafkaConsumer.java`](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/consumer/SmsKafkaConsumer.java) (Kafka listener), [`docker-compose.yml`](https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml) (Kafka broker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_controller["SMS controller<br/>[SmsController.java]"]
  node_request["Request validation<br/>[SmsRequest.java]"]
  node_exception["Error responses"]
  node_response["API response<br/>[ApiResponse.java]"]
end

subgraph group_producer["Message production"]
  node_producer_service["SMS producer"]
  node_api_message["Queued message<br/>[SmsMessage.java]"]
  node_kafka_config["Kafka producer config<br/>[KafkaConfig.java]"]
end

subgraph group_consumer["Message delivery"]
  node_consumer_config["Kafka consumer config"]
  node_consumer["Kafka listener"]
  node_consumer_message["Consumer message<br/>[SmsMessage.java]"]
  node_dispatcher["SMS dispatcher"]
end

subgraph group_platform["Messaging platform"]
  node_broker["Kafka broker<br/>[docker-compose.yml]"]
  node_zookeeper["Zookeeper<br/>[docker-compose.yml]"]
  node_kafka_ui["Kafka UI<br/>[docker-compose.yml]"]
end

node_client(("API client"))
node_sms_provider(("SMS provider"))

node_client -->|"submits request"| node_controller
node_controller -->|"validates"| node_request
node_controller -->|"routes validation errors"| node_exception
node_controller -->|"queues messages"| node_producer_service
node_producer_service -->|"creates"| node_api_message
node_producer_service -->|"uses producer"| node_kafka_config
node_producer_service -->|"publishes"| node_broker
node_controller -->|"returns accepted"| node_response
node_broker -->|"delivers topic records"| node_consumer
node_consumer_config -->|"configures listener"| node_consumer
node_consumer -->|"receives payload"| node_consumer_message
node_consumer -->|"dispatches"| node_dispatcher
node_dispatcher -.->|"sends SMS"| node_sms_provider
node_kafka_ui -->|"browses messages"| node_broker
node_zookeeper -->|"coordinates"| node_broker

click node_controller "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/controller/SmsController.java"
click node_request "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/SmsRequest.java"
click node_exception "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/controller/GlobalExceptionHandler.java"
click node_response "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/ApiResponse.java"
click node_producer_service "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/service/SmsProducerService.java"
click node_api_message "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/SmsMessage.java"
click node_kafka_config "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/config/KafkaConfig.java"
click node_broker "https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml"
click node_zookeeper "https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml"
click node_kafka_ui "https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml"
click node_consumer_config "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/config/KafkaConsumerConfig.java"
click node_consumer "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/consumer/SmsKafkaConsumer.java"
click node_consumer_message "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/dto/SmsMessage.java"
click node_dispatcher "https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/service/SmsDispatcherService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_request,node_exception,node_response,node_client toneBlue
class node_producer_service,node_api_message,node_kafka_config toneAmber
class node_consumer_config,node_consumer,node_consumer_message,node_dispatcher toneMint
class node_broker,node_zookeeper,node_kafka_ui toneRose
class node_sms_provider toneIndigo
```

## Components

### REST API

- [SMS controller](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/controller/SmsController.java): `sms-api/src/main/java/com/sms/controller/SmsController.java`
- [Request validation](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/SmsRequest.java): `sms-api/src/main/java/com/sms/dto/SmsRequest.java`
- [Error responses](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/controller/GlobalExceptionHandler.java): `sms-api/src/main/java/com/sms/controller/GlobalExceptionHandler.java`
- [API response](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/ApiResponse.java): `sms-api/src/main/java/com/sms/dto/ApiResponse.java`

### Message production

- [SMS producer](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/service/SmsProducerService.java): `sms-api/src/main/java/com/sms/service/SmsProducerService.java`
- [Queued message](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/dto/SmsMessage.java): `sms-api/src/main/java/com/sms/dto/SmsMessage.java`
- [Kafka producer config](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-api/src/main/java/com/sms/config/KafkaConfig.java): `sms-api/src/main/java/com/sms/config/KafkaConfig.java`

### Message delivery

- [Kafka consumer config](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/config/KafkaConsumerConfig.java): `sms-consumer/src/main/java/com/sms/config/KafkaConsumerConfig.java`
- [Kafka listener](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/consumer/SmsKafkaConsumer.java): `sms-consumer/src/main/java/com/sms/consumer/SmsKafkaConsumer.java`
- [Consumer message](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/dto/SmsMessage.java): `sms-consumer/src/main/java/com/sms/dto/SmsMessage.java`
- [SMS dispatcher](https://github.com/williamnyongesa/sms-notification-system/blob/main/sms-consumer/src/main/java/com/sms/service/SmsDispatcherService.java): `sms-consumer/src/main/java/com/sms/service/SmsDispatcherService.java`

### Messaging platform

- [Kafka broker](https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml): `docker-compose.yml`
- [Zookeeper](https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml): `docker-compose.yml`
- [Kafka UI](https://github.com/williamnyongesa/sms-notification-system/blob/main/docker-compose.yml): `docker-compose.yml`

### Other components

- **API client**
- **SMS provider**

## Connections

- API client → SMS controller: submits request
- SMS controller → Request validation: validates
- SMS controller → Error responses: routes validation errors
- SMS controller → SMS producer: queues messages
- SMS producer → Queued message: creates
- SMS producer → Kafka producer config: uses producer
- SMS producer → Kafka broker: publishes
- SMS controller → API response: returns accepted
- Kafka broker → Kafka listener: delivers topic records
- Kafka consumer config → Kafka listener: configures listener
- Kafka listener → Consumer message: receives payload
- Kafka listener → SMS dispatcher: dispatches
- SMS dispatcher → SMS provider: sends SMS
- Kafka UI → Kafka broker: browses messages
- Zookeeper → Kafka broker: coordinates