# firasama29/roadmap-newsletter architecture

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

- Interactive diagram: https://gitdiagram.com/firasama29/roadmap-newsletter
- Repository: https://github.com/firasama29/roadmap-newsletter

## Overview

This Spring Boot roadmap-newsletter service lets subscribers sign up, choose topics, and receive articles selected for their subscription day. It also exposes topic and article management APIs and a manual email-send endpoint. The scheduled newsletter service loads subscribers and matching articles, formats topic-grouped messages, and sends them by email. The graph follows the sampled controller/service/repository calls; README-level personalization is represented, but source excerpts do not establish signup-date scheduling behavior.

Main entry points: [`src/main/java/com/roadmap/newsletter/service/SubscriberService.java`](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/SubscriberService.java) (Subscriber Service), [`src/main/java/com/roadmap/newsletter/service/NewsletterService.java`](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/NewsletterService.java) (Newsletter Scheduler), [`src/main/java/com/roadmap/newsletter/controller/SubscriberController.java`](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/SubscriberController.java) (Subscriber API), [`src/main/java/com/roadmap/newsletter/repository/SubscriberRepository.java`](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/SubscriberRepository.java) (Subscriber Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP APIs"]
  node_subscriber_api["Subscriber API"]
  node_topic_api["Topic API"]
  node_article_api["Article API"]
  node_manual_api["Manual Email API"]
end

subgraph group_domain["Newsletter Domain"]
  node_subscriber_service["Subscriber Service"]
  node_topic_service["Topic Service<br/>[TopicService.java]"]
  node_article_service["Article Service"]
  node_newsletter_service["Newsletter Scheduler"]
end

subgraph group_data["Persistence"]
  node_subscriber_repo["Subscriber Repository"]
  node_topic_repo["Topic Repository"]
  node_article_repo["Article Repository"]
  node_database[("Relational Database")]
end

subgraph group_delivery["Email Delivery"]
  node_mail["Mail Service"]
end

node_subscriber(("Subscriber"))
node_admin(("Content Manager"))

node_subscriber -->|"signs up"| node_subscriber_api
node_subscriber_api -->|"dispatches"| node_subscriber_service
node_subscriber_service -->|"reads and saves"| node_subscriber_repo
node_subscriber_service -->|"lists topics"| node_topic_service
node_subscriber_service -->|"sends welcome"| node_mail
node_subscriber -->|"selects topics"| node_subscriber_api
node_subscriber_api -->|"dispatches"| node_subscriber_service
node_subscriber_service -->|"updates subscriptions"| node_subscriber_repo
node_admin -->|"manages topics"| node_topic_api
node_topic_api -->|"dispatches"| node_topic_service
node_topic_service -->|"queries and saves"| node_topic_repo
node_admin -->|"manages articles"| node_article_api
node_article_api -->|"dispatches"| node_article_service
node_article_service -->|"finds or saves topic"| node_topic_repo
node_article_service -->|"queries and saves"| node_article_repo
node_newsletter_service -->|"loads by day"| node_subscriber_repo
node_newsletter_service -->|"loads matching articles"| node_article_repo
node_newsletter_service -->|"sends newsletters"| node_mail
node_admin -->|"requests email"| node_manual_api
node_manual_api -->|"dispatches"| node_newsletter_service
node_newsletter_service -->|"sends message"| node_mail
node_subscriber_repo -->|"reads and writes"| node_database
node_topic_repo -->|"reads and writes"| node_database
node_article_repo -->|"reads and writes"| node_database

click node_subscriber_api "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/SubscriberController.java"
click node_topic_api "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/TopicController.java"
click node_article_api "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/ArticleController.java"
click node_manual_api "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/SubscriptionController.java"
click node_subscriber_service "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/SubscriberService.java"
click node_topic_service "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/TopicService.java"
click node_article_service "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/ArticleService.java"
click node_newsletter_service "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/NewsletterService.java"
click node_subscriber_repo "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/SubscriberRepository.java"
click node_topic_repo "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/TopicRepository.java"
click node_article_repo "https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/ArticleRepository.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_subscriber_api,node_topic_api,node_article_api,node_manual_api toneBlue
class node_subscriber_service,node_topic_service,node_article_service,node_newsletter_service toneAmber
class node_subscriber_repo,node_topic_repo,node_article_repo,node_database toneMint
class node_mail toneRose
class node_subscriber,node_admin toneIndigo
```

## Components

### HTTP APIs

- [Subscriber API](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/SubscriberController.java): `src/main/java/com/roadmap/newsletter/controller/SubscriberController.java`
- [Topic API](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/TopicController.java): `src/main/java/com/roadmap/newsletter/controller/TopicController.java`
- [Article API](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/ArticleController.java): `src/main/java/com/roadmap/newsletter/controller/ArticleController.java`
- [Manual Email API](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/controller/SubscriptionController.java): `src/main/java/com/roadmap/newsletter/controller/SubscriptionController.java`

### Newsletter Domain

- [Subscriber Service](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/SubscriberService.java): `src/main/java/com/roadmap/newsletter/service/SubscriberService.java`
- [Topic Service](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/TopicService.java): `src/main/java/com/roadmap/newsletter/service/TopicService.java`
- [Article Service](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/ArticleService.java): `src/main/java/com/roadmap/newsletter/service/ArticleService.java`
- [Newsletter Scheduler](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/service/NewsletterService.java): `src/main/java/com/roadmap/newsletter/service/NewsletterService.java`

### Persistence

- [Subscriber Repository](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/SubscriberRepository.java): `src/main/java/com/roadmap/newsletter/repository/SubscriberRepository.java`
- [Topic Repository](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/TopicRepository.java): `src/main/java/com/roadmap/newsletter/repository/TopicRepository.java`
- [Article Repository](https://github.com/firasama29/roadmap-newsletter/blob/main/src/main/java/com/roadmap/newsletter/repository/ArticleRepository.java): `src/main/java/com/roadmap/newsletter/repository/ArticleRepository.java`
- **Relational Database**

### Email Delivery

- **Mail Service**

### Other components

- **Subscriber**
- **Content Manager**

## Connections

- Subscriber → Subscriber API: signs up
- Subscriber API → Subscriber Service: dispatches
- Subscriber Service → Subscriber Repository: reads and saves
- Subscriber Service → Topic Service: lists topics
- Subscriber Service → Mail Service: sends welcome
- Subscriber → Subscriber API: selects topics
- Subscriber API → Subscriber Service: dispatches
- Subscriber Service → Subscriber Repository: updates subscriptions
- Content Manager → Topic API: manages topics
- Topic API → Topic Service: dispatches
- Topic Service → Topic Repository: queries and saves
- Content Manager → Article API: manages articles
- Article API → Article Service: dispatches
- Article Service → Topic Repository: finds or saves topic
- Article Service → Article Repository: queries and saves
- Newsletter Scheduler → Subscriber Repository: loads by day
- Newsletter Scheduler → Article Repository: loads matching articles
- Newsletter Scheduler → Mail Service: sends newsletters
- Content Manager → Manual Email API: requests email
- Manual Email API → Newsletter Scheduler: dispatches
- Newsletter Scheduler → Mail Service: sends message
- Subscriber Repository → Relational Database: reads and writes
- Topic Repository → Relational Database: reads and writes
- Article Repository → Relational Database: reads and writes