# chadoyev/instagram-auto-publisher architecture

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

- Interactive diagram: https://gitdiagram.com/chadoyev/instagram-auto-publisher
- Repository: https://github.com/chadoyev/instagram-auto-publisher

## Overview

Instagram Auto Publisher is a Telegram-operated content pipeline: users submit social-media links, the bot downloads files for users and review, admins moderate submissions, and approved items are scheduled for Instagram publication. Admin capabilities also include broadcast, subscription controls, scheduling settings, and Instagram session management. The graph reflects the README and source-index references; some implementation details and runtime wiring are unsampled, so uncertain links are omitted.

Main entry points: [`app/db/repositories`](https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/db/repositories) (Data repositories), [`app/services/instagram_publisher.py`](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/instagram_publisher.py) (Instagram publisher), [`app/__main__.py`](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/__main__.py) (Bot startup), [`app/bot/handlers/admin_menu.py`](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/admin_menu.py) (Admin controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram bot"]
  node_runtime["Bot startup<br/>[__main__.py]"]
  node_bot_factory["Bot factory<br/>[factory.py]"]
  node_bot_handlers["Bot handlers"]
  node_admin_controls["Admin controls<br/>[admin_menu.py]"]
  node_broadcast["Broadcast<br/>[broadcast.py]"]
  node_subscriptions["Subscriptions<br/>[subscription.py]"]
end

subgraph group_content["Content workflow"]
  node_download_handler["Download requests<br/>[download.py]"]
  node_download_router["Downloader router<br/>[router.py]"]
  node_downloaders["Platform downloaders"]
  node_review["Content review<br/>[content_review.py]"]
end

subgraph group_publishing["Publishing"]
  node_instagram_auth["Instagram session<br/>[instagram_auth.py]"]
  node_scheduler["Phase scheduler<br/>[scheduler.py]"]
  node_publisher["Instagram publisher"]
  node_watermark["Watermark processing<br/>[watermark.py]"]
end

subgraph group_persistence["Persistence"]
  node_repos["Data repositories"]
  node_models["Content and schedule models<br/>[models.py]"]
  node_database[("Database engine<br/>[engine.py]")]
end

subgraph group_platform["Configuration"]
  node_settings["Application settings<br/>[settings.py]"]
  node_webhook["Webhook endpoint<br/>[webhook.py]"]
end

node_user(("Bot user"))
node_admin(("Administrator"))
node_telegram(("Telegram"))
node_instagram(("Instagram"))
node_tiktok_api["TikTok API"]
node_hiker_api["HikerAPI"]
node_youtube["YouTube"]

node_runtime -->|"creates bot"| node_bot_factory
node_runtime -->|"initializes"| node_database
node_runtime -->|"starts"| node_scheduler
node_runtime -->|"uses in webhook mode"| node_webhook
node_bot_factory -->|"registers"| node_bot_handlers
node_user -->|"sends links"| node_telegram
node_admin -->|"reviews and manages"| node_telegram
node_telegram -.->|"dispatches updates"| node_bot_handlers
node_bot_handlers -.->|"routes requests"| node_download_handler
node_download_handler -->|"requests download"| node_download_router
node_download_router -->|"dispatches platform"| node_downloaders
node_download_router -->|"persists content"| node_repos
node_downloaders -->|"downloads from"| node_tiktok_api
node_downloaders -->|"downloads from"| node_hiker_api
node_downloaders -->|"downloads from"| node_youtube
node_download_handler -->|"returns files"| node_user
node_review -->|"reads and updates"| node_repos
node_review -->|"presents review items"| node_admin
node_review -.->|"queues approvals"| node_scheduler
node_repos -->|"operates on"| node_models
node_database -->|"creates schema"| node_models
node_scheduler -->|"loads schedule and queue"| node_repos
node_scheduler -->|"publishes queued item"| node_publisher
node_publisher -->|"processes media"| node_watermark
node_publisher -->|"publishes media"| node_instagram
node_instagram_auth -->|"manages session"| node_publisher
node_admin_controls -->|"reads and updates"| node_repos
node_admin_controls -.->|"manages logo"| node_watermark
node_admin_controls -.->|"opens workflow"| node_broadcast
node_admin_controls -.->|"opens workflow"| node_subscriptions
node_subscriptions -->|"manages requirements"| node_repos
node_admin -->|"sends announcements"| node_broadcast
node_admin -->|"configures channel access"| node_subscriptions
node_settings -->|"configures connection"| node_database
node_settings -->|"configures account"| node_publisher

click node_runtime "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/__main__.py"
click node_bot_factory "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/factory.py"
click node_bot_handlers "https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/bot/handlers"
click node_admin_controls "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/admin_menu.py"
click node_broadcast "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/broadcast.py"
click node_subscriptions "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/subscription.py"
click node_download_handler "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/download.py"
click node_download_router "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/downloaders/router.py"
click node_downloaders "https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/services/downloaders"
click node_review "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/content_review.py"
click node_instagram_auth "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/instagram_auth.py"
click node_scheduler "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/scheduler.py"
click node_publisher "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/instagram_publisher.py"
click node_watermark "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/watermark.py"
click node_repos "https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/db/repositories"
click node_models "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/db/models.py"
click node_database "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/db/engine.py"
click node_settings "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/settings.py"
click node_webhook "https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/web/webhook.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_runtime,node_bot_factory,node_bot_handlers,node_admin_controls,node_broadcast,node_subscriptions,node_user toneBlue
class node_download_handler,node_download_router,node_downloaders,node_review toneAmber
class node_instagram_auth,node_scheduler,node_publisher,node_watermark,node_tiktok_api,node_hiker_api toneMint
class node_repos,node_models,node_database toneRose
class node_settings,node_webhook,node_admin,node_telegram,node_instagram,node_youtube toneIndigo
```

## Components

### Telegram bot

- [Bot startup](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/__main__.py): `app/__main__.py`
- [Bot factory](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/factory.py): `app/bot/factory.py`
- [Bot handlers](https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/bot/handlers): `app/bot/handlers`
- [Admin controls](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/admin_menu.py): `app/bot/handlers/admin_menu.py`
- [Broadcast](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/broadcast.py): `app/bot/handlers/broadcast.py`
- [Subscriptions](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/subscription.py): `app/bot/handlers/subscription.py`

### Content workflow

- [Download requests](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/download.py): `app/bot/handlers/download.py`
- [Downloader router](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/downloaders/router.py): `app/services/downloaders/router.py`
- [Platform downloaders](https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/services/downloaders): `app/services/downloaders`
- [Content review](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/content_review.py): `app/bot/handlers/content_review.py`

### Publishing

- [Instagram session](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/bot/handlers/instagram_auth.py): `app/bot/handlers/instagram_auth.py`
- [Phase scheduler](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/scheduler.py): `app/services/scheduler.py`
- [Instagram publisher](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/instagram_publisher.py): `app/services/instagram_publisher.py`
- [Watermark processing](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/services/watermark.py): `app/services/watermark.py`

### Persistence

- [Data repositories](https://github.com/chadoyev/instagram-auto-publisher/tree/main/app/db/repositories): `app/db/repositories`
- [Content and schedule models](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/db/models.py): `app/db/models.py`
- [Database engine](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/db/engine.py): `app/db/engine.py`

### Configuration

- [Application settings](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/settings.py): `app/settings.py`
- [Webhook endpoint](https://github.com/chadoyev/instagram-auto-publisher/blob/main/app/web/webhook.py): `app/web/webhook.py`

### Other components

- **Bot user**
- **Administrator**
- **Telegram**
- **Instagram**
- **TikTok API**
- **HikerAPI**
- **YouTube**

## Connections

- Bot startup → Bot factory: creates bot (evidence: `app/__main__.py`)
- Bot startup → Database engine: initializes (evidence: `app/__main__.py`)
- Bot startup → Phase scheduler: starts (evidence: `app/__main__.py`)
- Bot startup → Webhook endpoint: uses in webhook mode (evidence: `app/__main__.py`)
- Bot factory → Bot handlers: registers (evidence: `app/bot/factory.py`)
- Bot user → Telegram: sends links (evidence: `README.md`)
- Administrator → Telegram: reviews and manages (evidence: `README.md`)
- Telegram → Bot handlers: dispatches updates
- Bot handlers → Download requests: routes requests
- Download requests → Downloader router: requests download (evidence: `app/bot/handlers/download.py`)
- Downloader router → Platform downloaders: dispatches platform (evidence: `app/services/downloaders/router.py`)
- Downloader router → Data repositories: persists content (evidence: `app/services/downloaders/router.py`)
- Platform downloaders → TikTok API: downloads from (evidence: `README.md`)
- Platform downloaders → HikerAPI: downloads from (evidence: `README.md`)
- Platform downloaders → YouTube: downloads from (evidence: `README.md`)
- Download requests → Bot user: returns files (evidence: `README.md`)
- Content review → Data repositories: reads and updates (evidence: `app/bot/handlers/content_review.py`)
- Content review → Administrator: presents review items (evidence: `README.md`)
- Content review → Phase scheduler: queues approvals
- Data repositories → Content and schedule models: operates on (evidence: `app/db/repositories/__init__.py`)
- Database engine → Content and schedule models: creates schema (evidence: `app/db/engine.py`)
- Phase scheduler → Data repositories: loads schedule and queue (evidence: `app/services/scheduler.py`)
- Phase scheduler → Instagram publisher: publishes queued item (evidence: `app/services/scheduler.py`)
- Instagram publisher → Watermark processing: processes media (evidence: `app/services/instagram_publisher.py`)
- Instagram publisher → Instagram: publishes media (evidence: `README.md`)
- Instagram session → Instagram publisher: manages session (evidence: `app/bot/handlers/instagram_auth.py`)
- Admin controls → Data repositories: reads and updates (evidence: `app/bot/handlers/admin_menu.py`)
- Admin controls → Watermark processing: manages logo (evidence: `app/bot/handlers/admin_menu.py`)
- Admin controls → Broadcast: opens workflow
- Admin controls → Subscriptions: opens workflow
- Subscriptions → Data repositories: manages requirements (evidence: `app/bot/handlers/subscription.py`)
- Administrator → Broadcast: sends announcements (evidence: `README.md`)
- Administrator → Subscriptions: configures channel access (evidence: `README.md`)
- Application settings → Database engine: configures connection (evidence: `app/db/engine.py`)
- Application settings → Instagram publisher: configures account (evidence: `app/services/instagram_publisher.py`)
