managarten/services/telegram-project-doc-bot/CLAUDE.md

Telegram Project Doc Bot

Telegram Bot zum Sammeln von Projektdokumentation (Fotos, Sprachnotizen, Text) und automatischer Blogbeitrag-Generierung.

Tech Stack

• Framework: NestJS 10
• Telegram: nestjs-telegraf + Telegraf
• Database: PostgreSQL + Drizzle ORM
• Storage: S3 (MinIO lokal, Hetzner in Produktion)
• AI - Transcription: OpenAI Whisper
• AI - Generation: Ollama (lokal) oder OpenAI GPT

Commands

# Development
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

# Database
pnpm db:generate      # Generate migrations
pnpm db:push          # Push schema to database
pnpm db:studio        # Open Drizzle Studio

Telegram 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

# Server
PORT=3302

# Telegram
TELEGRAM_BOT_TOKEN=xxx              # Bot Token von @BotFather
TELEGRAM_ALLOWED_USERS=123,456      # Optional: Nur diese User IDs erlauben

# 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 (optional, aber empfohlen)
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                   # Entry point
│   ├── app.module.ts             # Root module
│   ├── health.controller.ts      # Health endpoint
│   ├── config/
│   │   └── configuration.ts      # Config + Blog-Stile
│   ├── database/
│   │   ├── database.module.ts    # Drizzle connection
│   │   └── schema.ts             # DB schema
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── bot.update.ts         # Command handlers
│   ├── project/
│   │   ├── project.module.ts
│   │   └── project.service.ts    # Projekt CRUD
│   ├── media/
│   │   ├── media.module.ts
│   │   ├── media.service.ts      # Foto/Voice/Text verarbeiten
│   │   └── storage.service.ts    # S3 Upload/Download
│   ├── transcription/
│   │   ├── transcription.module.ts
│   │   └── transcription.service.ts  # Whisper API
│   └── generation/
│       ├── generation.module.ts
│       └── generation.service.ts # Blogpost AI
├── drizzle/                      # Migrations
├── drizzle.config.ts
├── package.json
└── Dockerfile

Lokale Entwicklung

1. Bot bei Telegram erstellen

1. Öffne @BotFather in Telegram
2. Sende /newbot
3. Wähle einen Namen (z.B. "Project Doc Bot")
4. Wähle einen Username (z.B. "my_projectdoc_bot")
5. Kopiere den Token

2. Umgebung vorbereiten

# Docker Services starten (PostgreSQL, MinIO, Ollama)
pnpm docker:up

# Datenbank erstellen
psql -h localhost -U postgres -c "CREATE DATABASE projectdoc;"

# Schema pushen
cd services/telegram-project-doc-bot
cp .env.example .env
# Token und Keys eintragen
pnpm db:push

3. Bot starten

pnpm start:dev

Features

• Multi-Projekt: Mehrere Projekte pro User
• Foto-Speicherung: Fotos in S3 mit Metadaten
• Voice-Transkription: Automatisch via Whisper
• Text-Notizen: Einfache Nachrichten werden gespeichert
• Chronologisch: Alle Einträge behalten ihre Reihenfolge
• Mehrere Stile: casual, formal, tutorial, diary
• Export: Markdown-Datei zum Download

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

Health Check

curl http://localhost:3302/health

Deployment

Docker (empfohlen)

# docker-compose.yml
telegram-project-doc-bot:
  build: ./services/telegram-project-doc-bot
  restart: always
  environment:
    PORT: 3302
    TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
    DATABASE_URL: ${DATABASE_URL}
    S3_ENDPOINT: ${S3_ENDPOINT}
    S3_ACCESS_KEY: ${S3_ACCESS_KEY}
    S3_SECRET_KEY: ${S3_SECRET_KEY}
    S3_BUCKET: projectdoc-storage
    LLM_PROVIDER: ollama
    OLLAMA_URL: http://ollama:11434
  ports:
    - "3302:3302"

Roadmap

• Foto-Vision-Analyse (was ist auf dem Bild?)
• PDF-Export
• Bilder im Blogpost einbetten
• Projekt-Templates
• Web-Dashboard zur Ansicht
• Telegram Mini App für bessere UX