# worksonmyserver/-spanish_fro_ua architecture

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

- Interactive diagram: https://gitdiagram.com/worksonmyserver/-spanish_fro_ua
- Repository: https://github.com/worksonmyserver/-spanish_fro_ua

## Overview

This is a Telegram bot for delivering Spanish-learning lessons, with administrator controls for generation, review, and publishing. The main flow runs from admin actions or scheduled jobs through lesson generation and persistence, then scheduled publication of vocabulary/audio, quizzes, and evening grammar/text. A separate OpenAI post-generation path is present in the source index but its trigger is not shown. Relationships reflect excerpts and index references; unsampled handler and generator behavior is not inferred.

Main entry points: [`bot/scheduler.py`](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/scheduler.py) (Publishing Scheduler), [`bot/handlers.py`](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/handlers.py) (Admin Controls), [`generator/gemini_pipeline.py`](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/gemini_pipeline.py) (Daily Lesson Generator), [`database/crud.py`](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/crud.py) (Lesson Data Access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_main["Application Startup<br/>[main.py]"]
  node_handlers["Admin Controls<br/>[handlers.py]"]
  node_scheduler["Publishing Scheduler<br/>[scheduler.py]"]
end

subgraph group_content["Lesson Content"]
  node_topics["Topic Catalog<br/>[topics.py]"]
  node_lesson_gen["Daily Lesson Generator<br/>[gemini_pipeline.py]"]
  node_tts["Speech Synthesis<br/>[gemini_pipeline.py]"]
  node_gemini(("Gemini API"))
  node_edge_tts(("Edge TTS Service"))
end

subgraph group_persistence["Lesson Storage"]
  node_session["Database Sessions<br/>[connection.py]"]
  node_crud["Lesson Data Access<br/>[crud.py]"]
  node_models["Learning Data Model<br/>[models.py]"]
  node_mysql[("MySQL Database")]
end

subgraph group_posts["Generated Posts"]
  node_post_gen["Post Generator<br/>[llm_pipeline.py]"]
  node_post_schema["Post Schema<br/>[schemas.py]"]
  node_openai(("OpenAI API"))
end

node_admin(("Administrator"))
node_telegram(("Telegram"))

node_main -->|"initializes database"| node_session
node_main -->|"registers router"| node_handlers
node_main -->|"starts scheduler"| node_scheduler
node_admin -->|"sends commands"| node_handlers
node_handlers -->|"reads and saves lessons"| node_crud
node_handlers -->|"requests generation"| node_lesson_gen
node_handlers -->|"selects topics"| node_topics
node_scheduler -->|"loads and advances lessons"| node_crud
node_scheduler -->|"generates next lesson"| node_lesson_gen
node_scheduler -->|"selects next topic"| node_topics
node_scheduler -->|"publishes lessons"| node_telegram
node_lesson_gen -->|"generates lesson data"| node_gemini
node_lesson_gen -->|"creates lesson audio"| node_tts
node_tts -->|"synthesizes speech"| node_edge_tts
node_lesson_gen -->|"saves generated lesson"| node_crud
node_crud -->|"queries and maps records"| node_models
node_session -->|"creates schema"| node_models
node_session -->|"connects to"| node_mysql
node_post_gen -->|"parses structured output"| node_post_schema
node_post_gen -->|"requests completion"| node_openai
node_post_gen -->|"saves draft post"| node_crud

click node_main "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/main.py"
click node_handlers "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/handlers.py"
click node_scheduler "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/scheduler.py"
click node_topics "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/topics.py"
click node_lesson_gen "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/gemini_pipeline.py"
click node_tts "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/gemini_pipeline.py"
click node_post_gen "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/llm_pipeline.py"
click node_post_schema "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/schemas.py"
click node_session "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/connection.py"
click node_crud "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/crud.py"
click node_models "https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/models.py"

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_main,node_handlers,node_scheduler toneBlue
class node_topics,node_lesson_gen,node_tts,node_gemini,node_edge_tts toneAmber
class node_session,node_crud,node_models,node_mysql toneMint
class node_post_gen,node_post_schema,node_openai toneRose
class node_admin,node_telegram toneIndigo
```

## Components

### Bot Runtime

- [Application Startup](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/main.py): `main.py`
- [Admin Controls](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/handlers.py): `bot/handlers.py`
- [Publishing Scheduler](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/bot/scheduler.py): `bot/scheduler.py`

### Lesson Content

- [Topic Catalog](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/topics.py): `generator/topics.py`
- [Daily Lesson Generator](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/gemini_pipeline.py): `generator/gemini_pipeline.py`
- [Speech Synthesis](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/gemini_pipeline.py): `generator/gemini_pipeline.py`
- **Gemini API**
- **Edge TTS Service**

### Lesson Storage

- [Database Sessions](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/connection.py): `database/connection.py`
- [Lesson Data Access](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/crud.py): `database/crud.py`
- [Learning Data Model](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/database/models.py): `database/models.py`
- **MySQL Database**

### Generated Posts

- [Post Generator](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/llm_pipeline.py): `generator/llm_pipeline.py`
- [Post Schema](https://github.com/worksonmyserver/-spanish_fro_ua/blob/main/generator/schemas.py): `generator/schemas.py`
- **OpenAI API**

### Other components

- **Administrator**
- **Telegram**

## Connections

- Application Startup → Database Sessions: initializes database (evidence: `main.py`)
- Application Startup → Admin Controls: registers router (evidence: `main.py`)
- Application Startup → Publishing Scheduler: starts scheduler (evidence: `main.py`)
- Administrator → Admin Controls: sends commands (evidence: `bot/handlers.py`)
- Admin Controls → Lesson Data Access: reads and saves lessons (evidence: `bot/handlers.py`)
- Admin Controls → Daily Lesson Generator: requests generation (evidence: `bot/handlers.py`)
- Admin Controls → Topic Catalog: selects topics (evidence: `bot/handlers.py`)
- Publishing Scheduler → Lesson Data Access: loads and advances lessons (evidence: `bot/scheduler.py`)
- Publishing Scheduler → Daily Lesson Generator: generates next lesson (evidence: `bot/scheduler.py`)
- Publishing Scheduler → Topic Catalog: selects next topic (evidence: `bot/scheduler.py`)
- Publishing Scheduler → Telegram: publishes lessons (evidence: `bot/scheduler.py`)
- Daily Lesson Generator → Gemini API: generates lesson data (evidence: `generator/gemini_pipeline.py`)
- Daily Lesson Generator → Speech Synthesis: creates lesson audio (evidence: `generator/gemini_pipeline.py`)
- Speech Synthesis → Edge TTS Service: synthesizes speech (evidence: `generator/gemini_pipeline.py`)
- Daily Lesson Generator → Lesson Data Access: saves generated lesson (evidence: `generator/gemini_pipeline.py`)
- Lesson Data Access → Learning Data Model: queries and maps records (evidence: `database/crud.py`)
- Database Sessions → Learning Data Model: creates schema (evidence: `database/connection.py`)
- Database Sessions → MySQL Database: connects to (evidence: `database/connection.py`)
- Post Generator → Post Schema: parses structured output (evidence: `generator/llm_pipeline.py`)
- Post Generator → OpenAI API: requests completion (evidence: `generator/llm_pipeline.py`)
- Post Generator → Lesson Data Access: saves draft post (evidence: `generator/llm_pipeline.py`)
