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

Telegram NutriPhi Bot

Telegram Bot für NutriPhi - KI-gestützte Ernährungsanalyse per Foto oder Text.

Tech Stack

• Framework: NestJS 10
• Telegram: nestjs-telegraf + Telegraf
• Database: PostgreSQL + Drizzle ORM
• AI: Google Gemini 2.0 Flash

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
/hilfe	Hilfe anzeigen
/heute	Heutige Mahlzeiten & Fortschritt
/woche	Wochenstatistik
/ziele	Ziele anzeigen
/ziele [kcal] [P] [K] [F]	Ziele setzen
/favorit [Name]	Letzte Mahlzeit speichern
/favoriten	Gespeicherte Mahlzeiten anzeigen
/essen [Nr]	Favorit als Mahlzeit eintragen
/delfav [Nr]	Favorit löschen
/loeschen	Letzte Mahlzeit löschen
Foto senden	Automatische Analyse
Text senden	Automatische Analyse

User Flow

1. /start                        → Willkommen
2. 📷 Foto einer Mahlzeit senden → Nährwertanalyse
3. /favorit Morgenmüsli          → Als Favorit speichern
4. /heute                        → Tagesübersicht
5. /ziele 2000 100 200 70        → Ziele setzen
6. /woche                        → Wochenstatistik

Environment Variables

# Server
PORT=3303

# Telegram
TELEGRAM_BOT_TOKEN=xxx              # Bot Token von @BotFather
TELEGRAM_ALLOWED_USERS=             # Optional: Komma-separierte User IDs

# Database
DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/nutriphi_bot

# AI
GEMINI_API_KEY=xxx                  # Google AI Studio API Key

Projekt-Struktur

services/telegram-nutriphi-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
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── bot.update.ts         # Command handlers
│   ├── analysis/
│   │   ├── analysis.module.ts
│   │   └── gemini.service.ts     # Gemini AI Integration
│   ├── meals/
│   │   ├── meals.module.ts
│   │   └── meals.service.ts      # Mahlzeiten CRUD
│   ├── goals/
│   │   ├── goals.module.ts
│   │   └── goals.service.ts      # Nutzerziele
│   └── stats/
│       ├── stats.module.ts
│       └── stats.service.ts      # Statistiken
├── drizzle/                      # Migrations
├── drizzle.config.ts
├── package.json
└── .env.example

Lokale Entwicklung

1. Bot bei Telegram erstellen

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

2. Gemini API Key holen

1. Gehe zu https://aistudio.google.com/apikey
2. Erstelle einen API Key
3. Kopiere den Key

3. Umgebung vorbereiten

# Docker Services starten (PostgreSQL)
pnpm docker:up

# Datenbank erstellen
psql -h localhost -U manacore -d postgres -c "CREATE DATABASE nutriphi_bot;"

# In das Verzeichnis wechseln
cd services/telegram-nutriphi-bot

# .env erstellen
cp .env.example .env
# Token und API Key eintragen

# Schema pushen
pnpm db:push

4. Bot starten

pnpm start:dev

Features

• Foto-Analyse: Mahlzeit fotografieren → Gemini analysiert → Nährwerte
• Text-Analyse: Mahlzeit beschreiben → Gemini schätzt → Nährwerte
• Tages-Tracking: Alle Mahlzeiten speichern, Tagesübersicht
• Wochenstatistik: 7-Tage-Übersicht mit Durchschnittswerten
• Ziele: Kalorienziel und Makros setzen
• Favoriten: Häufige Mahlzeiten speichern und wiederverwenden
• Fortschrittsanzeige: Visuelle Balken für Zielerreichung

Datenbank-Schema

user_goals
├── id (UUID)
├── telegram_user_id (BIGINT, unique)
├── daily_calories (INT, default 2000)
├── daily_protein (INT, default 50)
├── daily_carbs (INT, default 250)
├── daily_fat (INT, default 65)
├── daily_fiber (INT, default 30)
├── created_at, updated_at

meals
├── id (UUID)
├── telegram_user_id (BIGINT)
├── date (DATE)
├── meal_type (TEXT: breakfast/lunch/dinner/snack)
├── input_type (TEXT: photo/text)
├── description (TEXT)
├── calories (INT)
├── protein, carbohydrates, fat, fiber, sugar (REAL)
├── confidence (REAL, 0-1)
├── raw_response (JSONB)
├── created_at

favorite_meals
├── id (UUID)
├── telegram_user_id (BIGINT)
├── name (TEXT)
├── description (TEXT)
├── nutrition (JSONB)
├── usage_count (INT)
├── created_at

Health Check

curl http://localhost:3303/health

Gemini Integration

Der Bot verwendet Gemini 2.0 Flash für:

1. Foto-Analyse

   • Erkennt alle sichtbaren Lebensmittel
   • Schätzt Portionsgrößen
   • Berechnet Nährwerte pro Lebensmittel
   • Summiert Gesamtnährwerte

2. Text-Analyse

   • Interpretiert Mahlzeitbeschreibungen
   • Schätzt realistische Portionsgrößen
   • Berechnet Nährwerte

Response-Format:

{
  "foods": [
    {"name": "Spaghetti", "quantity": "200g", "calories": 314, "confidence": 0.9},
    {"name": "Bolognese-Sauce", "quantity": "150g", "calories": 180, "confidence": 0.85}
  ],
  "totalNutrition": {
    "calories": 494,
    "protein": 22,
    "carbohydrates": 65,
    "fat": 15,
    "fiber": 4,
    "sugar": 8
  },
  "description": "Spaghetti Bolognese",
  "confidence": 0.87
}

Beispiel-Ausgaben

Foto-Analyse:

🍽️ Spaghetti Bolognese mit Parmesan

Erkannt:
• Spaghetti (200g)
• Bolognese-Sauce (150g)
• Parmesan (20g)

Nährwerte:
Kalorien: 580 kcal
Protein: 28g
Kohlenhydrate: 68g
Fett: 20g
Ballaststoffe: 5g
Zucker: 8g

Genauigkeit: 87%

Als Favorit speichern: /favorit [Name]

Tagesübersicht (/heute):

📊 Heute (28.01.2026)

1. Frühstück (08:15)
   Haferflocken mit Banane und Milch
   420 kcal

2. Mittagessen (12:30)
   Spaghetti Bolognese
   580 kcal

─────────────────
Gesamt: 1000 kcal

Fortschritt:
Kalorien: ████████░░ 50%
Protein: ██████░░░░ 60%
Kohlenhydr.: ███████░░░ 70%
Fett: █████░░░░░ 50%

Verbleibend: 1000 kcal

Roadmap

• Mahlzeit-Typ manuell wählen
• Foto-Beschreibung als Caption
• Mehrere Fotos pro Mahlzeit
• Export als CSV/JSON
• Erinnerungen für Mahlzeiten
• Wassertracking