How raunov/bedtime-storyteller works
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.