# kemalq/feedback-bot architecture

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

- Interactive diagram: https://gitdiagram.com/kemalq/feedback-bot
- Repository: https://github.com/kemalq/feedback-bot

## Overview

Feedback Processing System collects anonymous employee feedback through Telegram, processes it asynchronously, and routes analysis into tracking and resolution workflows. Users onboard with role and branch selections, submit text or voice feedback, and receive bot responses; critical findings can become Trello cards, while feedback is logged to Sheets. A separate admin API supports authentication, invite-token management, and feedback review/resolution. The graph follows the documented architecture and available entry-point contracts; detailed internal wiring for unsampled services is not assumed.

Main entry points: [`node/src/main/java/com/feedbackbot/service/impl/FeedbackProcessingServiceImpl.java`](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/FeedbackProcessingServiceImpl.java) (Feedback Processing), [`node/src/main/java/com/feedbackbot/service/impl/MainServiceImpl.java`](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/MainServiceImpl.java) (Conversation Logic), [`node/src/main/java/com/feedbackbot/listener/RabbitMessageListener.java`](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/listener/RabbitMessageListener.java) (Message Listener), [`rest-service/src/main/java/com/feedbackbot/auth/controller/AuthController.java`](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/controller/AuthController.java) (Auth Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram Interaction"]
  node_webhook["Webhook Controller"]
  node_updates["Update Processor"]
  node_bot["Telegram Bot<br/>[TelegramBot.java]"]
  node_messaging_app["Messaging Application"]
  node_main_service["Conversation Logic"]
  node_answer_consumer["Answer Consumer"]
end

subgraph group_processing["Feedback Processing"]
  node_producer["Event Producer"]
  node_listener["Message Listener"]
  node_validator["Message Validator"]
  node_feedback_processing["Feedback Processing"]
  node_transcription["Voice Transcription"]
  node_analysis["AI Analysis"]
  node_sheets["Google Sheets"]
  node_trello["Trello Integration"]
end

subgraph group_admin["Administration API"]
  node_invite_tokens["Invite Tokens"]
  node_auth_controller["Auth Controller"]
  node_auth_service["Authentication Service"]
  node_jwt["JWT Service<br/>[JwtService.java]"]
  node_feedback_controller["Feedback Controller"]
  node_feedback_service["Feedback Service"]
  node_token_controller["Token Controller"]
end

subgraph group_shared["Shared Data"]
  node_feedback_dao["Feedback Repository"]
  node_auth_store["Auth Repositories"]
  node_invite_dao["Invite Repository"]
end

node_employee(("Employee"))
node_telegram_api["Telegram API"]
node_rabbit["RabbitMQ"]
node_database[("PostgreSQL")]
node_admin_actor(("Administrator"))
node_groq["Groq API"]
node_sheets_api["Google Sheets API"]
node_trello_api["Trello API"]

node_employee -->|"submits feedback"| node_telegram_api
node_telegram_api -->|"delivers updates"| node_webhook
node_webhook -->|"forwards update"| node_updates
node_updates -->|"dispatches update"| node_messaging_app
node_messaging_app -->|"handles conversation"| node_main_service
node_main_service -.->|"validates invite"| node_invite_tokens
node_main_service -->|"publishes feedback"| node_producer
node_producer -->|"publishes event"| node_rabbit
node_rabbit -->|"delivers event"| node_listener
node_listener -->|"validates message"| node_validator
node_listener -->|"processes message"| node_feedback_processing
node_feedback_processing -.->|"transcribes voice"| node_transcription
node_transcription -.->|"requests transcription"| node_groq
node_feedback_processing -->|"analyzes feedback"| node_analysis
node_analysis -.->|"requests analysis"| node_groq
node_feedback_processing -->|"persists feedback"| node_feedback_dao
node_feedback_dao -->|"reads/writes"| node_database
node_feedback_processing -->|"logs feedback"| node_sheets
node_sheets -.->|"writes rows"| node_sheets_api
node_feedback_processing -->|"routes critical issues"| node_trello
node_trello -.->|"creates cards"| node_trello_api
node_feedback_processing -->|"publishes answer"| node_rabbit
node_rabbit -->|"delivers answer"| node_answer_consumer
node_answer_consumer -->|"sends response"| node_bot
node_bot -->|"replies to user"| node_telegram_api
node_admin_actor -->|"authenticates"| node_auth_controller
node_auth_controller -->|"delegates auth"| node_auth_service
node_auth_controller -->|"issues access token"| node_jwt
node_auth_service -->|"stores tokens"| node_auth_store
node_auth_store -->|"reads/writes"| node_database
node_admin_actor -->|"manages feedback"| node_feedback_controller
node_feedback_controller -->|"requests feedback"| node_feedback_service
node_feedback_service -->|"queries feedback"| node_feedback_dao
node_admin_actor -->|"manages invites"| node_token_controller
node_token_controller -->|"requests token operations"| node_invite_tokens
node_invite_tokens -->|"reads/writes tokens"| node_invite_dao
node_invite_dao -->|"reads/writes"| node_database

click node_webhook "https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/WebhookController.java"
click node_updates "https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/UpdateProcessor.java"
click node_bot "https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/TelegramBot.java"
click node_messaging_app "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/MessagingApplicationServiceImpl.java"
click node_main_service "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/MainServiceImpl.java"
click node_invite_tokens "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/token/service/InviteTokenServiceImpl.java"
click node_producer "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/ProducerServiceImpl.java"
click node_listener "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/listener/RabbitMessageListener.java"
click node_validator "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/listener/MessageValidator.java"
click node_feedback_processing "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/FeedbackProcessingServiceImpl.java"
click node_transcription "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/ai/GroqTranscriptionServiceImpl.java"
click node_analysis "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/ai/SpringAIAnalysisServiceImpl.java"
click node_sheets "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/sheets/GoogleSheetsServiceImpl.java"
click node_trello "https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/trello/TrelloServiceImpl.java"
click node_feedback_dao "https://github.com/kemalq/feedback-bot/blob/master/common-jpa/src/main/java/com/feedbackbot/dao/FeedbackMessageDAO.java"
click node_answer_consumer "https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/service/AnswerConsumer.java"
click node_auth_controller "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/controller/AuthController.java"
click node_auth_service "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/service/AuthServiceImpl.java"
click node_jwt "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/service/JwtService.java"
click node_feedback_controller "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/feedback/controller/FeedbackController.java"
click node_feedback_service "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/feedback/service/FeedbackServiceImpl.java"
click node_token_controller "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/token/controller/TokenController.java"
click node_auth_store "https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/dao/RefreshTokenDAO.java"
click node_invite_dao "https://github.com/kemalq/feedback-bot/blob/master/common-jpa/src/main/java/com/feedbackbot/dao/InviteTokenDAO.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_webhook,node_updates,node_bot,node_messaging_app,node_main_service,node_answer_consumer toneBlue
class node_producer,node_listener,node_validator,node_feedback_processing,node_transcription,node_analysis,node_sheets,node_trello,node_database toneAmber
class node_invite_tokens,node_auth_controller,node_auth_service,node_jwt,node_feedback_controller,node_feedback_service,node_token_controller,node_telegram_api,node_groq,node_sheets_api,node_trello_api toneMint
class node_feedback_dao,node_auth_store,node_invite_dao toneRose
class node_employee,node_rabbit,node_admin_actor toneIndigo
```

## Components

### Telegram Interaction

- [Webhook Controller](https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/WebhookController.java): `dispatcher/src/main/java/com/feedbackbot/bot/WebhookController.java`
- [Update Processor](https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/UpdateProcessor.java): `dispatcher/src/main/java/com/feedbackbot/bot/UpdateProcessor.java`
- [Telegram Bot](https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/bot/TelegramBot.java): `dispatcher/src/main/java/com/feedbackbot/bot/TelegramBot.java`
- [Messaging Application](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/MessagingApplicationServiceImpl.java): `node/src/main/java/com/feedbackbot/service/impl/MessagingApplicationServiceImpl.java`
- [Conversation Logic](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/MainServiceImpl.java): `node/src/main/java/com/feedbackbot/service/impl/MainServiceImpl.java`
- [Answer Consumer](https://github.com/kemalq/feedback-bot/blob/master/dispatcher/src/main/java/com/feedbackbot/service/AnswerConsumer.java): `dispatcher/src/main/java/com/feedbackbot/service/AnswerConsumer.java`

### Feedback Processing

- [Event Producer](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/ProducerServiceImpl.java): `node/src/main/java/com/feedbackbot/service/impl/ProducerServiceImpl.java`
- [Message Listener](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/listener/RabbitMessageListener.java): `node/src/main/java/com/feedbackbot/listener/RabbitMessageListener.java`
- [Message Validator](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/listener/MessageValidator.java): `node/src/main/java/com/feedbackbot/listener/MessageValidator.java`
- [Feedback Processing](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/service/impl/FeedbackProcessingServiceImpl.java): `node/src/main/java/com/feedbackbot/service/impl/FeedbackProcessingServiceImpl.java`
- [Voice Transcription](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/ai/GroqTranscriptionServiceImpl.java): `node/src/main/java/com/feedbackbot/integrations/ai/GroqTranscriptionServiceImpl.java`
- [AI Analysis](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/ai/SpringAIAnalysisServiceImpl.java): `node/src/main/java/com/feedbackbot/integrations/ai/SpringAIAnalysisServiceImpl.java`
- [Google Sheets](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/sheets/GoogleSheetsServiceImpl.java): `node/src/main/java/com/feedbackbot/integrations/sheets/GoogleSheetsServiceImpl.java`
- [Trello Integration](https://github.com/kemalq/feedback-bot/blob/master/node/src/main/java/com/feedbackbot/integrations/trello/TrelloServiceImpl.java): `node/src/main/java/com/feedbackbot/integrations/trello/TrelloServiceImpl.java`

### Administration API

- [Invite Tokens](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/token/service/InviteTokenServiceImpl.java): `rest-service/src/main/java/com/feedbackbot/token/service/InviteTokenServiceImpl.java`
- [Auth Controller](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/controller/AuthController.java): `rest-service/src/main/java/com/feedbackbot/auth/controller/AuthController.java`
- [Authentication Service](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/service/AuthServiceImpl.java): `rest-service/src/main/java/com/feedbackbot/auth/service/AuthServiceImpl.java`
- [JWT Service](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/service/JwtService.java): `rest-service/src/main/java/com/feedbackbot/auth/service/JwtService.java`
- [Feedback Controller](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/feedback/controller/FeedbackController.java): `rest-service/src/main/java/com/feedbackbot/feedback/controller/FeedbackController.java`
- [Feedback Service](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/feedback/service/FeedbackServiceImpl.java): `rest-service/src/main/java/com/feedbackbot/feedback/service/FeedbackServiceImpl.java`
- [Token Controller](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/token/controller/TokenController.java): `rest-service/src/main/java/com/feedbackbot/token/controller/TokenController.java`

### Shared Data

- [Feedback Repository](https://github.com/kemalq/feedback-bot/blob/master/common-jpa/src/main/java/com/feedbackbot/dao/FeedbackMessageDAO.java): `common-jpa/src/main/java/com/feedbackbot/dao/FeedbackMessageDAO.java`
- [Auth Repositories](https://github.com/kemalq/feedback-bot/blob/master/rest-service/src/main/java/com/feedbackbot/auth/dao/RefreshTokenDAO.java): `rest-service/src/main/java/com/feedbackbot/auth/dao/RefreshTokenDAO.java`
- [Invite Repository](https://github.com/kemalq/feedback-bot/blob/master/common-jpa/src/main/java/com/feedbackbot/dao/InviteTokenDAO.java): `common-jpa/src/main/java/com/feedbackbot/dao/InviteTokenDAO.java`

### Other components

- **Employee**
- **Telegram API**
- **RabbitMQ**
- **PostgreSQL**
- **Administrator**
- **Groq API**
- **Google Sheets API**
- **Trello API**

## Connections

- Employee → Telegram API: submits feedback
- Telegram API → Webhook Controller: delivers updates
- Webhook Controller → Update Processor: forwards update
- Update Processor → Messaging Application: dispatches update
- Messaging Application → Conversation Logic: handles conversation
- Conversation Logic → Invite Tokens: validates invite
- Conversation Logic → Event Producer: publishes feedback
- Event Producer → RabbitMQ: publishes event
- RabbitMQ → Message Listener: delivers event
- Message Listener → Message Validator: validates message
- Message Listener → Feedback Processing: processes message
- Feedback Processing → Voice Transcription: transcribes voice
- Voice Transcription → Groq API: requests transcription
- Feedback Processing → AI Analysis: analyzes feedback
- AI Analysis → Groq API: requests analysis
- Feedback Processing → Feedback Repository: persists feedback
- Feedback Repository → PostgreSQL: reads/writes
- Feedback Processing → Google Sheets: logs feedback
- Google Sheets → Google Sheets API: writes rows
- Feedback Processing → Trello Integration: routes critical issues
- Trello Integration → Trello API: creates cards
- Feedback Processing → RabbitMQ: publishes answer
- RabbitMQ → Answer Consumer: delivers answer
- Answer Consumer → Telegram Bot: sends response
- Telegram Bot → Telegram API: replies to user
- Administrator → Auth Controller: authenticates
- Auth Controller → Authentication Service: delegates auth
- Auth Controller → JWT Service: issues access token
- Authentication Service → Auth Repositories: stores tokens
- Auth Repositories → PostgreSQL: reads/writes
- Administrator → Feedback Controller: manages feedback
- Feedback Controller → Feedback Service: requests feedback
- Feedback Service → Feedback Repository: queries feedback
- Administrator → Token Controller: manages invites
- Token Controller → Invite Tokens: requests token operations
- Invite Tokens → Invite Repository: reads/writes tokens
- Invite Repository → PostgreSQL: reads/writes