TGACH (Telegram-Attached Imageboard)
TGACH — это гибридная платформа для анонимного общения, объединяющая классическую механику имиджборд (imageboard) с современными возможностями мессенджеров (Telegram). Проект обеспечивает бесшовную синхронизацию контента: треды, созданные на сайте, мгновенно появляются в Telegram-чате, а сообщения из Telegram реплицируются на сайт в реальном времени.
📑 Оглавление
Философия и Архитектура
Функциональные возможности
Технический стек
Структура Фронтенда (Deep Dive)
Модульная архитектура JS
Система темизации (CSS Variables)
Адаптивность и Mobile-First
API Reference (Frontend Consumer)
Администрирование и Модерация
Установка и Запуск
Руководство по разработке (Contributing)
🏛 Философия и Архитектура
TGACH отвергает тяжелые SPA-фреймворки (React, Vue, Angular) в пользу чистого, производительного Vanilla JavaScript и Server-Side Rendering (SSR) через Jinja2. Это обеспечивает:
Молниеносную загрузку: Браузер получает готовый HTML.
SEO-оптимизацию: Контент доступен поисковикам без гидратации JS.
Устойчивость: Основной функционал (просмотр) работает даже без JS.
Реактивность: WebSocket соединение обеспечивает обновление контента без перезагрузки (Live Updates).
Схема потока данных
Пользователь (Web) отправляет форму -> FastAPI сохраняет в БД -> отправляет в Telegram Bot API -> рассылает уведомление через WebSocket.
Пользователь (Telegram) пишет сообщение -> Bot Webhook ловит апдейт -> сохраняет в БД -> рассылает уведомление через WebSocket.
🚀 Функциональные возможности Для пользователей
Гибридный постинг: Текст, Изображения, Видео, Аудио, Стикеры (Webp/Webm), Голосовые сообщения.
Real-time обновления: Новые посты появляются мгновенно (WebSocket).
Медиа-плеер:
Кастомный аудио-плеер с визуализацией волны (Waveform).
Галерея изображений с поддержкой Zoom (Pinch-to-zoom), Double Tap, Pan и слайдшоу.
Поддержка "Video Notes" (круглые видео) и WebM-стикеров.
UX/UI:
Плавающая форма ответа (Floating Reply Box).
Быстрое цитирование (выделение текста -> кнопка "Цитировать").
Предпросмотр тредов и постов при наведении (Preview Popup).
Автоматическое скрытие хедера при скролле.
Индикаторы "Живой вкладки" (мигание title при новых постах).
Персонализация:
20+ тем оформления (Shaft, Cyberpunk, Win95, Nord, Discord, Lain и др.).
Настройка шрифтов и плотности интерфейса.
Аватарки-идентиконы (генерируются на клиенте через Canvas).
Локальное сохранение настроек и скрытых постов.
Интерактив:
Система реакций (Emoji).
Опросы (Polls).
"Бутылочная почта" (Анонимные личные сообщения).
Ачивки за скроллинг.
Пасхалки (Konami Code, Dice Roll).
Для администрации
Wipe System: Удаление всех постов конкретного юзера одной кнопкой.
Shadow Ban: Пользователь продолжает постить, но его сообщения не видит никто, кроме него.
Report System: Система жалоб с категориями.
Alert System: Рассылка глобальных уведомлений (модальные окна) пользователям.
Stealth Edit: Тихое редактирование постов (без пометки "изменено").
Dashboard: Мониторинг здоровья сервера (CPU/RAM), статистика онлайна WS.
🛠 Технический стек Backend
Language: Python 3.10+
Framework: FastAPI (ASGI)
Database: SQLite (с возможностью миграции на PostgreSQL)
Templating: Jinja2
Async: asyncio, aiofiles
Frontend
Markup: HTML5 (Semantic)
Styling: CSS3 (Variables, Grid, Flexbox, Animations). Без Bootstrap/Tailwind.
Logic: Vanilla ES6+ JavaScript. Без jQuery.
Architecture: Singleton Managers Pattern.
🧠 Структура Фронтенда (Deep Dive)
Frontend построен на базе паттерна "Менеджеры". Каждый логический блок вынесен в отдельный объект-синглтон в main.js.
Модульная архитектура JS
- SettingsManager
Управляет пользовательскими настройками.
Хранилище: localStorage (user_settings).
Функции: Применение темы, размера шрифта, режима отображения (Grid/List).
Логика: Автоматически определяет системную тему (Dark/Light) при первом запуске.
- WSManager (WebSocket)
Отвечает за двустороннюю связь с сервером.
Heartbeat: Пинг каждые 30 секунд для поддержания соединения (nginx timeout fix).
Reconnect: Экспоненциальная задержка при разрыве соединения.
Обработка сообщений:
chat: Добавляет посты в ленту. Если юзер внизу страницы — автоскролл. Если читает историю — показывает кнопку "Новые сообщения".
catalog: Обновляет статистику тредов и поднимает тред (bump) в реальном времени.
live_update: Поддерживает обновление контента поста (например, при Stealth Edit).
- GalleryManager
Продвинутый просмотрщик медиа.
Жесты: Полная реализация Touch Events (touchstart, touchmove, touchend).
Pinch-to-Zoom (расчет дистанции между двумя пальцами).
Double Tap (умный зум в точку нажатия).
Swipe (листание).
Оптимизация: Использует технику "Blur Up". Сначала показывается растянутое превью (thumbnail), после загрузки оригинала подменяется на Full HD версию с пересчетом координат (fitToScreen).
- FormManager
Управляет отправкой контента.
Dual Mode: Работает и с основной формой (внизу/вверху), и с плавающим окном (floating-reply-box).
Drag & Drop: Глобальный перехват файлов на всей странице.
Audio Recorder: Захват микрофона через MediaRecorder API, кодирование в WebM/Ogg на лету.
AutoSave: Сохранение черновика текста в localStorage при каждом нажатии клавиши.
- PostRenderer
Генератор HTML из JSON-объекта поста (полученного через WS).
Дублирует логику Jinja2-шаблонов на клиенте для мгновенного рендеринга без запроса к серверу.
Обрабатывает все типы вложений: Видео-ноты (кружочки), Стикеры, Аудио.
- StealthEditor & AdminManager
Инструменты бога.
Реализуют скрытые API вызовы для модерации.
StealthEditor подгружает сырой текст поста (с разметкой) в модальное окно.
Система темизации (CSS Variables)
Стилизация реализована через мощную систему CSS переменных (:root). Переключение темы сводится к замене класса у .
Ключевые переменные:
:root { --bg-page: #f4f4f4; /* Фон страницы / --bg-post: #ffffff; / Фон поста / --text-primary: #212121; / Основной текст / --accent-primary: #0088cc; / Акцентный цвет (кнопки, ссылки) / --border-primary: #e0e0e0; / Рамки / --action-danger: #d9534f; / Цвет деструктивных действий */ }
Особенности уникальных тем:
Shaft (Monogatari): Использование шрифта Noto Serif, иероглифы на фоне через ::before, резкие углы (border-radius: 0), анимация "Warning Tape" для разделителей.
Cyberpunk: Активное использование text-shadow для эффекта неона, анимация neon-breath для инпутов, CRT-сетка на фоне.
Windows 95: Имитация 3D-рамок через border-color: #fff #808080 #808080 #fff (Bevel effect), синие заголовки окон.
Lain / Terminal: Эффекты хроматической аберрации, статический шум (SVG Noise), анимация печатающегося текста для новых постов.
Адаптивность и Mobile-First
CSS написан с учетом жесткой оптимизации под мобильные устройства (@media (max-width: 768px)).
Touch Targets: Все кнопки на мобильных устройствах имеют минимальную высоту 44px (стандарт Apple Human Interface Guidelines).
Navigation: Хедер перестраивается. Появляется нижняя навигационная панель (mobile-bottom-nav) с эффектом матового стекла (backdrop-filter: blur).
Inputs: Предотвращение зума на iOS (font-size >= 16px).
Floating Action Button (FAB): Кнопка быстрого ответа в правом нижнем углу.
📡 API Reference (Frontend Consumer)
JS-клиент взаимодействует с бэкендом через следующие эндпоинты (восстановлено по коду main.js):
Public Endpoints
POST /api/post/{board_id} — Создание треда или поста. Поддерживает multipart/form-data.
GET /api/threads/{board_id}?page=X — Пагинация тредов.
GET /api/chat/{board_id} — Получение истории чата.
GET /api/post/{post_id} — Получение сырых данных поста (для превью/редактирования).
POST /api/react — Отправка реакции (эмодзи). Payload: {post_num, emoji}.
POST /api/report — Отправка жалобы.
POST /api/feedback — Отправка формы обратной связи.
POST /api/poll/vote — Голосование в опросе.
Admin Endpoints (Require Auth & Rights)
POST /api/admin/delete_post — Удаление.
POST /api/admin/ban_user — Бан.
POST /api/admin/shadow_ban — Теневой бан. Payload: {post_num, duration}.
POST /api/admin/wipe_user — Удаление всех постов юзера.
POST /api/admin/stealth_edit — Редактирование контента.
GET /api/admin/stats — Статистика сервера.
GET /api/admin/logs — Системные логи.
🛡 Администрирование и Модерация
Вход в админ-панель осуществляется через кнопку 👮♂️ в хедере (доступна только при наличии флага is_admin в сессии).
Инструменты модератора
Контекстное меню: При клике на ▶ у поста админ видит расширенный список действий (выделены красным).
Shadow Ban: Эффективный метод борьбы со спамерами. Спамер видит свои посты, остальные — нет. Вызывается через модальное окно с выбором длительности (1 час - 30 дней).
Wipe: Экстренная кнопка. Удаляет все следы пребывания юзера на борде. Использовать с осторожностью.
Приемная (Feedback): Вкладка в админ-панели, куда падают тикеты от пользователей с сайта. Позволяет отвечать (пока ментально) и удалять прочитанное.
📥 Установка и Запуск Предварительные требования
Python 3.10+
FFmpeg (для обработки аудио/видео)
Telegram Bot Token (от @BotFather)
Шаг 1: Клонирование git clone https://github.com/your-repo/tgach.git cd tgach Шаг 2: Окружение python -m venv venv source venv/bin/activate # Linux/Mac
pip install -r requirements.txt
Шаг 3: Конфигурация
Создайте файл .env или настройте config.py:
TELEGRAM_BOT_TOKEN=your_token_here ADMIN_SECRET=change_this_to_something_secure DB_NAME=tgach.db Шаг 4: Запуск
uvicorn main:app --reload --host 0.0.0.0 --port 8000
Сайт будет доступен по адресу http://localhost:8000.
🤝 Руководство по разработке (Contributing)
Мы приветствуем Pull Requests! Пожалуйста, следуйте этим правилам:
No Frameworks: Не предлагайте переписать фронтенд на React/Vue. Мы ценим простоту и отсутствие build-step'ов для JS.
CSS Variables: При добавлении новых стилей используйте существующие переменные (var(--bg-post), и т.д.) для поддержки всех тем.
Managers: Если вы добавляете новую логику на фронт, инкапсулируйте её в новый объект-менеджер (например, RadioManager), а не пишите код в глобальную область видимости.
Linting: Старайтесь соблюдать стиль кода (точки с запятой в JS, отступы 4 пробела).
Как добавить новую тему?
Откройте style.css.
Добавьте класс body.theme-newname.
Переопределите ключевые переменные (--bg-page, --accent-primary).
Добавьте специфичные CSS-хаки (например, ::before для фоновых картинок).
Добавьте опцию в в файлах шаблонов (.jinja2) в модалке настроек. 2025 ТГАЧ Team. Код написан с ненавистью к современному вебу и любовью к анонимности.