# mhm-hossein/mewvia architecture

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

- Interactive diagram: https://gitdiagram.com/mhm-hossein/mewvia
- Repository: https://github.com/mhm-hossein/mewvia

## Overview

Mewvia is a Telegram media-toolbox bot. Users send media or choose a feature; handlers identify the operation, invoke media processing, and return results through Telegram. The product also includes personal sticker packs, download/search, group-media assistance, games and an admin panel. The README documents the broad feature flow; sampled handlers and the source index support several internal links. Unsampled feature implementations are represented only where the tree or README establishes them.

Main entry points: [`app/media`](https://github.com/mhm-hossein/mewvia/tree/master/app/media) (Specialized media tools), [`app/admin/router.py`](https://github.com/mhm-hossein/mewvia/blob/master/app/admin/router.py) (Admin panel), [`app/features/convert/router.py`](https://github.com/mhm-hossein/mewvia/blob/master/app/features/convert/router.py) (Media conversion), [`app/features/batch/router.py`](https://github.com/mhm-hossein/mewvia/blob/master/app/features/batch/router.py) (Batch processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Polling runtime<br/>[__main__.py]"]
  node_registry["Feature registry<br/>[registry.py]"]
end

subgraph group_features["User features"]
  node_convert["Media conversion<br/>[router.py]"]
  node_batch["Batch processing<br/>[router.py]"]
  node_audio["Audio tools<br/>[router.py]"]
  node_video["Video tools<br/>[router.py]"]
  node_sticker["Sticker packs<br/>[router.py]"]
  node_downloader["Media downloader<br/>[router.py]"]
  node_music["Music search<br/>[router.py]"]
  node_shazam["Shazam lookup<br/>[router.py]"]
  node_tag["Tag editor<br/>[router.py]"]
  node_filters["Media filters<br/>[router.py]"]
  node_groupmedia["Group media helper<br/>[router.py]"]
  node_games["Games<br/>[router.py]"]
end

subgraph group_media["Media processing"]
  node_kind["Media detection<br/>[kinds.py]"]
  node_pipeline["Conversion pipeline<br/>[pipeline.py]"]
  node_media_tools["Specialized media tools"]
  node_image["Image and frame tools<br/>[image_tools.py]"]
end

subgraph group_platform["Shared platform"]
  node_db[("PostgreSQL<br/>[session.py]")]
  node_repos["Data repositories"]
  node_redis[("Redis cache<br/>[redis.py]")]
  node_guard["Group panel guard<br/>[group_guard.py]"]
  node_ui["UI kit<br/>[kb.py]"]
  node_quota["Daily quota<br/>[quota.py]"]
  node_sponsor["Sponsor gate<br/>[sponsor_gate.py]"]
  node_settings["Runtime settings<br/>[settings_store.py]"]
end

subgraph group_admin["Administration"]
  node_admin["Admin panel<br/>[router.py]"]
  node_backup["Backup tools<br/>[backup.py]"]
  node_broadcast["Broadcast and exports<br/>[broadcast.py]"]
end

node_user(("Telegram user"))
node_telegram(("Telegram Bot API"))

node_user -->|"sends media"| node_telegram
node_telegram -->|"delivers updates"| node_entry
node_entry -->|"attaches features"| node_registry
node_user -->|"requests conversion"| node_convert
node_convert -->|"identifies media"| node_kind
node_convert -->|"requests conversion"| node_pipeline
node_pipeline -->|"returns result"| node_telegram
node_user -->|"chooses audio tool"| node_audio
node_user -->|"chooses video tool"| node_video
node_user -->|"manages packs"| node_sticker
node_sticker -->|"uses repositories"| node_repos
node_user -->|"requests download"| node_downloader
node_downloader -->|"uses downloader"| node_media_tools
node_user -->|"searches music"| node_music
node_music -->|"uses search tools"| node_media_tools
node_user -->|"requests recognition"| node_shazam
node_user -->|"requests batch work"| node_batch
node_batch -->|"classifies media"| node_kind
node_batch -->|"uses chained processing"| node_media_tools
node_user -->|"edits metadata"| node_tag
node_user -->|"applies filters"| node_filters
node_user -->|"uses group panel"| node_groupmedia
node_user -->|"plays games"| node_games
node_user -->|"uses image tools"| node_image
node_audio -->|"uses audio tools"| node_media_tools
node_video -->|"uses video tools"| node_media_tools
node_media_tools -->|"uses conversion core"| node_pipeline
node_guard -->|"stores panel state"| node_redis
node_guard -->|"resolves panel media"| node_kind
node_quota -->|"reads quota setting"| node_settings
node_quota -->|"counts conversions"| node_db
node_ui -->|"builds bot keyboards"| node_telegram
node_sponsor -->|"checks membership"| node_user
node_admin -->|"delegates backup"| node_backup
node_admin -->|"delegates broadcast"| node_broadcast
node_admin -->|"uses repositories"| node_repos
node_repos -.->|"queries database"| node_db

click node_entry "https://github.com/mhm-hossein/mewvia/blob/master/app/__main__.py"
click node_registry "https://github.com/mhm-hossein/mewvia/blob/master/app/features/registry.py"
click node_convert "https://github.com/mhm-hossein/mewvia/blob/master/app/features/convert/router.py"
click node_batch "https://github.com/mhm-hossein/mewvia/blob/master/app/features/batch/router.py"
click node_audio "https://github.com/mhm-hossein/mewvia/blob/master/app/features/audio/router.py"
click node_video "https://github.com/mhm-hossein/mewvia/blob/master/app/features/videotools/router.py"
click node_sticker "https://github.com/mhm-hossein/mewvia/blob/master/app/features/stickerpack/router.py"
click node_downloader "https://github.com/mhm-hossein/mewvia/blob/master/app/features/downloader/router.py"
click node_music "https://github.com/mhm-hossein/mewvia/blob/master/app/features/music_search/router.py"
click node_shazam "https://github.com/mhm-hossein/mewvia/blob/master/app/features/shazam/router.py"
click node_tag "https://github.com/mhm-hossein/mewvia/blob/master/app/features/tag_editor/router.py"
click node_filters "https://github.com/mhm-hossein/mewvia/blob/master/app/features/filters/router.py"
click node_groupmedia "https://github.com/mhm-hossein/mewvia/blob/master/app/features/group_media/router.py"
click node_games "https://github.com/mhm-hossein/mewvia/blob/master/app/features/games/router.py"
click node_kind "https://github.com/mhm-hossein/mewvia/blob/master/app/media/kinds.py"
click node_pipeline "https://github.com/mhm-hossein/mewvia/blob/master/app/media/pipeline.py"
click node_media_tools "https://github.com/mhm-hossein/mewvia/tree/master/app/media"
click node_image "https://github.com/mhm-hossein/mewvia/blob/master/app/media/image_tools.py"
click node_db "https://github.com/mhm-hossein/mewvia/blob/master/app/db/session.py"
click node_repos "https://github.com/mhm-hossein/mewvia/tree/master/app/db/repo"
click node_redis "https://github.com/mhm-hossein/mewvia/blob/master/app/cache/redis.py"
click node_guard "https://github.com/mhm-hossein/mewvia/blob/master/app/middlewares/group_guard.py"
click node_ui "https://github.com/mhm-hossein/mewvia/blob/master/app/ui/kb.py"
click node_quota "https://github.com/mhm-hossein/mewvia/blob/master/app/core/quota.py"
click node_sponsor "https://github.com/mhm-hossein/mewvia/blob/master/app/middlewares/sponsor_gate.py"
click node_admin "https://github.com/mhm-hossein/mewvia/blob/master/app/admin/router.py"
click node_backup "https://github.com/mhm-hossein/mewvia/blob/master/app/admin/backup.py"
click node_broadcast "https://github.com/mhm-hossein/mewvia/blob/master/app/admin/broadcast.py"
click node_settings "https://github.com/mhm-hossein/mewvia/blob/master/app/core/settings_store.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_entry,node_registry,node_user toneBlue
class node_convert,node_batch,node_audio,node_video,node_sticker,node_downloader,node_music,node_shazam,node_tag,node_filters,node_groupmedia,node_games toneAmber
class node_kind,node_pipeline,node_media_tools,node_image,node_telegram toneMint
class node_db,node_repos,node_redis,node_guard,node_ui,node_quota,node_sponsor,node_settings toneRose
class node_admin,node_backup,node_broadcast toneIndigo
```

## Components

### Bot runtime

- [Polling runtime](https://github.com/mhm-hossein/mewvia/blob/master/app/__main__.py): `app/__main__.py`
- [Feature registry](https://github.com/mhm-hossein/mewvia/blob/master/app/features/registry.py): `app/features/registry.py`

### User features

- [Media conversion](https://github.com/mhm-hossein/mewvia/blob/master/app/features/convert/router.py): `app/features/convert/router.py`
- [Batch processing](https://github.com/mhm-hossein/mewvia/blob/master/app/features/batch/router.py): `app/features/batch/router.py`
- [Audio tools](https://github.com/mhm-hossein/mewvia/blob/master/app/features/audio/router.py): `app/features/audio/router.py`
- [Video tools](https://github.com/mhm-hossein/mewvia/blob/master/app/features/videotools/router.py): `app/features/videotools/router.py`
- [Sticker packs](https://github.com/mhm-hossein/mewvia/blob/master/app/features/stickerpack/router.py): `app/features/stickerpack/router.py`
- [Media downloader](https://github.com/mhm-hossein/mewvia/blob/master/app/features/downloader/router.py): `app/features/downloader/router.py`
- [Music search](https://github.com/mhm-hossein/mewvia/blob/master/app/features/music_search/router.py): `app/features/music_search/router.py`
- [Shazam lookup](https://github.com/mhm-hossein/mewvia/blob/master/app/features/shazam/router.py): `app/features/shazam/router.py`
- [Tag editor](https://github.com/mhm-hossein/mewvia/blob/master/app/features/tag_editor/router.py): `app/features/tag_editor/router.py`
- [Media filters](https://github.com/mhm-hossein/mewvia/blob/master/app/features/filters/router.py): `app/features/filters/router.py`
- [Group media helper](https://github.com/mhm-hossein/mewvia/blob/master/app/features/group_media/router.py): `app/features/group_media/router.py`
- [Games](https://github.com/mhm-hossein/mewvia/blob/master/app/features/games/router.py): `app/features/games/router.py`

### Media processing

- [Media detection](https://github.com/mhm-hossein/mewvia/blob/master/app/media/kinds.py): `app/media/kinds.py`
- [Conversion pipeline](https://github.com/mhm-hossein/mewvia/blob/master/app/media/pipeline.py): `app/media/pipeline.py`
- [Specialized media tools](https://github.com/mhm-hossein/mewvia/tree/master/app/media): `app/media`
- [Image and frame tools](https://github.com/mhm-hossein/mewvia/blob/master/app/media/image_tools.py): `app/media/image_tools.py`

### Shared platform

- [PostgreSQL](https://github.com/mhm-hossein/mewvia/blob/master/app/db/session.py): `app/db/session.py`
- [Data repositories](https://github.com/mhm-hossein/mewvia/tree/master/app/db/repo): `app/db/repo`
- [Redis cache](https://github.com/mhm-hossein/mewvia/blob/master/app/cache/redis.py): `app/cache/redis.py`
- [Group panel guard](https://github.com/mhm-hossein/mewvia/blob/master/app/middlewares/group_guard.py): `app/middlewares/group_guard.py`
- [UI kit](https://github.com/mhm-hossein/mewvia/blob/master/app/ui/kb.py): `app/ui/kb.py`
- [Daily quota](https://github.com/mhm-hossein/mewvia/blob/master/app/core/quota.py): `app/core/quota.py`
- [Sponsor gate](https://github.com/mhm-hossein/mewvia/blob/master/app/middlewares/sponsor_gate.py): `app/middlewares/sponsor_gate.py`
- [Runtime settings](https://github.com/mhm-hossein/mewvia/blob/master/app/core/settings_store.py): `app/core/settings_store.py`

### Administration

- [Admin panel](https://github.com/mhm-hossein/mewvia/blob/master/app/admin/router.py): `app/admin/router.py`
- [Backup tools](https://github.com/mhm-hossein/mewvia/blob/master/app/admin/backup.py): `app/admin/backup.py`
- [Broadcast and exports](https://github.com/mhm-hossein/mewvia/blob/master/app/admin/broadcast.py): `app/admin/broadcast.py`

### Other components

- **Telegram user**
- **Telegram Bot API**

## Connections

- Telegram user → Telegram Bot API: sends media
- Telegram Bot API → Polling runtime: delivers updates
- Polling runtime → Feature registry: attaches features (evidence: `app/features/registry.py`)
- Telegram user → Media conversion: requests conversion
- Media conversion → Media detection: identifies media
- Media conversion → Conversion pipeline: requests conversion
- Conversion pipeline → Telegram Bot API: returns result
- Telegram user → Audio tools: chooses audio tool
- Telegram user → Video tools: chooses video tool
- Telegram user → Sticker packs: manages packs
- Sticker packs → Data repositories: uses repositories (evidence: `app/features/stickerpack/router.py`)
- Telegram user → Media downloader: requests download (evidence: `app/features/downloader/router.py`)
- Media downloader → Specialized media tools: uses downloader (evidence: `app/features/downloader/router.py`)
- Telegram user → Music search: searches music (evidence: `app/features/music_search/router.py`)
- Music search → Specialized media tools: uses search tools (evidence: `app/features/music_search/router.py`)
- Telegram user → Shazam lookup: requests recognition
- Telegram user → Batch processing: requests batch work (evidence: `app/features/batch/router.py`)
- Batch processing → Media detection: classifies media (evidence: `app/features/batch/router.py`)
- Batch processing → Specialized media tools: uses chained processing (evidence: `app/features/batch/router.py`)
- Telegram user → Tag editor: edits metadata (evidence: `app/features/tag_editor/router.py`)
- Telegram user → Media filters: applies filters
- Telegram user → Group media helper: uses group panel
- Telegram user → Games: plays games
- Telegram user → Image and frame tools: uses image tools
- Audio tools → Specialized media tools: uses audio tools (evidence: `app/features/audio/router.py`)
- Video tools → Specialized media tools: uses video tools (evidence: `app/features/videotools/router.py`)
- Specialized media tools → Conversion pipeline: uses conversion core (evidence: `app/media/chained_pipeline.py`)
- Group panel guard → Redis cache: stores panel state (evidence: `app/middlewares/group_guard.py`)
- Group panel guard → Media detection: resolves panel media (evidence: `app/media/kinds.py`)
- Daily quota → Runtime settings: reads quota setting (evidence: `app/core/quota.py`)
- Daily quota → PostgreSQL: counts conversions (evidence: `app/core/quota.py`)
- UI kit → Telegram Bot API: builds bot keyboards (evidence: `app/ui/kb.py`)
- Sponsor gate → Telegram user: checks membership (evidence: `app/middlewares/sponsor_gate.py`)
- Admin panel → Backup tools: delegates backup (evidence: `app/admin/router.py`)
- Admin panel → Broadcast and exports: delegates broadcast (evidence: `app/admin/router.py`)
- Admin panel → Data repositories: uses repositories (evidence: `app/admin/router.py`)
- Data repositories → PostgreSQL: queries database
