<<<<<<< HEAD

TGACH (dvachbot_cloned)

Telegram-Attached Hybrid Imageboard Platform with Real-time WebSocket Synchronization

Philosophy • Features • Architecture • Component Matrix • API Reference • Original Docs

---

🏛 Философия и Архитектура

TGACH — гибридная платформа для анонимного общения, объединяющая классическую механику имиджборд (imageboard) с возможностями мессенджера Telegram. Проект обеспечивает двустороннюю синхронизацию контента: треды, созданные на сайте, мгновенно транслируются в Telegram-чат, а сообщения из Telegram реплицируются на сайт в реальном времени.

TGACH отвергает тяжелые SPA-фреймворки (React, Vue) в пользу чистого, производительного Vanilla JavaScript и Server-Side Rendering (SSR) через Jinja2:

• Молниеносная загрузка: Браузер получает готовый HTML от сервера FastAPI.
• SEO-оптимизация: Контент доступен поисковикам без JS-гидратации.
• Устойчивость: Базовый просмотр работает даже при отключенном JavaScript.
• Реактивность: WebSocket-соединение обеспечивает обновление контента без перезагрузки (Live Updates).

---

📐 Architecture & Data Flow

flowchart TD
    subgraph WebClient [Web Client (Vanilla JS)]
        A[User Form Input] -->|1. HTTP POST| B[FastAPI Endpoint]
        G[WebSocket Listener] <--|5. Live WS Updates| F[WebSocket Manager]
    end

    subgraph Server [Backend Core (FastAPI)]
        B -->|2. Write DB Record| C[(SQLite / PostgreSQL)]
        C -->|3. Trigger Event| D[Sync Dispatcher]
        D -->|4. Push Broadcast| F
    end

    subgraph Telegram [Telegram Integration]
        D -->|5. Bot API Send| E[Telegram Group / Channel]
        E -->|6. Webhook Event| H[Bot Webhook Listener]
        H -->|7. Ingest Telegram Post| C
    end

Loading

---

📂 File Tree & Component Matrix

dvachbot_cloned/
├── Dubsite_tgach/          # Primary imageboard web application instance
│   ├── static/             # Assets (CSS themes, JS managers, icons, audio)
│   │   ├── css/            # Theme variables (Cyberpunk, Win95, Shaft, Lain)
│   │   └── js/             # Vanilla JS singleton managers (WS, Gallery, Form)
│   └── templates/          # Jinja2 SSR HTML templates
├── site_tgach/             # Secondary standalone web node
├── common/                 # Shared database models & API schemas
├── data/                   # SQLite database storage & media uploads
├── scripts/                # Database migrations & admin automation
├── pyproject.toml          # Python project metadata
└── requirements.txt        # Server dependencies (FastAPI, uvicorn, aiofiles)

Path	Primary Tech	Role / Component Description
Dubsite_tgach/static/js/main.js	Vanilla ES6+ JS	Client orchestrator containing singleton managers (WSManager, GalleryManager, FormManager)
Dubsite_tgach/static/css/style.css	CSS3 Variables	Dynamic theme engine supporting 20+ visual themes without re-compilation
common/	Python 3.10	Core data models, Pydantic validation schemas, and database connectors
site_tgach/	FastAPI / Jinja2	Async web server rendering SSR HTML pages and handling WebSocket channels
scripts/	Python / Shell	Database maintenance scripts, moderation tools, and backup utilities

---

🚀 Функциональные возможности

Для пользователей

• Гибридный постинг: Текст, Изображения, Видео, Аудио, WebM-стикеры, Голосовые сообщения, Кружочки ("Video Notes").
• Real-time обновления: Новые посты и ветки отображаются мгновенно через WebSockets.
• Продвинутый медиа-плеер: Кастомный аудио-плеер с визуализацией волны (Waveform), галерея с поддержкой Pinch-to-zoom и Double Tap.
• Персонализация UX: 20+ визуальных тем (Shaft, Cyberpunk, Win95, Nord, Discord, Lain), кастомные аватарки-идентиконы.
• Интерактив: Система эмодзи-реакций, голосования (Polls), анонимные сообщения ("Бутылочная почта").

Для администрации

