# giandomanc/ai-nutritionist architecture

> Architecture diagram of the GitHub repository giandomanc/ai-nutritionist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giandomanc/ai-nutritionist
- Repository: https://github.com/giandomanc/ai-nutritionist

## Overview

This is an API-only Next.js Telegram nutrition bot. Telegram updates enter the webhook and are dispatched through Telegraf middleware to onboarding, profile, meal, and general-message handlers. The main user workflow collects a profile, interprets text or voice as a meal/advice/day-analysis command, then replies with estimates or analysis; meal confirmation and recent advice are session state. Source excerpts show key calls, while some subsystem links rely on the SOURCE INDEX; unsampled features are not expanded beyond documented or indexed evidence.

Main entry points: [`bot/bot.ts`](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/bot.ts) (Bot dispatcher), [`bot/handlers/userMessage.ts`](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/userMessage.ts) (Message handler), [`services/daily-analysis.service.ts`](https://github.com/giandomanc/ai-nutritionist/blob/main/services/daily-analysis.service.ts) (Daily analysis), [`services/ai/command.service.ts`](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/command.service.ts) (Command parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Webhook and bot"]
  node_webhook["Webhook route<br/>[route.ts]"]
  node_bot["Bot dispatcher<br/>[bot.ts]"]
end

subgraph group_conversation["User interaction"]
  node_profile_mw["User middleware<br/>[loadUser.ts]"]
  node_onboarding["Profile onboarding<br/>[onboarding.ts]"]
  node_start["Start handler<br/>[start.ts]"]
  node_profile["Profile handler<br/>[profile.ts]"]
  node_meal_handler["Meal interactions<br/>[meal.ts]"]
  node_message_handler["Message handler<br/>[userMessage.ts]"]
  node_session["Advice session<br/>[advice-session.ts]"]
  node_voice["Voice transcription"]
  node_analysis_reply["Analysis reply"]
end

subgraph group_nutrition["Nutrition services"]
  node_daily["Daily analysis"]
  node_meal_records["Meal records"]
end

subgraph group_ai["AI services"]
  node_command["Command parsing<br/>[command.service.ts]"]
  node_meal_parser["Meal parsing"]
  node_coach["AI coaching<br/>[coach.service.ts]"]
  node_audio_ai["Audio AI<br/>[audio.service.ts]"]
  node_groq["Groq client<br/>[groq.client.ts]"]
  node_ai_support["AI prompts and schemas<br/>[prompts.ts]"]
  node_ai_json["JSON extraction<br/>[json.ts]"]
  node_ai_types["AI data types<br/>[types.ts]"]
end

subgraph group_persistence["State and storage"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_database[("PostgreSQL")]
  node_date["Date utilities<br/>[date.ts]"]
end

node_telegram(("Telegram user"))

node_telegram -->|"sends updates"| node_webhook
node_webhook -->|"forwards updates"| node_bot
node_bot -->|"runs middleware"| node_profile_mw
node_bot -->|"registers handler"| node_onboarding
node_bot -->|"registers handler"| node_start
node_bot -->|"registers handler"| node_profile
node_bot -->|"registers handler"| node_meal_handler
node_bot -->|"registers handler"| node_message_handler
node_profile_mw -->|"loads user"| node_prisma
node_onboarding -->|"creates profile"| node_prisma
node_message_handler -->|"parses message"| node_command
node_message_handler -->|"transcribes voice"| node_voice
node_message_handler -->|"uses advice state"| node_session
node_message_handler -->|"requests analysis reply"| node_analysis_reply
node_message_handler -->|"requests food advice"| node_daily
node_message_handler -->|"saves meal items"| node_meal_records
node_meal_handler -->|"uses meal services"| node_meal_records
node_voice -->|"transcribes audio"| node_audio_ai
node_analysis_reply -->|"requests analysis"| node_daily
node_command -->|"parses meal"| node_meal_parser
node_command -->|"classifies command"| node_groq
node_command -->|"uses prompt and schema"| node_ai_support
node_command -->|"extracts JSON"| node_ai_json
node_meal_parser -->|"requests completion"| node_groq
node_meal_parser -->|"uses prompt and schema"| node_ai_support
node_meal_parser -->|"extracts JSON"| node_ai_json
node_coach -->|"generates response"| node_groq
node_coach -->|"uses prompts"| node_ai_support
node_audio_ai -->|"transcribes audio"| node_groq
node_daily -->|"reads today's meals"| node_prisma
node_daily -->|"gets day boundary"| node_date
node_daily -->|"generates analysis"| node_coach
node_daily -->|"builds analysis prompts"| node_ai_support
node_meal_records -->|"persists meals"| node_prisma
node_meal_records -->|"uses date boundary"| node_date
node_prisma -->|"connects to"| node_database

click node_webhook "https://github.com/giandomanc/ai-nutritionist/blob/main/app/api/telegram/route.ts"
click node_bot "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/bot.ts"
click node_profile_mw "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/middleware/loadUser.ts"
click node_onboarding "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/onboarding.ts"
click node_start "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/start.ts"
click node_profile "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/profile.ts"
click node_meal_handler "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/meal.ts"
click node_message_handler "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/userMessage.ts"
click node_session "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/session/advice-session.ts"
click node_voice "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/utils/transcribeTelegramVoice.ts"
click node_analysis_reply "https://github.com/giandomanc/ai-nutritionist/blob/main/bot/utils/replyWithTodayAnalysis.ts"
click node_command "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/command.service.ts"
click node_meal_parser "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/meal-parser.service.ts"
click node_coach "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/coach.service.ts"
click node_audio_ai "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/audio.service.ts"
click node_groq "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/groq.client.ts"
click node_ai_support "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/prompts.ts"
click node_ai_json "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/json.ts"
click node_ai_types "https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/types.ts"
click node_daily "https://github.com/giandomanc/ai-nutritionist/blob/main/services/daily-analysis.service.ts"
click node_meal_records "https://github.com/giandomanc/ai-nutritionist/blob/main/services/meals/meal-record.service.ts"
click node_prisma "https://github.com/giandomanc/ai-nutritionist/blob/main/lib/prisma.ts"
click node_date "https://github.com/giandomanc/ai-nutritionist/blob/main/lib/date.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webhook,node_bot,node_telegram toneBlue
class node_profile_mw,node_onboarding,node_start,node_profile,node_meal_handler,node_message_handler,node_session,node_voice,node_analysis_reply toneAmber
class node_daily,node_meal_records toneMint
class node_command,node_meal_parser,node_coach,node_audio_ai,node_groq,node_ai_support,node_ai_json,node_ai_types toneRose
class node_prisma,node_database,node_date toneIndigo
```

## Components

### Webhook and bot

- [Webhook route](https://github.com/giandomanc/ai-nutritionist/blob/main/app/api/telegram/route.ts): `app/api/telegram/route.ts`
- [Bot dispatcher](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/bot.ts): `bot/bot.ts`

### User interaction

- [User middleware](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/middleware/loadUser.ts): `bot/middleware/loadUser.ts`
- [Profile onboarding](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/onboarding.ts): `bot/handlers/onboarding.ts`
- [Start handler](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/start.ts): `bot/handlers/start.ts`
- [Profile handler](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/profile.ts): `bot/handlers/profile.ts`
- [Meal interactions](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/meal.ts): `bot/handlers/meal.ts`
- [Message handler](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/handlers/userMessage.ts): `bot/handlers/userMessage.ts`
- [Advice session](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/session/advice-session.ts): `bot/session/advice-session.ts`
- [Voice transcription](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/utils/transcribeTelegramVoice.ts): `bot/utils/transcribeTelegramVoice.ts`
- [Analysis reply](https://github.com/giandomanc/ai-nutritionist/blob/main/bot/utils/replyWithTodayAnalysis.ts): `bot/utils/replyWithTodayAnalysis.ts`

### Nutrition services

- [Daily analysis](https://github.com/giandomanc/ai-nutritionist/blob/main/services/daily-analysis.service.ts): `services/daily-analysis.service.ts`
- [Meal records](https://github.com/giandomanc/ai-nutritionist/blob/main/services/meals/meal-record.service.ts): `services/meals/meal-record.service.ts`

### AI services

- [Command parsing](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/command.service.ts): `services/ai/command.service.ts`
- [Meal parsing](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/meal-parser.service.ts): `services/ai/meal-parser.service.ts`
- [AI coaching](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/coach.service.ts): `services/ai/coach.service.ts`
- [Audio AI](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/audio.service.ts): `services/ai/audio.service.ts`
- [Groq client](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/groq.client.ts): `services/ai/groq.client.ts`
- [AI prompts and schemas](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/prompts.ts): `services/ai/prompts.ts`
- [JSON extraction](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/json.ts): `services/ai/json.ts`
- [AI data types](https://github.com/giandomanc/ai-nutritionist/blob/main/services/ai/types.ts): `services/ai/types.ts`

### State and storage

- [Prisma client](https://github.com/giandomanc/ai-nutritionist/blob/main/lib/prisma.ts): `lib/prisma.ts`
- **PostgreSQL**
- [Date utilities](https://github.com/giandomanc/ai-nutritionist/blob/main/lib/date.ts): `lib/date.ts`

### Other components

- **Telegram user**

## Connections

- Telegram user → Webhook route: sends updates (evidence: `README.md`)
- Webhook route → Bot dispatcher: forwards updates (evidence: `app/api/telegram/route.ts`)
- Bot dispatcher → User middleware: runs middleware (evidence: `bot/bot.ts`)
- Bot dispatcher → Profile onboarding: registers handler (evidence: `bot/bot.ts`)
- Bot dispatcher → Start handler: registers handler (evidence: `bot/bot.ts`)
- Bot dispatcher → Profile handler: registers handler (evidence: `bot/bot.ts`)
- Bot dispatcher → Meal interactions: registers handler (evidence: `bot/bot.ts`)
- Bot dispatcher → Message handler: registers handler (evidence: `bot/bot.ts`)
- User middleware → Prisma client: loads user (evidence: `bot/middleware/loadUser.ts`)
- Profile onboarding → Prisma client: creates profile (evidence: `bot/handlers/onboarding.ts`)
- Message handler → Command parsing: parses message (evidence: `bot/handlers/userMessage.ts`)
- Message handler → Voice transcription: transcribes voice (evidence: `bot/handlers/userMessage.ts`)
- Message handler → Advice session: uses advice state (evidence: `bot/handlers/userMessage.ts`)
- Message handler → Analysis reply: requests analysis reply (evidence: `bot/handlers/userMessage.ts`)
- Message handler → Daily analysis: requests food advice (evidence: `bot/handlers/userMessage.ts`)
- Message handler → Meal records: saves meal items (evidence: `bot/handlers/userMessage.ts`)
- Meal interactions → Meal records: uses meal services (evidence: `bot/handlers/meal.ts`)
- Voice transcription → Audio AI: transcribes audio (evidence: `bot/utils/transcribeTelegramVoice.ts`)
- Analysis reply → Daily analysis: requests analysis (evidence: `bot/utils/replyWithTodayAnalysis.ts`)
- Command parsing → Meal parsing: parses meal (evidence: `services/ai/command.service.ts`)
- Command parsing → Groq client: classifies command (evidence: `services/ai/command.service.ts`)
- Command parsing → AI prompts and schemas: uses prompt and schema (evidence: `services/ai/command.service.ts`)
- Command parsing → JSON extraction: extracts JSON (evidence: `services/ai/command.service.ts`)
- Meal parsing → Groq client: requests completion (evidence: `services/ai/meal-parser.service.ts`)
- Meal parsing → AI prompts and schemas: uses prompt and schema (evidence: `services/ai/meal-parser.service.ts`)
- Meal parsing → JSON extraction: extracts JSON (evidence: `services/ai/meal-parser.service.ts`)
- AI coaching → Groq client: generates response (evidence: `services/ai/coach.service.ts`)
- AI coaching → AI prompts and schemas: uses prompts (evidence: `services/ai/coach.service.ts`)
- Audio AI → Groq client: transcribes audio (evidence: `services/ai/audio.service.ts`)
- Daily analysis → Prisma client: reads today's meals (evidence: `services/daily-analysis.service.ts`)
- Daily analysis → Date utilities: gets day boundary (evidence: `services/daily-analysis.service.ts`)
- Daily analysis → AI coaching: generates analysis (evidence: `services/daily-analysis.service.ts`)
- Daily analysis → AI prompts and schemas: builds analysis prompts (evidence: `services/daily-analysis.service.ts`)
- Meal records → Prisma client: persists meals (evidence: `services/meals/meal-record.service.ts`)
- Meal records → Date utilities: uses date boundary (evidence: `services/meals/meal-record.service.ts`)
- Prisma client → PostgreSQL: connects to (evidence: `lib/prisma.ts`)
