# airis-nst-ru/newletter_service architecture

> Architecture diagram of the GitHub repository airis-nst-ru/newletter_service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/airis-nst-ru/newletter_service
- Repository: https://github.com/airis-nst-ru/newletter_service

## Overview

AIRIS Chronicle is a newsletter authoring and delivery product. Its frontend tree covers newsletter editing, review and preview, recipient management, comments, and subscriber actions; its backend exposes a newsletter-send endpoint that validates recipients, sends batched email, and streams progress. Frontend route and page implementations were not sampled, and the README is empty, so connections among those capabilities and their integration with the backend are not asserted. Backend edges shown below are supported by the sampled source and SOURCE INDEX.

Main entry points: [`backend/src/controllers/send.controller.ts`](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/send.controller.ts) (Send controller), [`backend/src/app.ts`](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/app.ts) (Express application), [`backend/src/controllers/healthcheck.controller.ts`](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/healthcheck.controller.ts) (Health controller), [`backend/src/service/mail.service.ts`](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/service/mail.service.ts) (Bulk mail service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Newsletter authoring"]
  node_writer["Newsletter editor"]
  node_media["Media manager<br/>[MediaManager.tsx]"]
  node_preview["Newsletter preview<br/>[PreviewClient.tsx]"]
  node_compiler["HTML compiler<br/>[htmlCompiler.ts]"]
end

subgraph group_audience["Review and audience"]
  node_review["Approver review"]
  node_comments["Newsletter comments<br/>[CommentThread.tsx]"]
  node_blog["Newsletter blog<br/>[BlogHomeClient.tsx]"]
  node_recipients_ui["Recipient management<br/>[page.tsx]"]
  node_subscriber_actions["Subscriber actions"]
end

subgraph group_frontend_api["Frontend API"]
  node_newsletter_api["Newsletter API<br/>[route.ts]"]
  node_newsletter_state["Newsletter state API<br/>[route.ts]"]
  node_comments_api["Comments API<br/>[route.ts]"]
  node_recipients_api["Recipients API<br/>[route.ts]"]
  node_subscriber_api["Subscriber API<br/>[route.ts]"]
  node_send_api["Newsletter send API<br/>[route.ts]"]
end

subgraph group_delivery["Email delivery"]
  node_mail_service["Bulk mail service<br/>[mail.service.ts]"]
  node_template["Fallback template<br/>[v2_readmore.ts]"]
end

subgraph group_backend_platform["Backend platform"]
  node_send_route["Send endpoint route<br/>[send.routes.ts]"]
  node_send_controller["Send controller<br/>[send.controller.ts]"]
  node_socket["Progress sockets<br/>[socket.ts]"]
  node_http_app["Express application<br/>[app.ts]"]
  node_health_route["Health route"]
  node_health_controller["Health controller"]
  node_response["API response helper<br/>[response.util.ts]"]
  node_config["Environment config<br/>[envConfig.ts]"]
  node_logger["Application logger<br/>[logger.ts]"]
end

node_smtp(("Gmail SMTP"))

node_http_app -->|"mounts at"| node_send_route
node_http_app -->|"mounts at"| node_health_route
node_send_route -->|"routes POST"| node_send_controller
node_health_route -->|"routes GET"| node_health_controller
node_send_controller -->|"sends via"| node_mail_service
node_send_controller -->|"falls back to"| node_template
node_mail_service -->|"sends mail"| node_smtp
node_send_controller -->|"emits progress"| node_socket
node_send_controller -->|"logs"| node_logger
node_health_controller -->|"formats response"| node_response
node_health_controller -->|"reads name"| node_config
node_http_app -->|"logs requests"| node_logger

click node_writer "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/editor/NewsletterEditor.tsx"
click node_media "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/editor/MediaManager.tsx"
click node_preview "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/preview/PreviewClient.tsx"
click node_compiler "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/lib/htmlCompiler.ts"
click node_review "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/approver/ApproverReviewClient.tsx"
click node_comments "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/comments/CommentThread.tsx"
click node_blog "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/blog/BlogHomeClient.tsx"
click node_recipients_ui "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/recipients/page.tsx"
click node_subscriber_actions "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/unsubscribe/UnsubscribeClient.tsx"
click node_newsletter_api "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/route.ts"
click node_newsletter_state "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/%5Bid%5D/state/route.ts"
click node_comments_api "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/%5Bid%5D/comments/route.ts"
click node_recipients_api "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/recipients/route.ts"
click node_subscriber_api "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/unsubscribe/route.ts"
click node_send_api "https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/send-newsletter/route.ts"
click node_send_route "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/routes/send.routes.ts"
click node_send_controller "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/send.controller.ts"
click node_mail_service "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/service/mail.service.ts"
click node_template "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/template/v2_readmore.ts"
click node_socket "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/socket.ts"
click node_http_app "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/app.ts"
click node_health_route "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/routes/healthcheck.routes.ts"
click node_health_controller "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/healthcheck.controller.ts"
click node_response "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/utils/response.util.ts"
click node_config "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/config/envConfig.ts"
click node_logger "https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/logger/logger.ts"

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_writer,node_media,node_preview,node_compiler toneBlue
class node_review,node_comments,node_blog,node_recipients_ui,node_subscriber_actions toneAmber
class node_newsletter_api,node_newsletter_state,node_comments_api,node_recipients_api,node_subscriber_api,node_send_api toneMint
class node_mail_service,node_template toneRose
class node_send_route,node_send_controller,node_socket,node_http_app,node_health_route,node_health_controller,node_response,node_config,node_logger,node_smtp toneIndigo
```

## Components

### Newsletter authoring

- [Newsletter editor](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/editor/NewsletterEditor.tsx): `frontend/components/editor/NewsletterEditor.tsx`
- [Media manager](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/editor/MediaManager.tsx): `frontend/components/editor/MediaManager.tsx`
- [Newsletter preview](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/preview/PreviewClient.tsx): `frontend/components/preview/PreviewClient.tsx`
- [HTML compiler](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/lib/htmlCompiler.ts): `frontend/lib/htmlCompiler.ts`

### Review and audience

- [Approver review](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/approver/ApproverReviewClient.tsx): `frontend/components/approver/ApproverReviewClient.tsx`
- [Newsletter comments](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/comments/CommentThread.tsx): `frontend/components/comments/CommentThread.tsx`
- [Newsletter blog](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/components/blog/BlogHomeClient.tsx): `frontend/components/blog/BlogHomeClient.tsx`
- [Recipient management](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/recipients/page.tsx): `frontend/app/recipients/page.tsx`
- [Subscriber actions](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/unsubscribe/UnsubscribeClient.tsx): `frontend/app/unsubscribe/UnsubscribeClient.tsx`

### Frontend API

- [Newsletter API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/route.ts): `frontend/app/api/v1/newsletters/route.ts`
- [Newsletter state API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/%5Bid%5D/state/route.ts): `frontend/app/api/v1/newsletters/[id]/state/route.ts`
- [Comments API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/newsletters/%5Bid%5D/comments/route.ts): `frontend/app/api/v1/newsletters/[id]/comments/route.ts`
- [Recipients API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/recipients/route.ts): `frontend/app/api/v1/email/recipients/route.ts`
- [Subscriber API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/unsubscribe/route.ts): `frontend/app/api/v1/email/unsubscribe/route.ts`
- [Newsletter send API](https://github.com/airis-nst-ru/newletter_service/blob/main/frontend/app/api/v1/email/send-newsletter/route.ts): `frontend/app/api/v1/email/send-newsletter/route.ts`

### Email delivery

- [Bulk mail service](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/service/mail.service.ts): `backend/src/service/mail.service.ts`
- [Fallback template](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/template/v2_readmore.ts): `backend/src/template/v2_readmore.ts`

### Backend platform

- [Send endpoint route](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/routes/send.routes.ts): `backend/src/routes/send.routes.ts`
- [Send controller](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/send.controller.ts): `backend/src/controllers/send.controller.ts`
- [Progress sockets](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/socket.ts): `backend/src/socket.ts`
- [Express application](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Health route](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/routes/healthcheck.routes.ts): `backend/src/routes/healthcheck.routes.ts`
- [Health controller](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/controllers/healthcheck.controller.ts): `backend/src/controllers/healthcheck.controller.ts`
- [API response helper](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/utils/response.util.ts): `backend/src/utils/response.util.ts`
- [Environment config](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/config/envConfig.ts): `backend/src/config/envConfig.ts`
- [Application logger](https://github.com/airis-nst-ru/newletter_service/blob/main/backend/src/logger/logger.ts): `backend/src/logger/logger.ts`

### Other components

- **Gmail SMTP**

## Connections

- Express application → Send endpoint route: mounts at (evidence: `backend/src/app.ts`)
- Express application → Health route: mounts at (evidence: `backend/src/app.ts`)
- Send endpoint route → Send controller: routes POST (evidence: `backend/src/routes/send.routes.ts`)
- Health route → Health controller: routes GET (evidence: `backend/src/routes/healthcheck.routes.ts`)
- Send controller → Bulk mail service: sends via (evidence: `backend/src/controllers/send.controller.ts`)
- Send controller → Fallback template: falls back to (evidence: `backend/src/controllers/send.controller.ts`)
- Bulk mail service → Gmail SMTP: sends mail (evidence: `backend/src/service/mail.service.ts`)
- Send controller → Progress sockets: emits progress (evidence: `backend/src/controllers/send.controller.ts`)
- Send controller → Application logger: logs (evidence: `backend/src/controllers/send.controller.ts`)
- Health controller → API response helper: formats response (evidence: `backend/src/controllers/healthcheck.controller.ts`)
- Health controller → Environment config: reads name (evidence: `backend/src/controllers/healthcheck.controller.ts`)
- Express application → Application logger: logs requests (evidence: `backend/src/app.ts`)