# desenvolvimento-de-software/mslovelace_bot architecture

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

- Interactive diagram: https://gitdiagram.com/desenvolvimento-de-software/mslovelace_bot
- Repository: https://github.com/desenvolvimento-de-software/mslovelace_bot

## Overview

Ada Lovelace is a Telegram group-management bot. Its principal workflow is to receive Telegram updates (through incoming delivery or polling), turn them into contexts, dispatch actions, commands, and callbacks, and respond through Telegram’s API. Domain capabilities include moderation, warnings, federation, greetings/captcha, and AdaShield anti-spam checks. The README documents MySQL/Prisma and Combot integration; source excerpts are limited, so links for unsampled controllers and feature handlers are shown only where the tree or documentation supports them.

Main entry points: [`src/controllers/Controller.ts`](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Controller.ts) (Update dispatch), [`src/libraries/telegram/TelegramBotApi.ts`](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/libraries/telegram/TelegramBotApi.ts) (Telegram API client), [`src/commands`](https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/commands) (Bot commands), [`src/controllers/Polling.ts`](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Polling.ts) (Update polling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_app["App lifecycle<br/>[App.ts]"]
  node_incoming["Incoming delivery<br/>[Incoming.ts]"]
  node_polling["Update polling<br/>[Polling.ts]"]
  node_controller["Update dispatch<br/>[Controller.ts]"]
  node_context_factory["Context factory<br/>[ContextFactory.ts]"]
end

subgraph group_features["Group features"]
  node_actions["Update actions"]
  node_commands["Bot commands"]
  node_callbacks["Callback handlers"]
  node_adashield["AdaShield checks<br/>[AdaShield.ts]"]
end

subgraph group_domain["Domain services"]
  node_moderation["Moderation services<br/>[Ban.ts]"]
  node_warnings["Warning service<br/>[Warnings.ts]"]
  node_federations["Federation service<br/>[Federations.ts]"]
  node_user_chat_data["User and chat data<br/>[UsersAndChats.ts]"]
  node_scheduled_tasks["Scheduled tasks"]
end

subgraph group_integrations["External integrations"]
  node_telegram_client["Telegram API client<br/>[TelegramBotApi.ts]"]
  node_combot_client["Combot API client<br/>[CasApi.ts]"]
end

node_telegram_users(("Telegram users"))
node_telegram_api["Telegram API"]
node_combot["Combot anti-spam"]
node_mysql[("MySQL database")]

node_telegram_users -->|"send updates"| node_incoming
node_app -->|"mounts controller"| node_incoming
node_app -->|"mounts controller"| node_polling
node_incoming -->|"forwards payload"| node_controller
node_polling -->|"forwards updates"| node_controller
node_polling -->|"requests updates"| node_telegram_client
node_controller -->|"creates context"| node_context_factory
node_controller -->|"dispatches actions"| node_actions
node_controller -->|"dispatches commands"| node_commands
node_controller -->|"dispatches callbacks"| node_callbacks
node_actions -->|"checks joiners"| node_adashield
node_commands -->|"invokes moderation"| node_moderation
node_commands -->|"manages warnings"| node_warnings
node_commands -->|"manages federations"| node_federations
node_actions -->|"saves context data"| node_user_chat_data
node_scheduled_tasks -->|"kicks unverified users"| node_moderation
node_scheduled_tasks -->|"deletes expired messages"| node_telegram_client
node_adashield -->|"checks spam status"| node_combot_client
node_combot_client -->|"queries status"| node_combot
node_adashield -->|"bans flagged users"| node_telegram_client
node_moderation -->|"manages membership"| node_telegram_client
node_warnings -->|"persists warnings"| node_mysql
node_federations -->|"persists federation data"| node_mysql
node_user_chat_data -->|"reads and writes"| node_mysql
node_telegram_client -->|"calls Bot API"| node_telegram_api

click node_app "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/App.ts"
click node_incoming "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Incoming.ts"
click node_polling "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Polling.ts"
click node_controller "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Controller.ts"
click node_context_factory "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/contexts/ContextFactory.ts"
click node_actions "https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/actions"
click node_commands "https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/commands"
click node_callbacks "https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/callbacks"
click node_moderation "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Ban.ts"
click node_warnings "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Warnings.ts"
click node_federations "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Federations.ts"
click node_user_chat_data "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/UsersAndChats.ts"
click node_adashield "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/AdaShield.ts"
click node_scheduled_tasks "https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/intervals"
click node_telegram_client "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/libraries/telegram/TelegramBotApi.ts"
click node_combot_client "https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/libraries/combot/CasApi.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_app,node_incoming,node_polling,node_controller,node_context_factory,node_telegram_users toneBlue
class node_actions,node_commands,node_callbacks,node_adashield,node_mysql toneAmber
class node_moderation,node_warnings,node_federations,node_user_chat_data,node_scheduled_tasks,node_telegram_api toneMint
class node_telegram_client,node_combot_client toneRose
class node_combot toneIndigo
```

## Components

### Bot runtime

- [App lifecycle](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/App.ts): `src/App.ts`
- [Incoming delivery](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Incoming.ts): `src/controllers/Incoming.ts`
- [Update polling](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Polling.ts): `src/controllers/Polling.ts`
- [Update dispatch](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/controllers/Controller.ts): `src/controllers/Controller.ts`
- [Context factory](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/contexts/ContextFactory.ts): `src/contexts/ContextFactory.ts`

### Group features

- [Update actions](https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/actions): `src/actions`
- [Bot commands](https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/commands): `src/commands`
- [Callback handlers](https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/callbacks): `src/callbacks`
- [AdaShield checks](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/AdaShield.ts): `src/services/AdaShield.ts`

### Domain services

- [Moderation services](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Ban.ts): `src/services/Ban.ts`
- [Warning service](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Warnings.ts): `src/services/Warnings.ts`
- [Federation service](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/Federations.ts): `src/services/Federations.ts`
- [User and chat data](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/services/UsersAndChats.ts): `src/services/UsersAndChats.ts`
- [Scheduled tasks](https://github.com/desenvolvimento-de-software/mslovelace_bot/tree/master/src/intervals): `src/intervals`

### External integrations

- [Telegram API client](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/libraries/telegram/TelegramBotApi.ts): `src/libraries/telegram/TelegramBotApi.ts`
- [Combot API client](https://github.com/desenvolvimento-de-software/mslovelace_bot/blob/master/src/libraries/combot/CasApi.ts): `src/libraries/combot/CasApi.ts`

### Other components

- **Telegram users**
- **Telegram API**
- **Combot anti-spam**
- **MySQL database**

## Connections

- Telegram users → Incoming delivery: send updates
- App lifecycle → Incoming delivery: mounts controller
- App lifecycle → Update polling: mounts controller
- Incoming delivery → Update dispatch: forwards payload
- Update polling → Update dispatch: forwards updates
- Update polling → Telegram API client: requests updates
- Update dispatch → Context factory: creates context
- Update dispatch → Update actions: dispatches actions
- Update dispatch → Bot commands: dispatches commands
- Update dispatch → Callback handlers: dispatches callbacks
- Update actions → AdaShield checks: checks joiners
- Bot commands → Moderation services: invokes moderation
- Bot commands → Warning service: manages warnings
- Bot commands → Federation service: manages federations
- Update actions → User and chat data: saves context data
- Scheduled tasks → Moderation services: kicks unverified users
- Scheduled tasks → Telegram API client: deletes expired messages
- AdaShield checks → Combot API client: checks spam status
- Combot API client → Combot anti-spam: queries status
- AdaShield checks → Telegram API client: bans flagged users
- Moderation services → Telegram API client: manages membership
- Warning service → MySQL database: persists warnings
- Federation service → MySQL database: persists federation data
- User and chat data → MySQL database: reads and writes
- Telegram API client → Telegram API: calls Bot API