# stanislavstarr/compliment_bot architecture

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

- Interactive diagram: https://gitdiagram.com/stanislavstarr/compliment_bot
- Repository: https://github.com/stanislavstarr/compliment_bot

## Overview

Compliment Bot lets an author configure a personalized daily message for a recipient, who accepts an invitation and chooses delivery timing. Celery dispatches due schedules, queues deliveries, and delivers AI-generated or fallback messages through Telegram. The graph includes onboarding, feedback, settings, administration, persistence, and AI generation. Relationships are limited to README statements and source-index references; unsampled implementations are represented by their existing directories, and their exact internal wiring is not inferred.

Main entry points: [`app/infrastructure/telegram/routers`](https://github.com/stanislavstarr/compliment_bot/tree/main/app/infrastructure/telegram/routers) (Bot routers), [`app/infrastructure/tasks/delivery.py`](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/tasks/delivery.py) (Message delivery), [`app/application/orders/service.py`](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/orders/service.py) (Order lifecycle), [`app/application/author_onboarding/service.py`](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/author_onboarding/service.py) (Author onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram experience"]
  node_bot["Telegram bot<br/>[bot.py]"]
  node_routers["Bot routers"]
end

subgraph group_usecases["Application workflows"]
  node_author_setup["Author onboarding<br/>[service.py]"]
  node_recipient_setup["Recipient onboarding<br/>[service.py]"]
  node_invites["Invitations<br/>[service.py]"]
  node_orders["Order lifecycle<br/>[service.py]"]
  node_feedback["Feedback<br/>[service.py]"]
  node_settings["User settings<br/>[service.py]"]
  node_admin["Administration<br/>[service.py]"]
end

subgraph group_delivery["Scheduling and delivery"]
  node_scheduler["Schedule dispatch<br/>[scheduler.py]"]
  node_calculator["Schedule calculator<br/>[calculator.py]"]
  node_delivery_task["Message delivery<br/>[delivery.py]"]
end

subgraph group_generation["Message generation"]
  node_generation_service["Generation workflow<br/>[service.py]"]
  node_prompt["Prompt builder<br/>[builder.py]"]
  node_ai_provider["AI provider<br/>[base.py]"]
end

subgraph group_storage["Persistence and integrations"]
  node_db[("PostgreSQL data")]
  node_user_repository["User repository<br/>[users.py]"]
  node_order_repository["Order repository<br/>[orders.py]"]
  node_schedule_repository["Schedule repository<br/>[schedules.py]"]
  node_message_repository["Message repository<br/>[messages.py]"]
  node_config["Application config<br/>[config.py]"]
end

node_author(("Author"))
node_recipient(("Recipient"))
node_openai{{"OpenAI"}}

node_author -->|"uses"| node_bot
node_recipient -->|"uses"| node_bot
node_bot -->|"dispatches updates"| node_routers
node_routers -->|"handles setup"| node_author_setup
node_routers -.->|"handles setup"| node_recipient_setup
node_author_setup -->|"issues invites"| node_invites
node_author_setup -->|"configures order"| node_orders
node_recipient_setup -->|"accepts invite"| node_orders
node_routers -.->|"collects feedback"| node_feedback
node_routers -->|"updates settings"| node_settings
node_settings -->|"cancels order"| node_orders
node_settings -->|"computes next run"| node_calculator
node_scheduler -->|"claims due schedules"| node_schedule_repository
node_scheduler -->|"queues delivery"| node_delivery_task
node_delivery_task -->|"generates message"| node_generation_service
node_generation_service -->|"builds prompt"| node_prompt
node_generation_service -->|"requests generation"| node_ai_provider
node_ai_provider -->|"calls API"| node_openai
node_delivery_task -->|"persists message"| node_message_repository
node_delivery_task -->|"sends Telegram message"| node_bot
node_author_setup -->|"loads user"| node_user_repository
node_orders -->|"loads orders"| node_order_repository
node_orders -->|"pauses schedule"| node_schedule_repository
node_admin -->|"reviews messages"| node_message_repository
node_delivery_task -->|"reads settings"| node_config

click node_bot "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/telegram/bot.py"
click node_routers "https://github.com/stanislavstarr/compliment_bot/tree/main/app/infrastructure/telegram/routers"
click node_author_setup "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/author_onboarding/service.py"
click node_recipient_setup "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/recipient_onboarding/service.py"
click node_invites "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/invites/service.py"
click node_orders "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/orders/service.py"
click node_feedback "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/feedback/service.py"
click node_settings "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/settings/service.py"
click node_admin "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/admin/service.py"
click node_scheduler "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/tasks/scheduler.py"
click node_calculator "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/scheduling/calculator.py"
click node_delivery_task "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/tasks/delivery.py"
click node_generation_service "https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/generation/service.py"
click node_prompt "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/ai/prompts/builder.py"
click node_ai_provider "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/ai/base.py"
click node_db "https://github.com/stanislavstarr/compliment_bot/tree/main/app/infrastructure/db/models"
click node_user_repository "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/users.py"
click node_order_repository "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/orders.py"
click node_schedule_repository "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/schedules.py"
click node_message_repository "https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/messages.py"
click node_config "https://github.com/stanislavstarr/compliment_bot/blob/main/app/config.py"

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_bot,node_routers toneBlue
class node_author_setup,node_recipient_setup,node_invites,node_orders,node_feedback,node_settings,node_admin toneAmber
class node_scheduler,node_calculator,node_delivery_task toneMint
class node_generation_service,node_prompt,node_ai_provider toneRose
class node_db,node_user_repository,node_order_repository,node_schedule_repository,node_message_repository,node_config,node_author,node_recipient,node_openai toneIndigo
```

## Components

### Telegram experience

- [Telegram bot](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/telegram/bot.py): `app/infrastructure/telegram/bot.py`
- [Bot routers](https://github.com/stanislavstarr/compliment_bot/tree/main/app/infrastructure/telegram/routers): `app/infrastructure/telegram/routers`

### Application workflows

- [Author onboarding](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/author_onboarding/service.py): `app/application/author_onboarding/service.py`
- [Recipient onboarding](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/recipient_onboarding/service.py): `app/application/recipient_onboarding/service.py`
- [Invitations](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/invites/service.py): `app/application/invites/service.py`
- [Order lifecycle](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/orders/service.py): `app/application/orders/service.py`
- [Feedback](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/feedback/service.py): `app/application/feedback/service.py`
- [User settings](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/settings/service.py): `app/application/settings/service.py`
- [Administration](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/admin/service.py): `app/application/admin/service.py`

### Scheduling and delivery

- [Schedule dispatch](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/tasks/scheduler.py): `app/infrastructure/tasks/scheduler.py`
- [Schedule calculator](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/scheduling/calculator.py): `app/application/scheduling/calculator.py`
- [Message delivery](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/tasks/delivery.py): `app/infrastructure/tasks/delivery.py`

### Message generation

- [Generation workflow](https://github.com/stanislavstarr/compliment_bot/blob/main/app/application/generation/service.py): `app/application/generation/service.py`
- [Prompt builder](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/ai/prompts/builder.py): `app/infrastructure/ai/prompts/builder.py`
- [AI provider](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/ai/base.py): `app/infrastructure/ai/base.py`

### Persistence and integrations

- [PostgreSQL data](https://github.com/stanislavstarr/compliment_bot/tree/main/app/infrastructure/db/models): `app/infrastructure/db/models`
- [User repository](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/users.py): `app/infrastructure/db/repositories/users.py`
- [Order repository](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/orders.py): `app/infrastructure/db/repositories/orders.py`
- [Schedule repository](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/schedules.py): `app/infrastructure/db/repositories/schedules.py`
- [Message repository](https://github.com/stanislavstarr/compliment_bot/blob/main/app/infrastructure/db/repositories/messages.py): `app/infrastructure/db/repositories/messages.py`
- [Application config](https://github.com/stanislavstarr/compliment_bot/blob/main/app/config.py): `app/config.py`

### Other components

- **Author**
- **Recipient**
- **OpenAI**

## Connections

- Author → Telegram bot: uses (evidence: `README.md`)
- Recipient → Telegram bot: uses (evidence: `README.md`)
- Telegram bot → Bot routers: dispatches updates
- Bot routers → Author onboarding: handles setup (evidence: `app/infrastructure/telegram/routers/author/portrait.py`)
- Bot routers → Recipient onboarding: handles setup
- Author onboarding → Invitations: issues invites (evidence: `app/application/author_onboarding/service.py`)
- Author onboarding → Order lifecycle: configures order (evidence: `app/application/author_onboarding/service.py`)
- Recipient onboarding → Order lifecycle: accepts invite (evidence: `app/application/recipient_onboarding/service.py`)
- Bot routers → Feedback: collects feedback
- Bot routers → User settings: updates settings (evidence: `app/infrastructure/telegram/routers/settings.py`)
- User settings → Order lifecycle: cancels order (evidence: `app/application/settings/service.py`)
- User settings → Schedule calculator: computes next run (evidence: `app/application/settings/service.py`)
- Schedule dispatch → Schedule repository: claims due schedules (evidence: `README.md`)
- Schedule dispatch → Message delivery: queues delivery (evidence: `README.md`)
- Message delivery → Generation workflow: generates message (evidence: `app/infrastructure/tasks/delivery.py`)
- Generation workflow → Prompt builder: builds prompt (evidence: `app/application/generation/service.py`)
- Generation workflow → AI provider: requests generation (evidence: `app/application/generation/service.py`)
- AI provider → OpenAI: calls API (evidence: `README.md`)
- Message delivery → Message repository: persists message (evidence: `README.md`)
- Message delivery → Telegram bot: sends Telegram message (evidence: `README.md`)
- Author onboarding → User repository: loads user (evidence: `app/application/author_onboarding/service.py`)
- Order lifecycle → Order repository: loads orders (evidence: `app/application/orders/service.py`)
- Order lifecycle → Schedule repository: pauses schedule (evidence: `app/application/orders/service.py`)
- Administration → Message repository: reviews messages (evidence: `app/application/admin/service.py`)
- Message delivery → Application config: reads settings (evidence: `app/infrastructure/tasks/delivery.py`)