• Wipe System: Экстренная очистка всех сообщений пользователя в один клик.
• Shadow Ban: Теневая блокировка спамеров без видимого уведомления нарушителя.
• Stealth Edit: Тихое редактирование контента постов без отметки "изменено".
• Dashboard: Системный мониторинг нагрузки (CPU/RAM) и WebSocket-онлайна.

---

🛠 Технический стек

Слой	Технологии
Backend	Python 3.10+, FastAPI (ASGI), asyncio, aiofiles, Jinja2
Database	SQLite (WAL mode) / PostgreSQL compatibility
Frontend	HTML5, CSS3 Variables (Zero-Tailwind), Vanilla ES6+ JS (Singleton Managers)
Protocol	WebSockets, HTTP REST API, Telegram Bot API Webhooks

---

📡 API Reference (Frontend Consumer)

Public Endpoints

• POST /api/post/{board_id} — Создание треда или ответа (multipart/form-data)
• GET /api/threads/{board_id}?page=X — Пагинация тредов борды
• GET /api/chat/{board_id} — Загрузка истории сообщений
• POST /api/react — Отправка реакций (эмодзи)
• POST /api/poll/vote — Участие в опросах

Admin Endpoints (Auth Required)

• POST /api/admin/delete_post — Удаление поста
• POST /api/admin/shadow_ban — Установка теневого бана
• POST /api/admin/wipe_user — Массовое удаление постов пользователя
• POST /api/admin/stealth_edit — Скрытое редактирование текста

---

📄 Original Developer Documentation

The text below represents 100% of the original pre-agent developer documentation preserved verbatim from repository initial commit history:

TGACH (Telegram-Attached Imageboard)

TGACH — это гибридная платформа для анонимного общения, объединяющая классическую механику имиджборд (imageboard) с современными возможностями мессенджеров (Telegram). Проект обеспечивает бесшовную синхронизацию контента: треды, созданные на сайте, мгновенно появляются в Telegram-чате, а сообщения из Telegram реплицируются на сайт в реальном времени.

Оглавление:
- Философия и Архитектура
- Функциональные возможности
- Технический стек
- Структура Фронтенда (Deep Dive)
- Модульная архитектура JS
- Система темизации (CSS Variables)
- Адаптивность и Mobile-First
- API Reference (Frontend Consumer)
- Администрирование и Модерация
- Установка и Запуск
- Руководство по разработке (Contributing)

---

---

🇷🇺 Краткое описание на русском

TGACH — Имиджборд с интеграцией в Telegram

TGACH (dvachbot_cloned) — гибридная веб-платформа для анонимного общения, сочетающая классический формат имиджборда с функционалом мессенджера Telegram.

Основные свойства:

• Двусторонняя WebSocket-синхронизация: Сообщения и треды с веб-сайта мгновенно реплицируются в Telegram-группу, а ответы из Telegram дублируются на сайт.
• Высокая скорость и лёгкость: Отказ от тяжелых SPA (React/Vue) в пользу чистого Vanilla JS и Server-Side Rendering (SSR) на Jinja2 и FastAPI.
• Поддержка любых медиафайлов: Изображения, видеозаписи, голосовые сообщения, аудиофайлы с отрисовкой осциллограммы (Waveform), "круглые видео" и WebM-стикеры.
• Развитая модерация: Инструменты теневого бана (Shadow Ban), мгновенной очистки постов (Wipe), рассылки системных алеров и стелс-редактирования.
• 20+ встроенных тем: Гибкая CSS-темизация (Cyberpunk, Win95, Lain, Shaft, Nord и др.).

System Overview

• Telegram Bot Daemon: Handles real-time interactions via Telegram.
• Web/API Backend: A FastAPI application managing the web frontend, external API requests, and media uploads.
• Database: A shared SQLite database (dvach_bot.db) acting as the connective tissue between the bot and the backend.

Key Features

• Message Delivery Queue: Ensures safe dispatch of messages respecting rate limits (delivery_manager.py).
• LLM Integrations: Provides persona replies and summarization features (ai_manager.py).
• Automated Image Moderation: Asynchronously hashes and classifies media content (vision.py, tagging_worker.py).
• Full-Text Search: Uses fts5 for robust post searching.

External Integrations

• Telegram Bot API
• Telegram MTProto (pyrogram & tgcrypto)
• Groq API, Gemini API
• Image Hosts: ImgBB, PixHost, Catbox, FreeImage
• Telegraph API