# hamza-lgtm/teams-notification-bot architecture

> Architecture diagram of the GitHub repository hamza-lgtm/teams-notification-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamza-lgtm/teams-notification-bot
- Repository: https://github.com/hamza-lgtm/teams-notification-bot

## Overview

1. **System shape**  
   This is a **Spring Boot backend** for a Microsoft Teams notification bot. It is not a frontend app; the main runtime is a Java service that exposes an HTTP API and integrates with Teams bot messaging.

2. **Primary entry points**  
   `TeamsNotificationBotApplication` is the Spring Boot bootstrap class. From there, the app wires together the bot, REST controller, security, persistence, and message-delivery services.

3. **Inbound traffic paths**  
   There are two main inbound entry points:
   - A **REST API** exposed by `NotificationController`, used to submit notification requests such as `POST /api/notification/send`.
   - A **Teams bot interaction path** handled by `NotificationBot`, which is the Teams-facing component for bot-driven communication.

4. **Request protection and web wiring**  
   `SecurityConfig` and `ApiKeyAuthFilter` indicate the API is protected by **API-key-based authentication**. `WebConfig` likely configures MVC/web integration for the service endpoints and bot-related HTTP handling.

5. **Core business services**  
   The service layer is split into three focused components:
   - `MessageService` for notification/message orchestration.
   - `ChannelService` for resolving and managing channel-related targets.
   - `TeamsMessageService` for sending messages into Microsoft Teams and handling Teams-specific delivery logic.

6. **Domain model**  
   The app persists two main business entities:
   - `TeamsUser` for user-level notification recipients and verification/enablement state.
   - `ChannelInfo` for channel-level targets and configuration.

7. **Persistence boundary**  
   `TeamsUserRepository` and `ChannelInfoRepository` are the data-access layer. The repository naming strongly suggests **Spring Data persistence** behind the service layer, with services depending on repositories rather than controllers talking to storage directly.

8. **External integrations**  
   The repository is centered on **Microsoft Teams** and its bot ecosystem. The README also calls out:
   - **voice calls with text-to-speech**
   - **email verification**
   - **notification enable/disable controls**  
   So the main outbound integrations are Teams messaging and a voice-call/TTS capability, with email used as part of user verification.

9. **Localization and message content**  
   `src/main/resources/messages.properties` and `messages_fr.properties` show the app supports **localized user-facing text**, at least English and French. That makes message rendering part of the delivery pipeline rather than hardcoded in controllers.

10. **Deployment and packaging**  
   The `teams-manifest/` directory contains Teams app manifest files and a packaged zip, which means the bot is designed to be installed into Teams as a Teams application. `Publishing_to_Microsoft.md` and the README’s Azure/ngrok references indicate both local tunneling and Azure-hosted deployment are part of the operational model.

11. **Build/runtime footprint**  
   The project uses **Maven** and targets **Java 11+**. The `target/` directory shows standard Maven build outputs, while `pom.xml` is the central build definition for dependencies and packaging.

12. **End-to-end data flow**  
   A typical notification flow is: client submits a request to the REST API → API key is validated → controller hands off to services → services resolve the recipient/channel via repositories → Teams delivery is performed through the Teams bot/message layer → optional voice-call/TTS follow-up is triggered. The bot path is separate but shares the same domain and delivery services.

