From 48c5ff31dc6b9bd6c287dfa2673d204fa59925e4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Jan 2026 19:22:40 +0000
Subject: [PATCH] docs: add unified Telegram bots documentation

- Document all 3 existing bots (stats, ollama, project-doc)
- Include common architecture, environment variables, and deployment
- Add comprehensive plan for telegram-calendar-bot
- Cover features, commands, database schema, and message formatters

https://claude.ai/code/session_01LwmhvhKpEsvVtY1ZKhYu6f
---
 docs/TELEGRAM_BOTS.md | 724 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 724 insertions(+)
 create mode 100644 docs/TELEGRAM_BOTS.md

diff --git a/docs/TELEGRAM_BOTS.md b/docs/TELEGRAM_BOTS.md
new file mode 100644
index 000000000..7bb3c3145
--- /dev/null
+++ b/docs/TELEGRAM_BOTS.md
@@ -0,0 +1,724 @@
+# Telegram Bots
+
+Dokumentation aller Telegram-Bots im ManaCore Monorepo.
+
+## Übersicht
+
+| Bot | Port | Zweck | Status |
+|-----|------|-------|--------|
+| [telegram-stats-bot](#telegram-stats-bot) | 3300 | Analytics & Statistiken von Umami | ✅ Aktiv |
+| [telegram-ollama-bot](#telegram-ollama-bot) | 3301 | Lokale LLM-Inferenz via Ollama | ✅ Aktiv |
+| [telegram-project-doc-bot](#telegram-project-doc-bot) | 3302 | Projektdokumentation & Blogpost-Generierung | ✅ Aktiv |
+| [telegram-calendar-bot](#telegram-calendar-bot) | 3303 | Kalender-Termine & Erinnerungen | 📋 Geplant |
+
+## Gemeinsame Architektur
+
+Alle Bots teilen dieselbe technische Basis:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Telegram Bot Service                                       │
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │  NestJS 10  │  │  Telegraf   │  │  nestjs-telegraf    │ │
+│  │  Framework  │  │  Library    │  │  Integration        │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Standard Module Structure                          │   │
+│  │  ├── src/main.ts              # Entry point         │   │
+│  │  ├── src/app.module.ts        # Root module         │   │
+│  │  ├── src/health.controller.ts # /health endpoint    │   │
+│  │  ├── src/config/              # Configuration       │   │
+│  │  └── src/bot/                 # Bot commands        │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Gemeinsame Features
+
+- **Health Endpoint**: Alle Bots haben `/health` für Monitoring
+- **User-Beschränkung**: Optional via `TELEGRAM_ALLOWED_USERS`
+- **Docker Support**: Dockerfile für Container-Deployment
+- **Graceful Shutdown**: Sauberes Beenden bei SIGTERM
+
+### Standard Environment Variables
+
+```env
+# Alle Bots
+PORT=33xx                           # Port für Health-Endpoint
+TELEGRAM_BOT_TOKEN=xxx              # Bot Token von @BotFather
+TELEGRAM_ALLOWED_USERS=123,456      # Optional: Erlaubte User IDs
+NODE_ENV=production                 # Environment
+```
+
+---
+
+## telegram-stats-bot
+
+**Zweck:** Liefert Analytics und Statistiken von Umami (stats.mana.how) via Telegram.
+
+### Features
+
+- Übersicht aller App-Statistiken (30 Tage)
+- Tägliche und wöchentliche Reports
+- Echtzeit-Besucherzahlen
+- Registrierte User-Statistiken
+- Automatische geplante Reports
+
+### Commands
+
+| Command | Beschreibung |
+|---------|--------------|
+| `/start` | Hilfe anzeigen |
+| `/stats` | Übersicht aller Apps (letzte 30 Tage) |
+| `/today` | Heutige Statistiken |
+| `/week` | Wochenstatistiken |
+| `/realtime` | Aktive Besucher jetzt |
+| `/users` | Registrierte User-Statistiken |
+| `/help` | Verfügbare Commands anzeigen |
+
+### Scheduled Reports
+
+| Report | Schedule | Timezone |
+|--------|----------|----------|
+| Täglich | 09:00 | Europe/Berlin |
+| Wöchentlich | Montag 09:00 | Europe/Berlin |
+
+### Environment Variables
+
+```env
+PORT=3300
+TZ=Europe/Berlin
+
+# Telegram
+TELEGRAM_BOT_TOKEN=xxx
+TELEGRAM_CHAT_ID=xxx              # Chat für automatische Reports
+
+# Umami
+UMAMI_API_URL=http://umami:3000
+UMAMI_USERNAME=admin
+UMAMI_PASSWORD=xxx
+
+# Database (optional, für User-Counts)
+DATABASE_URL=postgresql://...
+```
+
+### Projekt-Struktur
+
+```
+services/telegram-stats-bot/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── health.controller.ts
+│   ├── config/
+│   │   └── configuration.ts      # Website IDs
+│   ├── bot/
+│   │   ├── bot.module.ts
+│   │   ├── bot.service.ts        # Send messages
+│   │   └── bot.update.ts         # Command handlers
+│   ├── umami/
+│   │   └── umami.service.ts      # Umami API client
+│   ├── analytics/
+│   │   ├── analytics.service.ts  # Data aggregation
+│   │   └── formatters.ts         # Message formatters
+│   ├── users/
+│   │   └── users.service.ts      # User count from auth DB
+│   └── scheduler/
+│       └── report.scheduler.ts   # Cron jobs
+└── Dockerfile
+```
+
+### Neue Website hinzufügen
+
+In `src/config/configuration.ts`:
+
+```typescript
+export const WEBSITE_IDS: Record<string, string> = {
+  'new-app-webapp': 'uuid-from-umami',
+};
+
+export const DISPLAY_NAMES: Record<string, string> = {
+  'new-app-webapp': 'New App',
+};
+```
+
+---
+
+## telegram-ollama-bot
+
+**Zweck:** Lokale LLM-Inferenz via Ollama auf dem Mac Mini Server.
+
+### Features
+
+- Chat mit lokalem LLM (Gemma 3 4B Standard)
+- Mehrere Konversations-Modi
+- Dynamischer Modell-Wechsel
+- Chat-Verlauf (10 Nachrichten Kontext)
+- Automatisches Message-Splitting bei langen Antworten
+
+### Commands
+
+| Command | Beschreibung |
+|---------|--------------|
+| `/start` | Hilfe anzeigen |
+| `/help` | Hilfe anzeigen |
+| `/models` | Verfügbare Modelle auflisten |
+| `/model [name]` | Modell wechseln |
+| `/mode [modus]` | System-Prompt ändern |
+| `/clear` | Chat-Verlauf löschen |
+| `/status` | Ollama-Status prüfen |
+
+### Modi
+
+| Modus | Beschreibung |
+|-------|--------------|
+| `default` | Allgemeiner Assistent |
+| `classify` | Text-Klassifizierung |
+| `summarize` | Zusammenfassungen |
+| `translate` | Übersetzungen |
+| `code` | Programmier-Hilfe |
+
+### Environment Variables
+
+```env
+PORT=3301
+
+# Telegram
+TELEGRAM_BOT_TOKEN=xxx
+TELEGRAM_ALLOWED_USERS=123,456    # Optional
+
+# Ollama
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=gemma3:4b
+OLLAMA_TIMEOUT=120000             # Timeout in ms
+```
+
+### Projekt-Struktur
+
+```
+services/telegram-ollama-bot/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── health.controller.ts
+│   ├── config/
+│   │   └── configuration.ts      # System Prompts
+│   ├── bot/
+│   │   ├── bot.module.ts
+│   │   └── bot.update.ts         # Command handlers
+│   └── ollama/
+│       ├── ollama.module.ts
+│       └── ollama.service.ts     # Ollama API client
+└── Dockerfile
+```
+
+### Deployment
+
+**Option 1: Docker**
+```yaml
+telegram-ollama-bot:
+  image: ghcr.io/memo-2023/telegram-ollama-bot:latest
+  environment:
+    TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
+    OLLAMA_URL: http://host.docker.internal:11434
+```
+
+**Option 2: Nativ (empfohlen für Performance)**
+```bash
+cd ~/projects/manacore-monorepo/services/telegram-ollama-bot
+pnpm build
+TELEGRAM_BOT_TOKEN=xxx pnpm start:prod
+```
+
+---
+
+## telegram-project-doc-bot
+
+**Zweck:** Sammelt Projektdokumentation (Fotos, Sprachnotizen, Text) und generiert automatisch Blogbeiträge.
+
+### Features
+
+- Multi-Projekt-Verwaltung
+- Foto-Speicherung in S3
+- Automatische Voice-Transkription (Whisper)
+- Text-Notizen
+- AI-Blogpost-Generierung (mehrere Stile)
+- Markdown-Export
+
+### Commands
+
+| Command | Beschreibung |
+|---------|--------------|
+| `/start` | Hilfe anzeigen |
+| `/help` | Hilfe anzeigen |
+| `/new [Name]` | Neues Projekt erstellen |
+| `/projects` | Alle Projekte auflisten |
+| `/switch [ID]` | Projekt wechseln |
+| `/status` | Status des aktiven Projekts |
+| `/archive` | Projekt archivieren |
+| `/generate` | Blogbeitrag generieren |
+| `/generate [Stil]` | Mit bestimmtem Stil generieren |
+| `/styles` | Verfügbare Stile anzeigen |
+| `/export` | Letzte Generierung als Datei |
+
+### Blog-Stile
+
+| Stil | Beschreibung |
+|------|--------------|
+| `casual` | Locker & persönlich |
+| `formal` | Professionell & sachlich |
+| `tutorial` | Anleitung mit Schritten |
+| `diary` | Tagebuch-Stil |
+
+### User Flow
+
+```
+1. /new Gartenhaus-Renovierung    → Projekt erstellen
+2. 📷 Foto senden                  → Wird gespeichert
+3. 🎤 Sprachnotiz senden           → Transkribiert + gespeichert
+4. "Heute das Fundament gegossen"  → Text-Notiz
+5. /status                        → Übersicht
+6. /generate tutorial             → Blogbeitrag erstellen
+7. /export                        → Als .md Datei
+```
+
+### Environment Variables
+
+```env
+PORT=3302
+
+# Telegram
+TELEGRAM_BOT_TOKEN=xxx
+TELEGRAM_ALLOWED_USERS=123,456
+
+# Database
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/projectdoc
+
+# Storage (MinIO)
+S3_ENDPOINT=http://localhost:9000
+S3_REGION=us-east-1
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+S3_BUCKET=projectdoc-storage
+
+# AI - Transcription
+OPENAI_API_KEY=sk-xxx
+
+# AI - Generation
+LLM_PROVIDER=ollama               # ollama oder openai
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=gemma3:4b
+```
+
+### Projekt-Struktur
+
+```
+services/telegram-project-doc-bot/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── health.controller.ts
+│   ├── config/
+│   │   └── configuration.ts      # Blog-Stile
+│   ├── database/
+│   │   ├── database.module.ts
+│   │   └── schema.ts             # Drizzle schema
+│   ├── bot/
+│   │   ├── bot.module.ts
+│   │   └── bot.update.ts         # Command handlers
+│   ├── project/
+│   │   └── project.service.ts    # Projekt CRUD
+│   ├── media/
+│   │   ├── media.service.ts      # Foto/Voice/Text
+│   │   └── storage.service.ts    # S3 Upload/Download
+│   ├── transcription/
+│   │   └── transcription.service.ts  # Whisper API
+│   └── generation/
+│       └── generation.service.ts # Blogpost AI
+├── drizzle/
+├── drizzle.config.ts
+└── Dockerfile
+```
+
+### Datenbank-Schema
+
+```
+projects
+├── id (UUID)
+├── telegram_user_id (INT)
+├── name (TEXT)
+├── description (TEXT)
+├── status (TEXT: active, archived, completed)
+├── created_at, updated_at
+
+media_items
+├── id (UUID)
+├── project_id (UUID FK)
+├── type (TEXT: photo, voice, text)
+├── storage_key (TEXT)
+├── caption (TEXT)
+├── transcription (TEXT)
+├── ai_description (TEXT)
+├── metadata (JSONB)
+├── telegram_file_id (TEXT)
+├── order_index (INT)
+├── created_at
+
+generations
+├── id (UUID)
+├── project_id (UUID FK)
+├── style (TEXT)
+├── content (TEXT - Markdown)
+├── pdf_key (TEXT)
+├── is_latest (BOOL)
+├── created_at
+```
+
+---
+
+## telegram-calendar-bot
+
+**Zweck:** Telegram-Integration für die Calendar-App mit Termin-Abfragen, Quick-Add und Erinnerungen.
+
+**Status:** 📋 Geplant
+
+Siehe [Plan](#telegram-calendar-bot-plan) unten für Details.
+
+---
+
+## Entwicklung
+
+### Neuen Bot erstellen
+
+1. **Bot bei Telegram registrieren:**
+   - Öffne @BotFather in Telegram
+   - Sende `/newbot`
+   - Wähle Namen und Username
+   - Kopiere den Token
+
+2. **Service erstellen:**
+   ```bash
+   mkdir -p services/telegram-{name}-bot/src
+   cd services/telegram-{name}-bot
+   pnpm init
+   ```
+
+3. **Dependencies installieren:**
+   ```bash
+   pnpm add @nestjs/core @nestjs/common @nestjs/config nestjs-telegraf telegraf
+   pnpm add -D @types/node typescript
+   ```
+
+4. **Standard-Struktur anlegen:**
+   ```
+   src/
+   ├── main.ts
+   ├── app.module.ts
+   ├── health.controller.ts
+   ├── config/
+   │   └── configuration.ts
+   └── bot/
+       ├── bot.module.ts
+       └── bot.update.ts
+   ```
+
+### Lokale Entwicklung
+
+```bash
+# Bot starten (aus dem Service-Verzeichnis)
+pnpm start:dev
+
+# Health Check testen
+curl http://localhost:33xx/health
+```
+
+### Docker Build
+
+```bash
+# Aus dem Monorepo-Root
+docker build -f services/telegram-{name}-bot/Dockerfile -t telegram-{name}-bot .
+```
+
+---
+
+## Deployment
+
+### Mac Mini Server
+
+Alle Bots laufen auf dem Mac Mini Server. Status prüfen:
+
+```bash
+ssh mana-server
+./scripts/mac-mini/status.sh
+```
+
+### Docker Compose
+
+```yaml
+# docker-compose.macmini.yml
+services:
+  telegram-stats-bot:
+    image: ghcr.io/memo-2023/telegram-stats-bot:latest
+    restart: always
+    ports:
+      - "3300:3300"
+    environment:
+      PORT: 3300
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_STATS_BOT_TOKEN}
+      # ...
+
+  telegram-ollama-bot:
+    image: ghcr.io/memo-2023/telegram-ollama-bot:latest
+    restart: always
+    ports:
+      - "3301:3301"
+    environment:
+      PORT: 3301
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_OLLAMA_BOT_TOKEN}
+      OLLAMA_URL: http://host.docker.internal:11434
+      # ...
+
+  telegram-project-doc-bot:
+    image: ghcr.io/memo-2023/telegram-project-doc-bot:latest
+    restart: always
+    ports:
+      - "3302:3302"
+    environment:
+      PORT: 3302
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_PROJECT_DOC_BOT_TOKEN}
+      # ...
+```
+
+### Health Checks
+
+```bash
+# Alle Bots prüfen
+curl http://localhost:3300/health  # stats-bot
+curl http://localhost:3301/health  # ollama-bot
+curl http://localhost:3302/health  # project-doc-bot
+```
+
+---
+
+## Monitoring
+
+### Telegram Notifications
+
+Bei Fehlern werden Benachrichtigungen via telegram-stats-bot gesendet:
+
+```bash
+# Health Check Script
+./scripts/mac-mini/health-check.sh
+```
+
+### Logs
+
+```bash
+# Docker Logs
+docker logs manacore-telegram-stats-bot -f
+docker logs manacore-telegram-ollama-bot -f
+docker logs manacore-telegram-project-doc-bot -f
+
+# Native Service Logs
+journalctl -u telegram-ollama-bot -f
+```
+
+---
+
+## telegram-calendar-bot Plan
+
+### Übersicht
+
+Ein Telegram-Bot für die Calendar-App, der Termin-Abfragen, Quick-Add und Erinnerungen via Telegram ermöglicht.
+
+### Geplante Commands
+
+| Command | Beschreibung |
+|---------|--------------|
+| `/start` | Hilfe & Account-Verknüpfung |
+| `/help` | Verfügbare Commands |
+| `/today` | Heutige Termine |
+| `/tomorrow` | Morgige Termine |
+| `/week` | Wochenübersicht |
+| `/next [n]` | Nächste n Termine (default: 5) |
+| `/add [text]` | Schnell-Termin via natürliche Sprache |
+| `/calendars` | Kalender-Übersicht |
+| `/remind` | Erinnerungseinstellungen |
+| `/link` | Account verknüpfen |
+| `/unlink` | Account trennen |
+
+### Geplante Features
+
+1. **Termin-Abfragen**
+   - Tägliche/wöchentliche Übersicht
+   - Suche nach Terminen
+   - Kalender-Filter
+
+2. **Quick-Add**
+   - Natürliche Spracheingabe: "Meeting morgen um 14 Uhr"
+   - Strukturiertes Format: `/add Meeting | 2024-12-20 14:00 | 1h`
+   - Kalender-Auswahl
+
+3. **Erinnerungen via Telegram**
+   - Push-Notifications für anstehende Termine
+   - Konfigurierbare Vorlaufzeit
+   - Morgen-Briefing (tägliche Zusammenfassung)
+
+4. **Account-Verknüpfung**
+   - OAuth oder Token-basierte Verknüpfung
+   - Mehrere Telegram-Accounts pro User möglich
+
+### Technische Architektur
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  telegram-calendar-bot (Port 3303)                         │
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │    Bot      │  │   Calendar  │  │    Reminder         │ │
+│  │   Module    │  │   Client    │  │    Scheduler        │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
+│         │                │                    │             │
+│         ▼                ▼                    ▼             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Calendar Backend API (Port 3016)                   │   │
+│  │  GET /api/v1/events?start=...&end=...              │   │
+│  │  POST /api/v1/events                               │   │
+│  │  GET /api/v1/calendars                             │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                           │                                 │
+│                           ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  PostgreSQL (calendar database)                     │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Environment Variables (geplant)
+
+```env
+PORT=3303
+
+# Telegram
+TELEGRAM_BOT_TOKEN=xxx
+TELEGRAM_ALLOWED_USERS=123,456    # Optional
+
+# Calendar Backend
+CALENDAR_API_URL=http://localhost:3016
+MANA_CORE_AUTH_URL=http://localhost:3001
+
+# Database (für User-Verknüpfungen)
+DATABASE_URL=postgresql://...
+
+# Reminder Settings
+REMINDER_CHECK_INTERVAL=60000     # Check every minute
+MORNING_BRIEFING_TIME=07:00       # Daily briefing time
+MORNING_BRIEFING_TIMEZONE=Europe/Berlin
+```
+
+### Projekt-Struktur (geplant)
+
+```
+services/telegram-calendar-bot/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── health.controller.ts
+│   ├── config/
+│   │   └── configuration.ts
+│   ├── database/
+│   │   ├── database.module.ts
+│   │   └── schema.ts             # telegram_users Tabelle
+│   ├── bot/
+│   │   ├── bot.module.ts
+│   │   └── bot.update.ts         # Command handlers
+│   ├── calendar/
+│   │   ├── calendar.module.ts
+│   │   └── calendar.client.ts    # Calendar API client
+│   ├── reminder/
+│   │   ├── reminder.module.ts
+│   │   └── reminder.scheduler.ts # Cron für Erinnerungen
+│   └── nlp/
+│       ├── nlp.module.ts
+│       └── nlp.service.ts        # Natürliche Spracheingabe
+├── drizzle/
+├── drizzle.config.ts
+└── Dockerfile
+```
+
+### Datenbank-Schema (geplant)
+
+```sql
+-- telegram_users: Verknüpfung Telegram <-> ManaCore
+CREATE TABLE telegram_users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  telegram_user_id BIGINT UNIQUE NOT NULL,
+  telegram_username VARCHAR(255),
+  mana_user_id UUID NOT NULL,
+  access_token TEXT,
+  refresh_token TEXT,
+  token_expires_at TIMESTAMP WITH TIME ZONE,
+  settings JSONB DEFAULT '{}',
+  is_active BOOLEAN DEFAULT true,
+  linked_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- telegram_reminder_settings: User-spezifische Einstellungen
+CREATE TABLE telegram_reminder_settings (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  telegram_user_id BIGINT REFERENCES telegram_users(telegram_user_id),
+  default_reminder_minutes INTEGER DEFAULT 15,
+  morning_briefing_enabled BOOLEAN DEFAULT false,
+  morning_briefing_time TIME DEFAULT '07:00',
+  timezone VARCHAR(100) DEFAULT 'Europe/Berlin',
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+### Message Formatters (Beispiele)
+
+**Tagesübersicht:**
+```
+📅 Deine Termine für heute (Mo, 27. Januar)
+
+🔵 09:00 - 10:00 | Team Standup
+   📍 Zoom Meeting
+
+🟢 12:30 - 13:30 | Mittagessen mit Lisa
+   📍 Restaurant Bella
+
+🔴 15:00 - 16:30 | Projekt Review
+   📍 Konferenzraum A
+   📝 Q4 Ergebnisse präsentieren
+
+───────────────
+3 Termine heute
+```
+
+**Quick-Add Bestätigung:**
+```
+✅ Termin erstellt!
+
+📌 Meeting mit Team
+📅 Morgen, 14:00 - 15:00
+📍 Büro
+🗓️ Kalender: Arbeit
+
+/undo zum Rückgängig machen
+```
+
+**Erinnerung:**
+```
+⏰ Erinnerung in 15 Minuten
+
+📌 Team Standup
+⏱️ 09:00 - 10:00
+📍 Zoom Meeting
+
+[Zum Termin] [Verschieben] [Absagen]
+```