# drakollla/recipescribe architecture

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

- Interactive diagram: https://gitdiagram.com/drakollla/recipescribe
- Repository: https://github.com/drakollla/recipescribe

## Overview

RecipeScribe turns video URLs or manually entered recipes into structured, searchable recipes, with a Web UI as the recommended interface and a Telegram bot as an additional client. Video extraction follows the documented fallback sequence: video description, pinned author comments, then yt-dlp audio download and Whisper transcription; LLM parsing structures the result. The API also supports recipe scaling, substitutions, step rewriting, exports, meal planning, and LLM profile management. The graph reflects README capabilities and indexed source references; several implementation paths are unsampled, so uncertain links are omitted.

Main entry points: [`RecipeScribeApi/Controllers/RecipesController.cs`](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/RecipesController.cs) (Recipe endpoints), [`RecipeScribeApi/Program.cs`](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Program.cs) (HTTP API), [`Infrastructure/Services/RecipeExtractorService.cs`](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/RecipeExtractorService.cs) (Extraction coordinator), [`Infrastructure/Database/RecipeRepository.cs`](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/RecipeRepository.cs) (Recipe repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Web API"]
  node_web_ui["Web UI<br/>[app.js]"]
  node_api["HTTP API<br/>[Program.cs]"]
  node_recipe_controller["Recipe endpoints"]
  node_meal_controller["Meal plan endpoints"]
  node_profile_controller["LLM profile endpoints"]
end

subgraph group_telegram["Telegram client"]
  node_telegram_bot["Telegram bot"]
  node_telegram_flows["Bot workflows"]
  node_recipe_client["Recipe API client<br/>[RecipeApiClient.cs]"]
  node_meal_client["Meal plan API client"]
end

subgraph group_extraction["Recipe extraction"]
  node_extractor["Extraction coordinator"]
  node_youtube["YouTube downloader"]
  node_transcriber["Whisper transcriber"]
  node_parser["LLM recipe parser<br/>[RecipeParser.cs]"]
  node_llm["LLM provider<br/>[OpenAiProvider.cs]"]
end

subgraph group_services["Recipe services"]
  node_retry["LLM retry helper<br/>[LlmRetryHelper.cs]"]
  node_meal_service["Meal planning"]
  node_scaling["Recipe scaling<br/>[ScalingService.cs]"]
  node_substitutions["Ingredient substitutions"]
  node_step_rewrite["Step rewriting"]
  node_exporter["Markdown export"]
end

subgraph group_storage["Persistence"]
  node_recipe_repo["Recipe repository"]
  node_meal_repo["Meal plan repository"]
  node_database[("SQLite database<br/>[RecipeDbContext.cs]")]
  node_profiles["LLM profile store<br/>[LlmProfileStore.cs]"]
end

node_web_user(("Web user"))
node_telegram_user(("Telegram user"))
node_youtube_service(("YouTube"))
node_llm_service(("LLM endpoint"))
node_whisper_service(("Whisper"))

node_web_user -->|"uses"| node_web_ui
node_web_ui -->|"calls"| node_api
node_telegram_user -->|"messages"| node_telegram_bot
node_telegram_bot -->|"dispatches"| node_telegram_flows
node_telegram_flows -->|"requests recipes"| node_recipe_client
node_telegram_flows -->|"requests plans"| node_meal_client
node_recipe_client -->|"HTTP requests"| node_api
node_meal_client -->|"HTTP requests"| node_api
node_api -.->|"routes"| node_recipe_controller
node_api -.->|"routes"| node_meal_controller
node_api -.->|"routes"| node_profile_controller
node_recipe_controller -->|"extracts recipes"| node_extractor
node_recipe_controller -->|"reads and saves"| node_recipe_repo
node_recipe_controller -->|"rescales"| node_scaling
node_recipe_controller -->|"gets suggestions"| node_substitutions
node_recipe_controller -->|"rewrites steps"| node_step_rewrite
node_recipe_controller -->|"reads user settings"| node_meal_repo
node_meal_controller -->|"plans meals"| node_meal_service
node_meal_controller -->|"reads recipes"| node_recipe_repo
node_profile_controller -->|"manages profiles"| node_profiles
node_extractor -.->|"downloads audio"| node_youtube
node_extractor -.->|"transcribes audio"| node_transcriber
node_extractor -.->|"structures recipe"| node_parser
node_youtube -.->|"fetches media"| node_youtube_service
node_transcriber -.->|"recognizes speech"| node_whisper_service
node_parser -->|"prompts"| node_llm
node_llm -.->|"sends prompts"| node_llm_service
node_parser -->|"retries calls"| node_retry
node_substitutions -->|"retries calls"| node_retry
node_meal_service -->|"reads and updates"| node_meal_repo
node_meal_service -->|"uses scaling"| node_recipe_repo
node_recipe_repo -->|"queries and saves"| node_database
node_meal_repo -->|"queries and saves"| node_database
node_recipe_controller -.->|"exports markdown"| node_exporter

click node_web_ui "https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/wwwroot/app.js"
click node_api "https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Program.cs"
click node_recipe_controller "https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/RecipesController.cs"
click node_meal_controller "https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/MealPlansController.cs"
click node_profile_controller "https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/LlmProfilesController.cs"
click node_telegram_bot "https://github.com/drakollla/recipescribe/blob/master/TelegramBot/TelegramBotService.cs"
click node_telegram_flows "https://github.com/drakollla/recipescribe/blob/master/TelegramBot/TelegramRecipeFlow.cs"
click node_recipe_client "https://github.com/drakollla/recipescribe/blob/master/TelegramBot/ApiClients/RecipeApiClient.cs"
click node_meal_client "https://github.com/drakollla/recipescribe/blob/master/TelegramBot/ApiClients/MealPlanApiClient.cs"
click node_extractor "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/RecipeExtractorService.cs"
click node_youtube "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/YouTubeDownloader.cs"
click node_transcriber "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/WhisperTranscriber.cs"
click node_parser "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/RecipeParser.cs"
click node_llm "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Providers/OpenAiProvider.cs"
click node_retry "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Helpers/LlmRetryHelper.cs"
click node_meal_service "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/MealPlannerService.cs"
click node_scaling "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/ScalingService.cs"
click node_substitutions "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/LlmSubstitutionService.cs"
click node_step_rewrite "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/StepRewriteService.cs"
click node_exporter "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Exporters/MarkdownRecipeExporter.cs"
click node_recipe_repo "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/RecipeRepository.cs"
click node_meal_repo "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/MealPlanRepository.cs"
click node_database "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/RecipeDbContext.cs"
click node_profiles "https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/LlmProfileStore.cs"

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_web_ui,node_api,node_recipe_controller,node_meal_controller,node_profile_controller,node_web_user,node_telegram_user toneBlue
class node_telegram_bot,node_telegram_flows,node_recipe_client,node_meal_client toneAmber
class node_extractor,node_youtube,node_transcriber,node_parser,node_llm toneMint
class node_retry,node_meal_service,node_scaling,node_substitutions,node_step_rewrite,node_exporter toneRose
class node_recipe_repo,node_meal_repo,node_database,node_profiles,node_youtube_service,node_llm_service,node_whisper_service toneIndigo
```

## Components

### Web API

- [Web UI](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/wwwroot/app.js): `RecipeScribeApi/wwwroot/app.js`
- [HTTP API](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Program.cs): `RecipeScribeApi/Program.cs`
- [Recipe endpoints](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/RecipesController.cs): `RecipeScribeApi/Controllers/RecipesController.cs`
- [Meal plan endpoints](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/MealPlansController.cs): `RecipeScribeApi/Controllers/MealPlansController.cs`
- [LLM profile endpoints](https://github.com/drakollla/recipescribe/blob/master/RecipeScribeApi/Controllers/LlmProfilesController.cs): `RecipeScribeApi/Controllers/LlmProfilesController.cs`

### Telegram client

- [Telegram bot](https://github.com/drakollla/recipescribe/blob/master/TelegramBot/TelegramBotService.cs): `TelegramBot/TelegramBotService.cs`
- [Bot workflows](https://github.com/drakollla/recipescribe/blob/master/TelegramBot/TelegramRecipeFlow.cs): `TelegramBot/TelegramRecipeFlow.cs`
- [Recipe API client](https://github.com/drakollla/recipescribe/blob/master/TelegramBot/ApiClients/RecipeApiClient.cs): `TelegramBot/ApiClients/RecipeApiClient.cs`
- [Meal plan API client](https://github.com/drakollla/recipescribe/blob/master/TelegramBot/ApiClients/MealPlanApiClient.cs): `TelegramBot/ApiClients/MealPlanApiClient.cs`

### Recipe extraction

- [Extraction coordinator](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/RecipeExtractorService.cs): `Infrastructure/Services/RecipeExtractorService.cs`
- [YouTube downloader](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/YouTubeDownloader.cs): `Infrastructure/YouTubeDownloader.cs`
- [Whisper transcriber](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/WhisperTranscriber.cs): `Infrastructure/WhisperTranscriber.cs`
- [LLM recipe parser](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/RecipeParser.cs): `Infrastructure/RecipeParser.cs`
- [LLM provider](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Providers/OpenAiProvider.cs): `Infrastructure/Providers/OpenAiProvider.cs`

### Recipe services

- [LLM retry helper](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Helpers/LlmRetryHelper.cs): `Infrastructure/Helpers/LlmRetryHelper.cs`
- [Meal planning](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/MealPlannerService.cs): `Infrastructure/Services/MealPlannerService.cs`
- [Recipe scaling](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/ScalingService.cs): `Infrastructure/Services/ScalingService.cs`
- [Ingredient substitutions](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/LlmSubstitutionService.cs): `Infrastructure/Services/LlmSubstitutionService.cs`
- [Step rewriting](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/StepRewriteService.cs): `Infrastructure/Services/StepRewriteService.cs`
- [Markdown export](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Exporters/MarkdownRecipeExporter.cs): `Infrastructure/Exporters/MarkdownRecipeExporter.cs`

### Persistence

- [Recipe repository](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/RecipeRepository.cs): `Infrastructure/Database/RecipeRepository.cs`
- [Meal plan repository](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/MealPlanRepository.cs): `Infrastructure/Database/MealPlanRepository.cs`
- [SQLite database](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Database/RecipeDbContext.cs): `Infrastructure/Database/RecipeDbContext.cs`
- [LLM profile store](https://github.com/drakollla/recipescribe/blob/master/Infrastructure/Services/LlmProfileStore.cs): `Infrastructure/Services/LlmProfileStore.cs`

### Other components

- **Web user**
- **Telegram user**
- **YouTube**
- **LLM endpoint**
- **Whisper**

## Connections

- Web user → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP API: calls (evidence: `README.md`)
- Telegram user → Telegram bot: messages (evidence: `README.md`)
- Telegram bot → Bot workflows: dispatches (evidence: `TelegramBot/TelegramBotService.cs`)
- Bot workflows → Recipe API client: requests recipes (evidence: `TelegramBot/Extensions/TgServiceCollectionExtensions.cs`)
- Bot workflows → Meal plan API client: requests plans (evidence: `TelegramBot/Extensions/TgServiceCollectionExtensions.cs`)
- Recipe API client → HTTP API: HTTP requests (evidence: `TelegramBot/ApiClients/RecipeApiClient.cs`)
- Meal plan API client → HTTP API: HTTP requests (evidence: `TelegramBot/ApiClients/MealPlanApiClient.cs`)
- HTTP API → Recipe endpoints: routes
- HTTP API → Meal plan endpoints: routes
- HTTP API → LLM profile endpoints: routes
- Recipe endpoints → Extraction coordinator: extracts recipes (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Recipe endpoints → Recipe repository: reads and saves (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Recipe endpoints → Recipe scaling: rescales (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Recipe endpoints → Ingredient substitutions: gets suggestions (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Recipe endpoints → Step rewriting: rewrites steps (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Recipe endpoints → Meal plan repository: reads user settings (evidence: `RecipeScribeApi/Controllers/RecipesController.cs`)
- Meal plan endpoints → Meal planning: plans meals (evidence: `RecipeScribeApi/Controllers/MealPlansController.cs`)
- Meal plan endpoints → Recipe repository: reads recipes (evidence: `RecipeScribeApi/Controllers/MealPlansController.cs`)
- LLM profile endpoints → LLM profile store: manages profiles (evidence: `RecipeScribeApi/Controllers/LlmProfilesController.cs`)
- Extraction coordinator → YouTube downloader: downloads audio (evidence: `README.md`)
- Extraction coordinator → Whisper transcriber: transcribes audio (evidence: `README.md`)
- Extraction coordinator → LLM recipe parser: structures recipe (evidence: `README.md`)
- YouTube downloader → YouTube: fetches media (evidence: `README.md`)
- Whisper transcriber → Whisper: recognizes speech (evidence: `README.md`)
- LLM recipe parser → LLM provider: prompts (evidence: `Infrastructure/RecipeParser.cs`)
- LLM provider → LLM endpoint: sends prompts
- LLM recipe parser → LLM retry helper: retries calls (evidence: `Infrastructure/RecipeParser.cs`)
- Ingredient substitutions → LLM retry helper: retries calls (evidence: `Infrastructure/Services/LlmSubstitutionService.cs`)
- Meal planning → Meal plan repository: reads and updates (evidence: `Infrastructure/Services/MealPlannerService.cs`)
- Meal planning → Recipe repository: uses scaling (evidence: `Infrastructure/Services/MealPlannerService.cs`)
- Recipe repository → SQLite database: queries and saves (evidence: `Infrastructure/Database/RecipeRepository.cs`)
- Meal plan repository → SQLite database: queries and saves (evidence: `Infrastructure/Database/MealPlanRepository.cs`)
- Recipe endpoints → Markdown export: exports markdown
