Top Level Workflow - CheckMadeLtd/CheckMade GitHub Wiki
Summary of the top-level main workflow (input-output roundtrip) for handling a Telegram bot update:
-
Request Ingestion:
- One of the bot functions (
OperationsBot
,CommunicationsBot
, orNotificationsBot
) receives anHTTP POST
request from Telegram. - These functions inherit from
BotFunctionBase
, which provides a commonProcessRequestAsync
method.
- One of the bot functions (
-
Update Deserialization and Routing:
- The incoming request body is deserialized into a
Telegram.Bot.Types.Update
object. - The
Update
is passed to theBotUpdateSwitch.SwitchUpdateAsync
method along with the specificInteractionMode
.
- The incoming request body is deserialized into a
-
Update Handling:
-
BotUpdateSwitch
determines the type ofUpdate
(e.g.,Message
,EditedMessage
,CallbackQuery
). - For supported types, it calls
UpdateHandler.HandleUpdateAsync
and passes theUpdate
in a custom Wrapper (UpdateWrapper
) which improves/simplifies/unifies the Update's representation for the purposes of our subsequent code.
-
-
Conversion to Domain Model:
-
UpdateHandler
usesToModelConverter
to transform the TelegramUpdate
into aTlgInput
domain object. - This process includes resolving file paths, handling attachments, and identifying the originator's role.
-
-
Input Processing:
- The converted
TlgInput
is passed to an appropriateInputProcessor
(based on theInteractionMode
). - The
InputProcessor
generates a collection ofOutputDto
objects and enriches theTlgInput
.
- The converted
-
Output Generation:
-
OutputSender
takes theOutputDto
collection and prepares it for sending back to Telegram. - It resolves the correct
BotClient
for each output based on theInteractionMode
(and in non-default case usesLogicalPort
to resolve destination TlgAgent that is different from source of current Input). -
OutputToReplyMarkupConverter
is used to create appropriate Telegram reply markup (e.g., inline keyboards, reply keyboards).
-
-
Response Sending:
- The prepared outputs are sent back to Telegram using the appropriate
BotClientWrapper
methods. - This may include sending text messages, documents, photos, voice messages, or locations.
- The prepared outputs are sent back to Telegram using the appropriate
-
Finally, save to DB
- Based on actual message-send parameters returned from prev. step, now saves the enriched Input, any corresponding derived data and the actually sent Outputs to the DB.
-
Error Handling:
- Throughout this process, errors are captured using our custom
Result<T>
monad. - Errors are logged, but a
200 OK
response is always returned to Telegram to prevent endless retry loops.
This workflow represents a clean separation of concerns, with distinct steps for input processing, domain logic, and output generation, all wrapped in a functional-style error handling approach.