> For the complete documentation index, see [llms.txt](https://vitrina-blogerov.gitbook.io/bloggers-showcase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/obshaya-skhema-sistemy.md).
# Общая схема системы
{% hint style="info" %}
Платформа состоит из общего edge-слоя и нескольких независимых языковых версий приложения. Каждая языковая версия разворачивается как отдельный стек со своим backend, Telegram-ботом, базой данных, файлами и конфигурацией. Такой подход позволяет устанавливать, обновлять и администрировать версии независимо друг от друга.
{% endhint %}
Входящий HTTP-трафик принимает Caddy. Он обслуживает общие статические ресурсы и страницы ошибок, определяет нужную языковую версию и проксирует запросы в соответствующий backend. Взаимодействие с Telegram Bot API, AI-провайдерами и каналами публикации выполняется напрямую из backend и bot-контейнеров. Для установки, обновления, резервного копирования и удаления используются отдельные серверные утилиты.
### Пользователи, пограничный уровень и маршрутизация
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 30, "rankSpacing": 45, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
Browser["User browser"]
TgMobile["Telegram Mini App
mobile"]
TgDesktop["Telegram Mini App
desktop"]
TgWeb["Telegram Web
Mini App"]
AdminBrowser["Administrator browser"]
PublicEntry["Public request entry"]
EdgeCaddy["edge container
Caddy 2"]
RedirectPage["/opt/bloggers_platform/edge/www/index.html
language-version selection page"]
LanguageSelection["Selection priority
1. Telegram language
2. Browser language
3. fallback: en, zh, ar, ru"]
BackendRoutes["Caddy language routes"]
RUBackend["backend_ru
FastAPI + storefront
admin + API"]
ENBackend["backend_en
FastAPI + storefront
admin + API"]
ZHBackend["backend_zh
FastAPI + storefront
admin + API"]
ARBackend["backend_ar
FastAPI + storefront
admin + API"]
ErrorPages["/opt/bloggers_platform/edge/www/errors
403 / 404 / 502"]
EdgeAssets["/opt/bloggers_platform/edge/www/assets
style.css / bg.mp4"]
EdgeConfig["/opt/bloggers_platform/edge/Caddyfile"]
EdgeCompose["/opt/bloggers_platform/edge/docker-compose.yml"]
EdgeNetwork["Docker network
bloggers_edge"]
Browser -->|"https://domain/"| PublicEntry
TgMobile -->|"Mini App URL"| PublicEntry
TgDesktop -->|"Mini App URL"| PublicEntry
TgWeb -->|"Mini App iframe"| PublicEntry
AdminBrowser -->|"https://domain/bloggers/{lang}/admin"| PublicEntry
PublicEntry --> EdgeCaddy
EdgeCaddy -->|"root /"| RedirectPage
RedirectPage --> LanguageSelection
LanguageSelection -->|"redirected request"| BackendRoutes
EdgeCaddy -->|"direct /bloggers/{lang} request"| BackendRoutes
BackendRoutes -->|"/bloggers/ru/*"| RUBackend
BackendRoutes -->|"/bloggers/en/*"| ENBackend
BackendRoutes -->|"/bloggers/zh/*"| ZHBackend
BackendRoutes -->|"/bloggers/ar/*"| ARBackend
EdgeCaddy -->|"/errors/* and 403 / 404 / 502"| ErrorPages
EdgeCaddy -->|"/assets/*"| EdgeAssets
EdgeCaddy --- EdgeConfig
EdgeCaddy --- EdgeCompose
EdgeCaddy --- EdgeNetwork
EdgeNetwork --- RUBackend
EdgeNetwork --- ENBackend
EdgeNetwork --- ZHBackend
EdgeNetwork --- ARBackend
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Все пользовательские HTTP-запросы поступают в общий контейнер Caddy. Это относится к обычному браузеру, Telegram Mini App на мобильных и настольных клиентах, Telegram Web, а также к административной панели. Caddy выступает единой точкой входа и скрывает внутреннюю структуру контейнеров от внешнего клиента.
{% hint style="info" %}
При открытии корневого адреса сервер направляет пользователя на страницу выбора языковой версии. Сначала учитывается язык Telegram, затем язык браузера. Если определить подходящую версию не удалось, используется фиксированный порядок резервного выбора. После определения языка запрос перенаправляется на соответствующий путь /bloggers/{lang} и передаётся нужному backend через общую Docker-сеть.
{% endhint %}
Caddy также обслуживает общие статические ресурсы и страницы ошибок. Его конфигурация, Docker Compose-файл и служебные файлы хранятся отдельно от языковых приложений, поэтому edge-слой можно изменять без пересборки каждого стека.
### Внутренняя структура языковых версий
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 28, "rankSpacing": 42, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
subgraph RU["RU stack: /opt/bloggers_platform/apps/ru"]
direction LR
RUBackend["backend_ru
FastAPI + storefront
admin + API"]
RUBot["bot_ru
aiogram polling"]
RUDB[("PostgreSQL ru
bloggers_db")]
RUAssets["assets ru
photos, media, icons"]
RUBackend -->|"HTML storefront, admin panel, /api/*"| RUDB
RUBackend -->|"uploaded files"| RUAssets
RUBot -->|"settings, users, posts, welcome, AI config"| RUDB
end
subgraph EN["EN stack: /opt/bloggers_platform/apps/en"]
direction LR
ENBackend["backend_en
FastAPI + storefront
admin + API"]
ENBot["bot_en
aiogram polling"]
ENDB[("PostgreSQL en
bloggers_db")]
ENAssets["assets en
photos, media, icons"]
ENBackend -->|"HTML storefront, admin panel, /api/*"| ENDB
ENBackend -->|"uploaded files"| ENAssets
ENBot -->|"settings, users, posts, welcome, AI config"| ENDB
end
subgraph ZH["ZH stack: /opt/bloggers_platform/apps/zh"]
direction LR
ZHBackend["backend_zh
FastAPI + storefront
admin + API"]
ZHBot["bot_zh
aiogram polling"]
ZHDB[("PostgreSQL zh
bloggers_db")]
ZHAssets["assets zh
photos, media, icons"]
ZHBackend -->|"HTML storefront, admin panel, /api/*"| ZHDB
ZHBackend -->|"uploaded files"| ZHAssets
ZHBot -->|"settings, users, posts, welcome, AI config"| ZHDB
end
subgraph AR["AR stack: /opt/bloggers_platform/apps/ar"]
direction LR
ARBackend["backend_ar
FastAPI + storefront
admin + API"]
ARBot["bot_ar
aiogram polling"]
ARDB[("PostgreSQL ar
bloggers_db")]
ARAssets["assets ar
photos, media, icons"]
ARBackend -->|"HTML storefront, admin panel, /api/*"| ARDB
ARBackend -->|"uploaded files"| ARAssets
ARBot -->|"settings, users, posts, welcome, AI config"| ARDB
end
style RU fill:none,stroke:#71717a,stroke-width:1px
style EN fill:none,stroke:#71717a,stroke-width:1px
style ZH fill:none,stroke:#71717a,stroke-width:1px
style AR fill:none,stroke:#71717a,stroke-width:1px
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Каждая языковая версия представляет собой самостоятельный набор сервисов. В состав стека входят backend на FastAPI, Telegram-бот на aiogram, PostgreSQL и каталог загруженных файлов. Настройки версии хранятся в отдельном .env, где указываются язык приложения и публичный базовый путь.
Backend обслуживает витрину, административную панель и API. Данные пользователей, публикаций, настроек и контента сохраняются в отдельной базе данных конкретной языковой версии. Медиафайлы и иконки хранятся в файловом каталоге этого же стека.
Telegram-бот использует ту же базу данных, что и backend. За счёт этого изменения настроек, пользователей, приветственных сообщений и AI-конфигурации доступны обоим сервисам без дополнительной синхронизации между разными хранилищами.
### API Telegram-бота
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 30, "rankSpacing": 45, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
AdminTelegram["Administrator in Telegram bot"]
RUBot["bot_ru
aiogram polling"]
ENBot["bot_en
aiogram polling"]
ZHBot["bot_zh
aiogram polling"]
ARBot["bot_ar
aiogram polling"]
TelegramAPI["Telegram Bot API"]
PublishBus["Channel publication requests"]
TelegramChannel["Telegram channel
for publications"]
RUBot <-->|"polling / messages to API
updates from API"| TelegramAPI
ENBot <-->|"polling / messages to API
updates from API"| TelegramAPI
ZHBot <-->|"polling / messages to API
updates from API"| TelegramAPI
ARBot <-->|"polling / messages to API
updates from API"| TelegramAPI
RUBot -->|"channel posts"| PublishBus
ENBot -->|"channel posts"| PublishBus
ZHBot -->|"channel posts"| PublishBus
ARBot -->|"channel posts"| PublishBus
PublishBus --> TelegramChannel
AdminTelegram -->|"admin bot commands"| TelegramAPI
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Каждый языковой стек содержит отдельного Telegram-бота со своим токеном и настройками. Боты работают в режиме polling: отправляют запросы в Telegram Bot API, получают обновления и обрабатывают пользовательские или административные команды.
Публикации в Telegram-канал также выполняются через соответствующий языковой бот. Контент формируется внутри конкретной версии платформы, после чего бот отправляет подготовленное сообщение в настроенный канал.
Команды администратора проходят через тот же Telegram Bot API. Доступ к административным операциям ограничивается настройками конкретного бота и правилами авторизации, реализованными в приложении.
### Администрирование и поставщики услуг в области искусственного интеллекта
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 30, "rankSpacing": 45, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
AdminBrowser["Administrator browser"]
AdminAPI["JWT admin API requests"]
RUBackend["backend_ru"]
ENBackend["backend_en"]
ZHBackend["backend_zh"]
ARBackend["backend_ar"]
RUBot["bot_ru"]
ENBot["bot_en"]
ZHBot["bot_zh"]
ARBot["bot_ar"]
BackendAI["Backend AI search requests"]
BotAI["Bot AI consultant requests"]
AIProviders["AI providers
OpenAI / Groq / Gemini / OpenRouter"]
AdminBrowser --> AdminAPI
AdminAPI -->|"JWT admin API"| RUBackend
AdminAPI -->|"JWT admin API"| ENBackend
AdminAPI -->|"JWT admin API"| ZHBackend
AdminAPI -->|"JWT admin API"| ARBackend
RUBackend -->|"AI search"| BackendAI
ENBackend -->|"AI search"| BackendAI
ZHBackend -->|"AI search"| BackendAI
ARBackend -->|"AI search"| BackendAI
BackendAI --> AIProviders
RUBot -->|"AI consultant"| BotAI
ENBot -->|"AI consultant"| BotAI
ZHBot -->|"AI consultant"| BotAI
ARBot -->|"AI consultant"| BotAI
BotAI --> AIProviders
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Веб-администрирование выполняется через backend выбранной языковой версии. После авторизации браузер администратора обращается к защищённому API с использованием JWT. Каждый backend работает только со своей базой данных и не изменяет данные других языковых стеков.
Backend использует внешних AI-провайдеров для функций поиска и обработки данных. Telegram-боты обращаются к тем же провайдерам для работы AI-консультанта. Конкретный провайдер и параметры подключения определяются конфигурацией языковой версии.
Разделение запросов backend и Telegram-бота позволяет независимо управлять пользовательскими сценариями. При этом учётные данные и параметры AI-сервисов остаются частью конфигурации конкретного приложения.
### Установка и обновления
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 30, "rankSpacing": 45, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
Installer["install.sh
installs or updates one language version"]
PlatformManager["/opt/bloggers_platform/manager.sh
edge regeneration, status, logs"]
Delivery["deliveri.solodolik.com
install.sh, version archives, error pages"]
TelegramAPI["Telegram Bot API"]
AppsRoot["/opt/bloggers_platform/apps
language-version stacks"]
EdgeRoot["/opt/bloggers_platform/edge
shared edge layer"]
EnvWriter["Write language .env file"]
RUEnv["apps/ru/.env
APP_LANGUAGE=ru
PUBLIC_BASE_PATH=/bloggers/ru"]
ENEnv["apps/en/.env
APP_LANGUAGE=en
PUBLIC_BASE_PATH=/bloggers/en"]
ZHEnv["apps/zh/.env
APP_LANGUAGE=zh
PUBLIC_BASE_PATH=/bloggers/zh"]
AREnv["apps/ar/.env
APP_LANGUAGE=ar
PUBLIC_BASE_PATH=/bloggers/ar"]
Installer -->|"downloads selected archive by install token"| Delivery
Installer -->|"creates / updates apps/{lang}"| AppsRoot
Installer --> EnvWriter
EnvWriter -->|"writes .env"| RUEnv
EnvWriter -->|"writes .env"| ENEnv
EnvWriter -->|"writes .env"| ZHEnv
EnvWriter -->|"writes .env"| AREnv
Installer -->|"creates shared edge"| EdgeRoot
Installer -->|"setChatMenuButton"| TelegramAPI
PlatformManager -->|"regenerates Caddyfile and redirect page"| EdgeRoot
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Основная установка и обновление выполняются скриптом install.sh. Скрипт получает архив выбранной версии с сервера доставки, проверяет установочный токен и создаёт либо обновляет каталог apps/{lang}. После этого он записывает параметры языковой версии в .env и запускает необходимые контейнеры.
При первой установке также создаётся общий edge-слой. Для Telegram-бота настраивается кнопка запуска Mini App через метод setChatMenuButton. Это позволяет выполнить базовое развёртывание платформы без ручного редактирования Docker Compose и конфигурации Caddy.
Утилита manager.sh управляет общими компонентами платформы. Она пересобирает Caddyfile и страницу языкового перенаправления на основании реально установленных версий, а также предоставляет команды для просмотра состояния и журналов edge-слоя.
### Управление, резервное копирование и удаление
```mermaid
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 30, "rankSpacing": 45, "padding": 24}, "themeVariables": {"fontSize": "22px"}}}%%
flowchart TB
classDef default fill:#3f3f46,stroke:#71717a,stroke-width:2px,color:#ffffff,font-size:22px
ContentManager["/opt/bloggers_platform/content.sh
backup, restore, content export"]
AppManager["apps/{lang}/manager.sh
status, logs, restart, backup, update"]
Uninstaller["/opt/bloggers_platform/uninstall.sh
complete platform removal"]
RUDB[("PostgreSQL ru
bloggers_db")]
ENDB[("PostgreSQL en
bloggers_db")]
ZHDB[("PostgreSQL zh
bloggers_db")]
ARDB[("PostgreSQL ar
bloggers_db")]
RUStack["RU stack
/opt/bloggers_platform/apps/ru"]
ENStack["EN stack
/opt/bloggers_platform/apps/en"]
ZHStack["ZH stack
/opt/bloggers_platform/apps/zh"]
ARStack["AR stack
/opt/bloggers_platform/apps/ar"]
Platform["/opt/bloggers_platform"]
Backups["/opt/bloggers_platform/backups
manual, temp, exports"]
ContentManager -->|"backup / restore / export content"| RUDB
ContentManager -->|"backup / restore / export content"| ENDB
ContentManager -->|"backup / restore / export content"| ZHDB
ContentManager -->|"backup / restore / export content"| ARDB
ContentManager -->|"stores backups"| Backups
AppManager -->|"docker compose controls app stack"| RUStack
AppManager -->|"docker compose controls app stack"| ENStack
AppManager -->|"docker compose controls app stack"| ZHStack
AppManager -->|"docker compose controls app stack"| ARStack
Uninstaller -->|"stops containers, removes apps, edge, volumes"| Platform
Uninstaller -->|"pre-removal backup"| Backups
linkStyle default stroke:#9ca3af,stroke-width:2px
```
Для управления отдельной языковой версией используется скрипт apps/{lang}/manager.sh. Через него можно проверить состояние контейнеров, просмотреть логи, перезапустить стек, создать резервную копию или выполнить обновление. Команды применяются только к выбранному языку и не затрагивают остальные версии.
Операции с контентом выполняются через content.sh. Утилита создаёт резервные копии баз данных, восстанавливает данные и экспортирует содержимое языковых версий. Полученные архивы сохраняются в общем каталоге /opt/bloggers\_platform/backups.
Полное удаление платформы выполняется скриптом uninstall.sh. Перед удалением он может создать резервную копию, после чего останавливает контейнеры и удаляет приложения, edge-слой и связанные Docker-тома.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/obshaya-skhema-sistemy.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.