managarten/services/telegram-todo-bot/CLAUDE.md

Telegram Todo Bot

Telegram Bot fuer Todo - Aufgabenverwaltung via Telegram.

Tech Stack

• Framework: NestJS 10
• Telegram: nestjs-telegraf + Telegraf
• Database: PostgreSQL + Drizzle ORM
• Scheduler: @nestjs/schedule
• API Client: Calls Todo Backend (localhost:3018)

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	Willkommensnachricht
/help	Hilfe anzeigen
/login	Account verknuepfen
/logout	Account trennen
/add [Text]	Neue Aufgabe erstellen
/inbox	Inbox-Aufgaben anzeigen
/today	Heutige Aufgaben
/list	Alle offenen Aufgaben
/done [Nr]	Aufgabe als erledigt markieren
/projects	Projekte anzeigen
/remind	Taegliche Erinnerung an/aus

User Flow

1. /start                        → Willkommen
2. /login                        → Email eingeben
3. [Email eingeben]              → Passwort eingeben
4. [Passwort eingeben]           → Account verknuepft
5. /today                        → Heutige Aufgaben
6. /add Einkaufen                → Aufgabe erstellt
7. /done 1                       → Aufgabe erledigt
8. /remind                       → Taegliche Erinnerung aktivieren

Architecture

Der Bot verwendet einen API-Client Ansatz:

• Bot hat eigene DB fuer Telegram User ↔ Todo User Mapping
• Ruft Todo Backend REST API auf fuer Task-Operationen
• Kein direkter DB-Zugriff auf Todo-Datenbank

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Telegram  │────>│  Todo Bot       │────>│  Todo Backend   │
│   User      │     │  (port 3304)    │     │  (port 3018)    │
└─────────────┘     └─────────────────┘     └─────────────────┘
                           │                        │
                           │ Bot DB (user mapping)  │ Todo DB (tasks)
                           ▼                        ▼
                    ┌─────────────┐          ┌─────────────┐
                    │  todo_bot   │          │    todo     │
                    │  (PG DB)    │          │   (PG DB)   │
                    └─────────────┘          └─────────────┘

Environment Variables

# Server
PORT=3304

# Telegram
TELEGRAM_BOT_TOKEN=xxx              # Bot Token von @BotFather

# Database (Bot's own database)
DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/todo_bot

# Todo Backend API
TODO_API_URL=http://localhost:3018

# Mana Core Auth
MANA_CORE_AUTH_URL=http://localhost:3001

Projekt-Struktur

services/telegram-todo-bot/
├── src/
│   ├── main.ts                   # Entry point
│   ├── app.module.ts             # Root module
│   ├── health.controller.ts      # Health endpoint
│   ├── config/
│   │   └── configuration.ts      # Config
│   ├── database/
│   │   ├── database.module.ts    # Drizzle connection
│   │   └── schema.ts             # DB schema (user mapping)
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── bot.update.ts         # Command handlers
│   ├── todo-client/
│   │   ├── todo-client.module.ts
│   │   ├── todo-client.service.ts # Todo API wrapper
│   │   └── types.ts              # TypeScript interfaces
│   ├── user/
│   │   ├── user.module.ts
│   │   └── user.service.ts       # Account linking, settings
│   └── scheduler/
│       ├── scheduler.module.ts
│       └── reminder.scheduler.ts # Cron fuer 08:00 Uhr
├── drizzle/                      # Migrations
├── drizzle.config.ts
├── package.json
└── .env.example

Lokale Entwicklung

1. Bot bei Telegram erstellen

1. Oeffne @BotFather in Telegram
2. Sende /newbot
3. Waehle einen Namen (z.B. "Todo Bot")
4. Waehle einen Username (z.B. "mana_todo_bot")
5. Kopiere den Token

2. Umgebung vorbereiten

# Docker Services starten (PostgreSQL)
pnpm docker:up

# Datenbank erstellen und Schema pushen
pnpm dev:todo-bot:full

3. Bot starten

# Nur Bot starten (DB muss existieren)
pnpm dev:todo-bot

Features

• Account-Verknuepfung: Login via Email/Passwort
• Aufgaben erstellen: Schnell neue Aufgaben anlegen
• Aufgaben anzeigen: Inbox, Today, alle offenen
• Aufgaben erledigen: Per Nummer abhaken
• Projekte: Projektliste anzeigen
• Taegliche Erinnerung: Automatisch um 08:00 Uhr

Datenbank-Schema

telegram_users
├── id (UUID)
├── telegram_user_id (BIGINT, unique)
├── telegram_username (TEXT)
├── mana_user_id (TEXT)              # Verknuepfter Todo-User
├── access_token (TEXT)              # JWT fuer API-Calls
├── refresh_token (TEXT)
├── token_expires_at (TIMESTAMP)
├── daily_reminder_enabled (BOOLEAN)
├── daily_reminder_time (TEXT, default '08:00')
├── timezone (TEXT, default 'Europe/Berlin')
├── created_at, updated_at

Health Check

curl http://localhost:3304/health

MVP Features (Phase 1)

• /start, /help
• /login, /logout - Account-Verknuepfung
• /add [text] - Aufgabe in Inbox erstellen
• /today - Heutige Aufgaben
• /inbox - Inbox-Aufgaben
• /list - Alle offenen Aufgaben
• /done [Nr] - Abhaken
• /projects - Projektliste
• /remind - Taegliche Erinnerung

Spaetere Features (Phase 2)

• /add @projekt [text] - Aufgabe in Projekt
• /due [Nr] [Datum] - Faelligkeitsdatum setzen
• /priority [Nr] [hoch/mittel/niedrig]
• Inline-Buttons fuer schnelle Aktionen
• OAuth-basiertes Login (statt Email/Passwort)