# raunov/bedtime-storyteller architecture

> Architecture diagram of the GitHub repository raunov/bedtime-storyteller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raunov/bedtime-storyteller
- Repository: https://github.com/raunov/bedtime-storyteller

## Overview

##### Project Type and Purpose
- This is a small full-stack web application built with Streamlit (app.py) that generates personalized bedtime stories using AI language models.
- It integrates with three external AI services (OpenAI/GPT-4, Anthropic/Claude, Google/Gemini) and stores usage statistics in a Supabase database.
- Static assets (images) and a translations.json file support a multilingual UI.

##### File Structure
- Top level:
- app.py – the single Streamlit application entry point (UI + orchestrator)
- create_table.sql – DDL for the Supabase table
- render.yaml – (presumably CI/CD or deployment config)
- requirements.txt – Python dependencies
- translations.json – UI text for different languages
- Directories:
- .streamlit/config.toml – secret keys for APIs & Supabase
- static/images – any image assets
- No separate “frontend” or “backend” folders—Streamlit handles both.

##### Extract Key Architecture Insights from the README
- The app:
- Presents a web UI for user inputs (language, child details, values, rating)
- Sends prompts to one of three AI model providers, receives the story
- Persists usage stats and ratings to Supabase
- Is configurable via .streamlit/secrets.toml

##### Main Components
a. User’s Browser (Streamlit front-end UI)
b. Streamlit Application (app.py)
– UI layer: widgets, form inputs, static assets, translations loader
– Business logic: prompt builder, story‐generation workflow, feedback collector
c. External AI Model APIs
– OpenAI GPT-4
– Anthropic Claude
– Google Gemini
d. Supabase Database (PostgreSQL instance)
– Stories table (usage statistics and ratings)
e. Configuration Store
– .streamlit/secrets.toml for API keys & database credentials

##### Relationships and Data Flows
- User → (HTTP) → Streamlit UI
- Streamlit UI → Business Logic → External AI API (over HTTPS)
- AI API → returns generated story → Business Logic
- Business Logic → writes/reads → Supabase (via Supabase REST/SDK)
- User → rates story → Business Logic → Supabase
- Streamlit → reads translations.json for UI strings

##### Architectural Patterns and Design Principles
- Monolithic application pattern (single Python process)
- Clear separation of concerns within the code: UI, orchestration, data persistence
- External service integration pattern (all AI calls are HTTP REST clients)
- Configuration-as-code for secrets and environment (Streamlit secrets)
- CI/CD or deployment described by render.yaml (pointing at a hosted service)

##### Detail
- Every external dependency (three AI providers + database).
- Translations.json file as a distinct asset loader.
- Don’t collapse all AI calls into one—show them individually to reflect real network dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User"
        User["Browser (User)"]:::user
    end

    subgraph "Streamlit Application"
        App["Streamlit Application"]:::streamlit
        UI["UI Module (Widgets & Forms)"]:::streamlit
        Logic["Business Logic\n(Prompt Builder & Workflow)"]:::streamlit
        Translations["Translations Loader"]:::streamlit
        StaticAssets["Static Assets (Images)"]:::streamlit
        Config["Configuration Store"]:::config
    end

    subgraph "AI Model Providers"
        OpenAI["OpenAI GPT-4"]:::external
        Anthropic["Anthropic Claude"]:::external
        Google["Google Gemini"]:::external
    end

    DB["Supabase Database\n(Stories Table)"]:::db

    subgraph "Project Artifacts"
        Deploy["Deployment Config\n(render.yaml)"]:::config
        Requirements["Python Dependencies\n(requirements.txt)"]:::config
        README["Project Docs\n(README.md)"]:::config
        DDL["Supabase Schema DDL\n(create_table.sql)"]:::config
    end

    User -->|"HTTP Request"| App
    App -->|"renders UI"| UI
    App -->|"orchestrates"| Logic
    UI -->|"loads strings"| Translations
    UI -->|"loads images"| StaticAssets
    App -.->|"loads secrets"| Config
    Logic -->|"POST prompt (HTTPS)"| OpenAI
    Logic -->|"POST prompt (HTTPS)"| Anthropic
    Logic -->|"POST prompt (HTTPS)"| Google
    OpenAI -->|"story response"| Logic
    Anthropic -->|"story response"| Logic
    Google -->|"story response"| Logic
    Logic -->|"INSERT/SELECT (Supabase SDK)"| DB
    DDL -.-> DB

    click App "https://github.com/raunov/bedtime-storyteller/blob/main/app.py"
    click Config "https://github.com/raunov/bedtime-storyteller/blob/main/.streamlit/config.toml"
    click Translations "https://github.com/raunov/bedtime-storyteller/blob/main/translations.json"
    click StaticAssets "https://github.com/raunov/bedtime-storyteller/tree/main/static/images/"
    click DDL "https://github.com/raunov/bedtime-storyteller/blob/main/create_table.sql"
    click Deploy "https://github.com/raunov/bedtime-storyteller/blob/main/render.yaml"
    click Requirements "https://github.com/raunov/bedtime-storyteller/blob/main/requirements.txt"
    click README "https://github.com/raunov/bedtime-storyteller/blob/main/README.md"

    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef streamlit fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef db fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
