# tomslideruz/rimuru-tempest-ai-telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/tomslideruz/rimuru-tempest-ai-telegram-bot
- Repository: https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot

## Overview

Rimuru Tempest is a persistent-personality Telegram AI bot. Users send private messages or address the bot in groups; the bot filters and routes messages, builds a persona- and memory-aware prompt, calls Groq, updates user and relationship state, stores the reply, and responds through Telegram. Separate capabilities include commands, language detection, relationship progression, idle follow-ups, and health checks. The sampled source confirms the message-processing and storage flow; some subsystem wiring is documented or evident from module roles but was not sampled, so uncertain links are omitted.

Main entry points: [`src/bot/handlers/messageHandler.js`](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/messageHandler.js) (Message handler), [`src/services/chatService.js`](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/chatService.js) (Chat orchestration), [`src/storage/fileDatabase.js`](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/fileDatabase.js) (JSON database), [`src/bot/telegramClient.js`](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/telegramClient.js) (Telegram client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Telegram interface"]
  node_entry["Application entry<br/>[index.js]"]
  node_bot["Bot runtime<br/>[bot.js]"]
  node_telegram_client["Telegram client<br/>[telegramClient.js]"]
  node_message_handler["Message handler<br/>[messageHandler.js]"]
  node_commands["Commands<br/>[commandHandler.js]"]
  node_block_check["Block check<br/>[blockCheck.js]"]
  node_file_filter["Media filter<br/>[fileFilter.js]"]
  node_group_mention["Group mention"]
  node_mention_service["Mention detection<br/>[mentionService.js]"]
  node_language["Language detection"]
  node_health["Health endpoints<br/>[index.js]"]
end

subgraph group_conversation["Conversation processing"]
  node_chat_service["Chat orchestration<br/>[chatService.js]"]
  node_prompt_builder["Prompt builder<br/>[promptBuilder.js]"]
  node_prompts["Personality prompts<br/>[systemPrompt.txt]"]
  node_memory_analyzer["Memory analysis<br/>[memoryAnalyzer.js]"]
  node_ai_client["AI client and key rotation<br/>[aiClient.js]"]
  node_response_parser["Response parser<br/>[responseParser.js]"]
end

subgraph group_persona["Memory and relationships"]
  node_user_service["User service<br/>[userService.js]"]
  node_user_memory["User profiles<br/>[userMemory.js]"]
  node_relationship["Relationship engine"]
  node_chat_memory["Conversation memory<br/>[chatMemory.js]"]
  node_idle_scheduler["Idle follow-ups"]
end

subgraph group_persistence["Local persistence"]
  node_database[("JSON database<br/>[fileDatabase.js]")]
  node_json_reader["JSON reader<br/>[jsonReader.js]"]
  node_json_writer["Atomic JSON writer<br/>[jsonWriter.js]"]
end

subgraph group_integrations["External integrations"]
  node_telegram(("Telegram API"))
  node_groq(("Groq API"))
end

node_user(("Telegram user"))
node_platform(("Hosting platform"))

node_user -->|"sends messages"| node_telegram
node_telegram -->|"delivers updates"| node_telegram_client
node_entry -->|"starts"| node_bot
node_bot -->|"creates client"| node_telegram_client
node_telegram_client -->|"routes messages"| node_message_handler
node_message_handler -->|"checks status"| node_block_check
node_message_handler -->|"filters media"| node_file_filter
node_message_handler -->|"handles commands"| node_commands
node_message_handler -->|"checks group address"| node_group_mention
node_group_mention -->|"tests and cleans"| node_mention_service
node_message_handler -->|"detects script"| node_language
node_message_handler -->|"processes text"| node_chat_service
node_chat_service -->|"loads and updates user"| node_user_service
node_chat_service -->|"reads and records"| node_chat_memory
node_chat_service -->|"records activity"| node_idle_scheduler
node_chat_service -->|"builds prompt"| node_prompt_builder
node_prompt_builder -->|"uses persona rules"| node_prompts
node_prompt_builder -.->|"uses memory analysis"| node_memory_analyzer
node_chat_service -->|"requests completion"| node_ai_client
node_ai_client -->|"calls completion API"| node_groq
node_chat_service -->|"parses completion"| node_response_parser
node_chat_service -->|"returns reply"| node_message_handler
node_message_handler -->|"sends reply"| node_telegram_client
node_user_service -->|"reads and updates profile"| node_user_memory
node_user_service -->|"reads and updates relation"| node_relationship
node_relationship -->|"persists relation"| node_database
node_user_memory -->|"persists profile"| node_database
node_chat_memory -->|"persists history"| node_database
node_database -->|"reads files"| node_json_reader
node_database -->|"writes atomically"| node_json_writer
node_idle_scheduler -.->|"sends follow-ups"| node_telegram_client
node_platform -->|"checks health"| node_health

click node_entry "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/index.js"
click node_bot "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/bot.js"
click node_telegram_client "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/telegramClient.js"
click node_message_handler "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/messageHandler.js"
click node_commands "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/commandHandler.js"
click node_block_check "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/blockCheck.js"
click node_file_filter "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/fileFilter.js"
click node_group_mention "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/groupMentionHandler.js"
click node_mention_service "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/mentionService.js"
click node_language "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/languageDetector.js"
click node_chat_service "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/chatService.js"
click node_prompt_builder "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/promptBuilder.js"
click node_prompts "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/prompts/systemPrompt.txt"
click node_memory_analyzer "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/memoryAnalyzer.js"
click node_ai_client "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/aiClient.js"
click node_response_parser "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/responseParser.js"
click node_user_service "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/userService.js"
click node_user_memory "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/userMemory.js"
click node_relationship "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/relationshipEngine.js"
click node_chat_memory "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/chatMemory.js"
click node_idle_scheduler "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/idleMessageScheduler.js"
click node_database "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/fileDatabase.js"
click node_json_reader "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/jsonReader.js"
click node_json_writer "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/jsonWriter.js"
click node_health "https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/index.js"

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_entry,node_bot,node_telegram_client,node_message_handler,node_commands,node_block_check,node_file_filter,node_group_mention,node_mention_service,node_language,node_health,node_user toneBlue
class node_chat_service,node_prompt_builder,node_prompts,node_memory_analyzer,node_ai_client,node_response_parser toneAmber
class node_user_service,node_user_memory,node_relationship,node_chat_memory,node_idle_scheduler toneMint
class node_database,node_json_reader,node_json_writer toneRose
class node_telegram,node_groq,node_platform toneIndigo
```

## Components

### Telegram interface

- [Application entry](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/index.js): `src/index.js`
- [Bot runtime](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/bot.js): `src/bot/bot.js`
- [Telegram client](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/telegramClient.js): `src/bot/telegramClient.js`
- [Message handler](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/messageHandler.js): `src/bot/handlers/messageHandler.js`
- [Commands](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/commandHandler.js): `src/bot/handlers/commandHandler.js`
- [Block check](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/blockCheck.js): `src/bot/middleware/blockCheck.js`
- [Media filter](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/fileFilter.js): `src/bot/middleware/fileFilter.js`
- [Group mention](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/handlers/groupMentionHandler.js): `src/bot/handlers/groupMentionHandler.js`
- [Mention detection](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/mentionService.js): `src/services/mentionService.js`
- [Language detection](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/bot/middleware/languageDetector.js): `src/bot/middleware/languageDetector.js`
- [Health endpoints](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/index.js): `src/index.js`

### Conversation processing

- [Chat orchestration](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/chatService.js): `src/services/chatService.js`
- [Prompt builder](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/promptBuilder.js): `src/ai/promptBuilder.js`
- [Personality prompts](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/prompts/systemPrompt.txt): `src/prompts/systemPrompt.txt`
- [Memory analysis](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/memoryAnalyzer.js): `src/ai/memoryAnalyzer.js`
- [AI client and key rotation](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/aiClient.js): `src/ai/aiClient.js`
- [Response parser](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/ai/responseParser.js): `src/ai/responseParser.js`

### Memory and relationships

- [User service](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/services/userService.js): `src/services/userService.js`
- [User profiles](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/userMemory.js): `src/memory/userMemory.js`
- [Relationship engine](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/relationshipEngine.js): `src/memory/relationshipEngine.js`
- [Conversation memory](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/chatMemory.js): `src/memory/chatMemory.js`
- [Idle follow-ups](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/memory/idleMessageScheduler.js): `src/memory/idleMessageScheduler.js`

### Local persistence

- [JSON database](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/fileDatabase.js): `src/storage/fileDatabase.js`
- [JSON reader](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/jsonReader.js): `src/storage/jsonReader.js`
- [Atomic JSON writer](https://github.com/tomslideruz/rimuru-tempest-ai-telegram-bot/blob/master/src/storage/jsonWriter.js): `src/storage/jsonWriter.js`

### External integrations

- **Telegram API**
- **Groq API**

### Other components

- **Telegram user**
- **Hosting platform**

## Connections

- Telegram user → Telegram API: sends messages
- Telegram API → Telegram client: delivers updates
- Application entry → Bot runtime: starts
- Bot runtime → Telegram client: creates client
- Telegram client → Message handler: routes messages
- Message handler → Block check: checks status
- Message handler → Media filter: filters media
- Message handler → Commands: handles commands
- Message handler → Group mention: checks group address
- Group mention → Mention detection: tests and cleans
- Message handler → Language detection: detects script
- Message handler → Chat orchestration: processes text
- Chat orchestration → User service: loads and updates user
- Chat orchestration → Conversation memory: reads and records
- Chat orchestration → Idle follow-ups: records activity
- Chat orchestration → Prompt builder: builds prompt
- Prompt builder → Personality prompts: uses persona rules
- Prompt builder → Memory analysis: uses memory analysis
- Chat orchestration → AI client and key rotation: requests completion
- AI client and key rotation → Groq API: calls completion API
- Chat orchestration → Response parser: parses completion
- Chat orchestration → Message handler: returns reply
- Message handler → Telegram client: sends reply
- User service → User profiles: reads and updates profile
- User service → Relationship engine: reads and updates relation
- Relationship engine → JSON database: persists relation
- User profiles → JSON database: persists profile
- Conversation memory → JSON database: persists history
- JSON database → JSON reader: reads files
- JSON database → Atomic JSON writer: writes atomically
- Idle follow-ups → Telegram client: sends follow-ups
- Hosting platform → Health endpoints: checks health