Main entry points: [`src/main/java/com/teamsbot/service/MessageService.java`](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/MessageService.java) (Message Service), [`src/main/java/com/teamsbot/TeamsNotificationBotApplication.java`](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/TeamsNotificationBotApplication.java) (App), [`src/main/java/com/teamsbot/service/ChannelService.java`](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/ChannelService.java) (Channel Service), [`src/main/java/com/teamsbot/service/TeamsMessageService.java`](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/TeamsMessageService.java) (Teams Delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app(("App"))
end

subgraph group_web["Web API"]
  node_bot["Teams Bot<br/>bot endpoint"]
  node_controller["Notification API<br/>REST controller"]
end

subgraph group_service["Services"]
  node_message_service["Message Service<br/>orchestrator"]
  node_channel_service["Channel Service<br/>target resolver"]
  node_teams_message_service["Teams Delivery<br/>delivery service"]
end

subgraph group_domain["Domain"]
  node_teams_user["Teams User<br/>entity<br/>[TeamsUser.java]"]
  node_channel_info["Channel Info<br/>entity<br/>[ChannelInfo.java]"]
end

subgraph group_persistence["Persistence"]
  node_user_repo[("User Repo<br/>spring data repo")]
  node_channel_repo[("Channel Repo<br/>spring data repo")]
end

subgraph group_config["Config"]
  node_security["Security<br/>api key auth"]
  node_api_filter["API Key Filter<br/>security filter"]
  node_web_config["Web Config<br/>mvc config<br/>[WebConfig.java]"]
  node_bot_config["Bot Config<br/>bot wiring<br/>[BotConfig.java]"]
  node_messages_en["Messages EN<br/>localization bundle"]
  node_messages_fr["Messages FR<br/>localization bundle"]
end

subgraph group_packaging["Packaging"]
  node_manifest["Teams Manifest<br/>deployment artifact<br/>[manifest.json]"]
  node_manifest_fr["Manifest FR<br/>deployment artifact"]
  node_publish_doc["Publish Guide<br/>deployment docs"]
end

node_app -->|"wires"| node_bot
node_app -->|"wires"| node_controller
node_app -->|"loads"| node_security
node_app -->|"loads"| node_web_config
node_app -->|"loads"| node_bot_config
node_security -->|"uses"| node_api_filter
node_controller -->|"delegates"| node_message_service
node_bot -->|"delegates"| node_message_service
node_message_service -->|"resolves"| node_channel_service
node_message_service -->|"delivers"| node_teams_message_service
node_channel_service -->|"reads"| node_channel_repo
node_message_service -->|"reads"| node_user_repo
node_message_service -->|"uses"| node_teams_user
node_channel_service -->|"uses"| node_channel_info
node_user_repo -->|"stores"| node_teams_user
node_channel_repo -->|"stores"| node_channel_info
node_teams_message_service -->|"localizes"| node_messages_en
node_teams_message_service -->|"localizes"| node_messages_fr
node_bot_config -->|"configures"| node_bot
node_publish_doc -.->|"describes"| node_manifest
node_publish_doc -.->|"describes"| node_manifest_fr

click node_app "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/TeamsNotificationBotApplication.java"
click node_bot "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/bot/NotificationBot.java"
click node_controller "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/controller/NotificationController.java"
click node_security "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/SecurityConfig.java"
click node_api_filter "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/ApiKeyAuthFilter.java"
click node_web_config "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/WebConfig.java"
click node_bot_config "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/BotConfig.java"
click node_message_service "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/MessageService.java"
click node_channel_service "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/ChannelService.java"
click node_teams_message_service "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/TeamsMessageService.java"
click node_teams_user "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/model/TeamsUser.java"
click node_channel_info "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/model/ChannelInfo.java"
click node_user_repo "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/repository/TeamsUserRepository.java"
click node_channel_repo "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/repository/ChannelInfoRepository.java"
click node_messages_en "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/resources/messages.properties"
click node_messages_fr "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/resources/messages_fr.properties"
click node_manifest "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/teams-manifest/manifest.json"
click node_manifest_fr "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/teams-manifest/manifest.fr-fr.json"
click node_publish_doc "https://github.com/hamza-lgtm/teams-notification-bot/blob/master/Publishing_to_Microsoft.md"

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_app,node_manifest,node_manifest_fr,node_publish_doc toneBlue
class node_bot,node_controller toneAmber
class node_message_service,node_channel_service,node_teams_message_service toneMint
class node_teams_user,node_channel_info toneRose
class node_user_repo,node_channel_repo toneIndigo
class node_security,node_api_filter,node_web_config,node_bot_config,node_messages_en,node_messages_fr toneTeal
```

## Components

### Runtime

Spring Boot application and bot entry points

- [App](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/TeamsNotificationBotApplication.java): Spring Boot app · Main application bootstrap for the notification bot · `src/main/java/com/teamsbot/TeamsNotificationBotApplication.java`

### Web API

HTTP and bot-facing inbound handling

- [Teams Bot](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/bot/NotificationBot.java): bot endpoint · Teams-facing bot interaction handler · `src/main/java/com/teamsbot/bot/NotificationBot.java`
- [Notification API](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/controller/NotificationController.java): REST controller · HTTP entry point for notification requests · `src/main/java/com/teamsbot/controller/NotificationController.java`

### Services

Business orchestration and delivery logic

- [Message Service](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/MessageService.java): orchestrator · Coordinates notification requests and delivery flow · `src/main/java/com/teamsbot/service/MessageService.java`
- [Channel Service](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/ChannelService.java): target resolver · Resolves and manages channel targets · `src/main/java/com/teamsbot/service/ChannelService.java`
- [Teams Delivery](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/service/TeamsMessageService.java): delivery service · Sends messages into Microsoft Teams and related delivery steps · `src/main/java/com/teamsbot/service/TeamsMessageService.java`

### Domain

Persistent business entities

- [Teams User](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/model/TeamsUser.java): entity · Recipient and verification state for notification users · `src/main/java/com/teamsbot/model/TeamsUser.java`
- [Channel Info](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/model/ChannelInfo.java): entity · Channel target and configuration data · `src/main/java/com/teamsbot/model/ChannelInfo.java`

### Persistence

Repository access layer

- [User Repo](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/repository/TeamsUserRepository.java): spring data repo · Persistence access for Teams users · `src/main/java/com/teamsbot/repository/TeamsUserRepository.java`
- [Channel Repo](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/repository/ChannelInfoRepository.java): spring data repo · Persistence access for channel records · `src/main/java/com/teamsbot/repository/ChannelInfoRepository.java`

### Config

Application wiring and security

- [Security](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/SecurityConfig.java): api key auth · Web security configuration for protected API access · `src/main/java/com/teamsbot/config/SecurityConfig.java`
- [API Key Filter](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/ApiKeyAuthFilter.java): security filter · Validates API-key authenticated requests · `src/main/java/com/teamsbot/config/ApiKeyAuthFilter.java`
- [Web Config](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/WebConfig.java): mvc config · HTTP and MVC wiring for the service · `src/main/java/com/teamsbot/config/WebConfig.java`
- [Bot Config](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/java/com/teamsbot/config/BotConfig.java): bot wiring · Configuration for Teams bot integration · `src/main/java/com/teamsbot/config/BotConfig.java`
- [Messages EN](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/resources/messages.properties): localization bundle · Default localized user-facing text · `src/main/resources/messages.properties`
- [Messages FR](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/src/main/resources/messages_fr.properties): localization bundle · French localized user-facing text · `src/main/resources/messages_fr.properties`

### Packaging

Teams deployment artifacts and docs

- [Teams Manifest](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/teams-manifest/manifest.json): deployment artifact · Teams app packaging and install manifest · `teams-manifest/manifest.json`
- [Manifest FR](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/teams-manifest/manifest.fr-fr.json): deployment artifact · French Teams app manifest · `teams-manifest/manifest.fr-fr.json`
- [Publish Guide](https://github.com/hamza-lgtm/teams-notification-bot/blob/master/Publishing_to_Microsoft.md): deployment docs · Instructions for publishing and deployment · `Publishing_to_Microsoft.md`

## Connections

- App → Teams Bot: wires · Bootstraps Teams bot component
- App → Notification API: wires · Exposes REST API entry point
- App → Security: loads · Applies web security configuration
- App → Web Config: loads · Configures HTTP handling
- App → Bot Config: loads · Registers bot integration settings
- Security → API Key Filter: uses · Installs API-key authentication filter
- Notification API → Message Service: delegates · Submits notification requests to service layer
- Teams Bot → Message Service: delegates · Reuses shared message orchestration
- Message Service → Channel Service: resolves · Looks up channel targets
- Message Service → Teams Delivery: delivers · Triggers Teams message sending
- Channel Service → Channel Repo: reads · Accesses channel persistence
- Message Service → User Repo: reads · Accesses recipient state
- Message Service → Teams User: uses · Operates on user notification state
- Channel Service → Channel Info: uses · Operates on channel configuration
- User Repo → Teams User: stores · Persists user records
- Channel Repo → Channel Info: stores · Persists channel records
- Teams Delivery → Messages EN: localizes · Uses message templates
- Teams Delivery → Messages FR: localizes · Uses message templates
- Bot Config → Teams Bot: configures · Provides bot runtime wiring
- Publish Guide → Teams Manifest: describes · Documents Teams packaging
- Publish Guide → Manifest FR: describes · Documents localized Teams packaging
