Scope

This document defines all models related to the Telegram bot integration and JWT authentication. The bot models cover the shapes Telegram sends to the gateway and the intent model produced by local Ollama classification. The auth models cover the JWT claims structure and the user context carried through the request lifecycle. Full user management is deferred to post-launch but the auth models are shaped to accommodate it without restructuring.

Telegram Bot Models

Telegram sends webhook events to the gateway as HTTP POST requests. The shapes below reflect the relevant subset of the Telegram Bot API update payload. Only the fields the gateway actually uses are modelled. Full Telegram update payloads contain many additional fields that are ignored.

classDiagram
    class TelegramUpdate {
        Long updateId
        TelegramMessage message
    }

    class TelegramMessage {
        Long messageId
        TelegramChat chat
        TelegramUser from
        String text
        TelegramPhotoSize[] photo
        TelegramDocument document
    }

    class TelegramChat {
        Long id
        String type
    }

    class TelegramUser {
        Long id
        String firstName
        String username
    }

    class TelegramPhotoSize {
        String fileId
        Integer width
        Integer height
        Integer fileSize
    }

    class TelegramDocument {
        String fileId
        String fileName
        String mimeType
        Integer fileSize
    }

    TelegramUpdate --> TelegramMessage
    TelegramMessage --> TelegramChat
    TelegramMessage --> TelegramUser
    TelegramMessage --> TelegramPhotoSize
    TelegramMessage --> TelegramDocument

TelegramUpdate
Purpose Top-level payload received from Telegram on the webhook endpoint POST /api/v1/bot/telegram. The gateway extracts the message from each update and passes it to the bot service for processing.
Key Constraints updateId is unique per update and can be used for deduplication. Only message updates are handled. Callback queries, inline queries, and other update types are ignored. The Telegram secret token header is validated before this object is deserialised.

TelegramMessage
Purpose Represents the message sent by the user to the bot. Carries text content, photo attachments, or document attachments depending on what the user sent.
Key Constraints text is null when the message is a photo or document. photo is an array of resolutions when present -- the gateway selects the highest resolution entry. document covers file attachments. The bot service checks which fields are populated to determine message type before routing to intent classification.

TelegramChat
Purpose Identifies the chat where the message was sent. The id is used for all reply calls to the Telegram Bot API.
Key Constraints id is required for sending any reply. type is typically "private" for direct bot messages.

TelegramUser
Purpose Identifies the user who sent the message. Used for logging and for future access control when user management is added.
Key Constraints username may be null if the user has not set one. firstName is always present. id is the stable Telegram user identifier.

TelegramPhotoSize
Purpose Represents one resolution variant of a photo attachment. Telegram sends multiple resolutions for each photo.
Key Constraints fileId is used to download the image via the Telegram Bot API GET /file/{fileId} endpoint. The gateway selects the largest available size. fileSize is in bytes and is used to reject images that exceed the configured maximum.

TelegramDocument
Purpose Represents a file attachment sent as a document rather than a compressed photo.
Key Constraints mimeType is checked before download to ensure the file is an image type supported by the vision model. fileId is used for download.

Intent Classification Models

These models are internal to the bot flow. They represent the output of local Ollama intent classification and carry the resolved intent and any extracted parameters to the bot service handler.

classDiagram
    class IntentClassificationRequest {
        String messageText
        boolean hasImage
    }

    class IntentClassificationResult {
        BotIntent intent
        Map~String_String~ params
        Double confidence
    }

    IntentClassificationResult --> BotIntent