# arpit-26/smart-cultural-storyteller architecture

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

- Interactive diagram: https://gitdiagram.com/arpit-26/smart-cultural-storyteller
- Repository: https://github.com/arpit-26/smart-cultural-storyteller

## Overview

Smart Cultural Storyteller is a Streamlit/Flask application for generating culturally themed stories, narration, imagery, and videos. The main workflow runs from user selections in the interface through Flask API orchestration, story generation and optional Hindi translation, then audio and image generation; video requests combine those assets into a video. Cultural facts, theme/language options, and regional-accent narration are supporting capabilities. The graph follows README statements and shown excerpts; some API internals and integrations are only partially sampled, so uncertain links are omitted.

Main entry points: [`app.py`](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/app.py) (Flask API), [`frontend/streamlit_app.py`](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/frontend/streamlit_app.py) (Streamlit UI), [`models/story_generator.py`](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/story_generator.py) (Local Story Model), [`models/image_generator.py`](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/image_generator.py) (Scene Imagery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_web_ui["Streamlit UI<br/>[streamlit_app.py]"]
end

subgraph group_api["API Orchestration"]
  node_api_server["Flask API<br/>[app.py]"]
end

subgraph group_stories["Story Content"]
  node_story_logic["Cultural Logic<br/>[storyteller.py]"]
  node_story_model["Local Story Model<br/>[story_generator.py]"]
  node_hindi_translation["Hindi Translation<br/>[story_generator.py]"]
end

subgraph group_media["Media Generation"]
  node_image_scenes["Scene Imagery<br/>[image_generator.py]"]
  node_audio_narration["Audio Narration<br/>[storyteller.py]"]
  node_video_workflow["Video Workflow<br/>[video_creator.py]"]
  node_video_compiler["Video Compiler<br/>[video_compiler.py]"]
end

node_user(("Storyteller"))
node_elevenlabs{{"ElevenLabs"}}
node_pollinations{{"Pollinations.ai"}}
node_translation_service{{"Google Translate"}}
node_ffmpeg{{"FFmpeg"}}

node_user -->|"selects story"| node_web_ui
node_web_ui -->|"requests stories"| node_api_server
node_api_server -->|"requests cultural content"| node_story_logic
node_api_server -->|"generates story"| node_story_model
node_api_server -->|"translates story"| node_hindi_translation
node_story_model -->|"translates text"| node_translation_service
node_api_server -->|"requests imagery"| node_image_scenes
node_api_server -->|"requests narration"| node_audio_narration
node_audio_narration -->|"generates speech"| node_elevenlabs
node_image_scenes -->|"generates images"| node_pollinations
node_api_server -->|"creates video"| node_video_workflow
node_video_workflow -->|"delegates compilation"| node_video_compiler
node_video_compiler -->|"encodes video"| node_ffmpeg

click node_web_ui "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/frontend/streamlit_app.py"
click node_api_server "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/app.py"
click node_story_logic "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/storyteller.py"
click node_story_model "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/story_generator.py"
click node_hindi_translation "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/story_generator.py"
click node_image_scenes "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/image_generator.py"
click node_audio_narration "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/storyteller.py"
click node_video_workflow "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/video_creator.py"
click node_video_compiler "https://github.com/arpit-26/smart-cultural-storyteller/blob/main/video_compiler.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_web_ui toneBlue
class node_api_server toneAmber
class node_story_logic,node_story_model,node_hindi_translation toneMint
class node_image_scenes,node_audio_narration,node_video_workflow,node_video_compiler toneRose
class node_user,node_elevenlabs,node_pollinations,node_translation_service,node_ffmpeg toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/frontend/streamlit_app.py): `frontend/streamlit_app.py`

### API Orchestration

- [Flask API](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/app.py): `app.py`

### Story Content

- [Cultural Logic](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/storyteller.py): `storyteller.py`
- [Local Story Model](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/story_generator.py): `models/story_generator.py`
- [Hindi Translation](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/story_generator.py): `models/story_generator.py`

### Media Generation

- [Scene Imagery](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/models/image_generator.py): `models/image_generator.py`
- [Audio Narration](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/storyteller.py): `storyteller.py`
- [Video Workflow](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/video_creator.py): `video_creator.py`
- [Video Compiler](https://github.com/arpit-26/smart-cultural-storyteller/blob/main/video_compiler.py): `video_compiler.py`

### Other components

- **Storyteller**
- **ElevenLabs**
- **Pollinations.ai**
- **Google Translate**
- **FFmpeg**

## Connections

- Storyteller → Streamlit UI: selects story (evidence: `README.md`)
- Streamlit UI → Flask API: requests stories (evidence: `frontend/streamlit_app.py`)
- Flask API → Cultural Logic: requests cultural content (evidence: `app.py`)
- Flask API → Local Story Model: generates story (evidence: `app.py`)
- Flask API → Hindi Translation: translates story (evidence: `app.py`)
- Local Story Model → Google Translate: translates text (evidence: `models/story_generator.py`)
- Flask API → Scene Imagery: requests imagery (evidence: `app.py`)
- Flask API → Audio Narration: requests narration (evidence: `app.py`)
- Audio Narration → ElevenLabs: generates speech (evidence: `storyteller.py`)
- Scene Imagery → Pollinations.ai: generates images (evidence: `models/image_generator.py`)
- Flask API → Video Workflow: creates video (evidence: `app.py`)
- Video Workflow → Video Compiler: delegates compilation (evidence: `video_creator.py`)
- Video Compiler → FFmpeg: encodes video (evidence: `video_compiler.py`)
