# mhdbadr/mail-system architecture

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

- Interactive diagram: https://gitdiagram.com/mhdbadr/mail-system
- Repository: https://github.com/mhdbadr/mail-system

## Overview

Mail Support System is a full-stack shared-mailbox application: authenticated support staff process imported customer messages as tickets, reply through a shared mailbox, and also use internal mail. The main path runs from the Angular workspace through authenticated REST operations to backend mail/ticket services and persistent state; IMAP import and SMTP sending support the external-mail lifecycle. The README documents the system integrations and behavior; source excerpts show selected query, reply, ticket, identity, and storage responsibilities, so unsampled implementation links are omitted or marked unverified.

Main entry points: [`backend/src/main/kotlin/de/thm/mni/backend/mail/MailController.kt`](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailController.kt) (Mail endpoints), [`backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt`](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt) (Ticket lifecycle), [`frontend/src/app/app.ts`](https://github.com/mhdbadr/mail-system/blob/main/frontend/src/app/app.ts) (Angular application), [`backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt`](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt) (Mailbox queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workspace"]
  node_angular["Angular application<br/>[app.ts]"]
  node_mail_ui["Mail workspace"]
  node_ticket_ui["Ticket workspace"]
  node_mail_api_client["Mail API client<br/>[mails-service.ts]"]
  node_ticket_api_client["Ticket API client<br/>[tickets-service.ts]"]
end

subgraph group_identity["Identity and access"]
  node_oidc_client["OIDC client<br/>[auth-service.ts]"]
  node_keycloak["Keycloak"]
  node_security["API security<br/>[SecurityConfig.kt]"]
  node_user_profiles[("User profiles<br/>[User.kt]")]
end

subgraph group_mail["Mail workflows"]
  node_mail_api["Mail endpoints<br/>[MailController.kt]"]
  node_mail_queries["Mailbox queries"]
  node_mail_record_service["Recipient records"]
  node_mail_store[("Mail records<br/>[Mail.kt]")]
  node_internal_replies["Internal replies"]
  node_support_replies["Support replies"]
  node_imap_import["IMAP import"]
  node_imap_service["IMAP polling<br/>[IMAPService.kt]"]
  node_smtp_sender["SMTP sender<br/>[SMTPService.kt]"]
  node_mail_record_store[("Recipient record store")]
end

subgraph group_tickets["Support tickets"]
  node_ticket_api["Ticket endpoints"]
  node_ticket_lifecycle["Ticket lifecycle"]
  node_ticket_service["Ticket operations"]
  node_ticket_store[("Ticket state<br/>[SupportTicket.kt]")]
end

subgraph group_persistence["Persistence and attachments"]
  node_attachment_metadata[("Attachment metadata<br/>[Attachment.kt]")]
  node_storage_facade["File storage"]
  node_s3_storage["S3 attachment store"]
end

node_staff(("Support staff"))
node_mailbox["Support mailbox"]
node_object_store[("SeaweedFS storage")]

node_staff -->|"uses"| node_angular
node_angular -->|"starts sign-in"| node_oidc_client
node_oidc_client -->|"authenticates"| node_keycloak
node_angular -->|"routes to"| node_mail_ui
node_angular -->|"routes to"| node_ticket_ui
node_mail_ui -.->|"requests mail"| node_mail_api_client
node_ticket_ui -.->|"requests tickets"| node_ticket_api_client
node_mail_api_client -->|"calls API"| node_mail_api
node_ticket_api_client -->|"calls API"| node_ticket_api
node_keycloak -->|"issues tokens"| node_security
node_mail_api -.->|"delegates queries"| node_mail_queries
node_mail_queries -->|"reads mails"| node_mail_store
node_mail_queries -->|"queries recipients"| node_mail_record_service
node_mail_record_service -->|"reads and writes"| node_mail_record_store
node_mail_api -.->|"handles internal mail"| node_internal_replies
node_mail_api -.->|"handles support replies"| node_support_replies
node_support_replies -->|"attaches reply"| node_ticket_lifecycle
node_ticket_api -.->|"changes ticket state"| node_ticket_lifecycle
node_ticket_lifecycle -->|"generates ticket code"| node_ticket_service
node_ticket_lifecycle -->|"persists transitions"| node_ticket_store
node_imap_service -.->|"polls messages"| node_imap_import
node_imap_import -->|"imports messages"| node_mailbox
node_imap_import -.->|"associates incoming mail"| node_ticket_lifecycle
node_support_replies -.->|"sends replies"| node_smtp_sender
node_smtp_sender -->|"delivers mail"| node_mailbox
node_mail_api -.->|"manages attachments"| node_storage_facade
node_storage_facade -->|"delegates storage"| node_s3_storage
node_s3_storage -->|"stores binaries"| node_object_store
node_storage_facade -->|"returns metadata"| node_attachment_metadata
node_security -.->|"resolves identity"| node_user_profiles

click node_angular "https://github.com/mhdbadr/mail-system/blob/main/frontend/src/app/app.ts"
click node_mail_ui "https://github.com/mhdbadr/mail-system/tree/main/frontend/src/pages/mails"
click node_ticket_ui "https://github.com/mhdbadr/mail-system/tree/main/frontend/src/pages/tickets"
click node_mail_api_client "https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/mails/mails-service.ts"
click node_ticket_api_client "https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/tickets/tickets-service.ts"
click node_oidc_client "https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/auth/auth-service.ts"
click node_security "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/security/SecurityConfig.kt"
click node_user_profiles "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/user/User.kt"
click node_mail_api "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailController.kt"
click node_mail_queries "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt"
click node_mail_record_service "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordService.kt"
click node_mail_store "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/Mail.kt"
click node_internal_replies "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/internal/InternalReplyService.kt"
click node_support_replies "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/external/SupportReplyService.kt"
click node_imap_import "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/external/MailImportService.kt"
click node_imap_service "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/imap/IMAPService.kt"
click node_smtp_sender "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/smtp/SMTPService.kt"
click node_ticket_api "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketController.kt"
click node_ticket_lifecycle "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt"
click node_ticket_service "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketService.kt"
click node_ticket_store "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicket.kt"
click node_attachment_metadata "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/attachment/Attachment.kt"
click node_storage_facade "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/storage/FileStorageService.kt"
click node_s3_storage "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/storage/s3/S3AttachmentStorage.kt"
click node_mail_record_store "https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordRepository.kt"

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_angular,node_mail_ui,node_ticket_ui,node_mail_api_client,node_ticket_api_client toneBlue
class node_oidc_client,node_keycloak,node_security,node_user_profiles,node_object_store toneAmber
class node_mail_api,node_mail_queries,node_mail_record_service,node_mail_store,node_internal_replies,node_support_replies,node_imap_import,node_imap_service,node_smtp_sender,node_mail_record_store toneMint
class node_ticket_api,node_ticket_lifecycle,node_ticket_service,node_ticket_store toneRose
class node_attachment_metadata,node_storage_facade,node_s3_storage,node_staff,node_mailbox toneIndigo
```

## Components

### Web workspace

- [Angular application](https://github.com/mhdbadr/mail-system/blob/main/frontend/src/app/app.ts): `frontend/src/app/app.ts`
- [Mail workspace](https://github.com/mhdbadr/mail-system/tree/main/frontend/src/pages/mails): `frontend/src/pages/mails`
- [Ticket workspace](https://github.com/mhdbadr/mail-system/tree/main/frontend/src/pages/tickets): `frontend/src/pages/tickets`
- [Mail API client](https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/mails/mails-service.ts): `frontend/src/services/mails/mails-service.ts`
- [Ticket API client](https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/tickets/tickets-service.ts): `frontend/src/services/tickets/tickets-service.ts`

### Identity and access

- [OIDC client](https://github.com/mhdbadr/mail-system/blob/main/frontend/src/services/auth/auth-service.ts): `frontend/src/services/auth/auth-service.ts`
- **Keycloak**
- [API security](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/security/SecurityConfig.kt): `backend/src/main/kotlin/de/thm/mni/backend/security/SecurityConfig.kt`
- [User profiles](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/user/User.kt): `backend/src/main/kotlin/de/thm/mni/backend/user/User.kt`

### Mail workflows

- [Mail endpoints](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailController.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/MailController.kt`
- [Mailbox queries](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt`
- [Recipient records](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordService.kt): `backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordService.kt`
- [Mail records](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/Mail.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/Mail.kt`
- [Internal replies](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/internal/InternalReplyService.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/internal/InternalReplyService.kt`
- [Support replies](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/external/SupportReplyService.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/external/SupportReplyService.kt`
- [IMAP import](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mail/external/MailImportService.kt): `backend/src/main/kotlin/de/thm/mni/backend/mail/external/MailImportService.kt`
- [IMAP polling](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/imap/IMAPService.kt): `backend/src/main/kotlin/de/thm/mni/backend/imap/IMAPService.kt`
- [SMTP sender](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/smtp/SMTPService.kt): `backend/src/main/kotlin/de/thm/mni/backend/smtp/SMTPService.kt`
- [Recipient record store](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordRepository.kt): `backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordRepository.kt`

### Support tickets

- [Ticket endpoints](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketController.kt): `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketController.kt`
- [Ticket lifecycle](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt): `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt`
- [Ticket operations](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketService.kt): `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketService.kt`
- [Ticket state](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicket.kt): `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicket.kt`

### Persistence and attachments

- [Attachment metadata](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/attachment/Attachment.kt): `backend/src/main/kotlin/de/thm/mni/backend/attachment/Attachment.kt`
- [File storage](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/storage/FileStorageService.kt): `backend/src/main/kotlin/de/thm/mni/backend/storage/FileStorageService.kt`
- [S3 attachment store](https://github.com/mhdbadr/mail-system/blob/main/backend/src/main/kotlin/de/thm/mni/backend/storage/s3/S3AttachmentStorage.kt): `backend/src/main/kotlin/de/thm/mni/backend/storage/s3/S3AttachmentStorage.kt`

### Other components

- **Support staff**
- **Support mailbox**
- **SeaweedFS storage**

## Connections

- Support staff → Angular application: uses
- Angular application → OIDC client: starts sign-in
- OIDC client → Keycloak: authenticates
- Angular application → Mail workspace: routes to
- Angular application → Ticket workspace: routes to
- Mail workspace → Mail API client: requests mail
- Ticket workspace → Ticket API client: requests tickets
- Mail API client → Mail endpoints: calls API
- Ticket API client → Ticket endpoints: calls API
- Keycloak → API security: issues tokens
- Mail endpoints → Mailbox queries: delegates queries
- Mailbox queries → Mail records: reads mails (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt`)
- Mailbox queries → Recipient records: queries recipients (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mail/MailQueryService.kt`)
- Recipient records → Recipient record store: reads and writes (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mailrecord/MailRecordService.kt`)
- Mail endpoints → Internal replies: handles internal mail
- Mail endpoints → Support replies: handles support replies
- Support replies → Ticket lifecycle: attaches reply (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mail/external/SupportReplyService.kt`)
- Ticket endpoints → Ticket lifecycle: changes ticket state
- Ticket lifecycle → Ticket operations: generates ticket code (evidence: `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt`)
- Ticket lifecycle → Ticket state: persists transitions (evidence: `backend/src/main/kotlin/de/thm/mni/backend/ticket/SupportTicketLifecycleService.kt`)
- IMAP polling → IMAP import: polls messages (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mail/external/MailImportService.kt`)
- IMAP import → Support mailbox: imports messages
- IMAP import → Ticket lifecycle: associates incoming mail (evidence: `backend/src/main/kotlin/de/thm/mni/backend/mail/external/MailImportService.kt`)
- Support replies → SMTP sender: sends replies
- SMTP sender → Support mailbox: delivers mail
- Mail endpoints → File storage: manages attachments
- File storage → S3 attachment store: delegates storage (evidence: `backend/src/main/kotlin/de/thm/mni/backend/storage/FileStorageService.kt`)
- S3 attachment store → SeaweedFS storage: stores binaries
- File storage → Attachment metadata: returns metadata
- API security → User profiles: resolves identity
