# nkmohit/fableforgeai-storyengine architecture

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

- Interactive diagram: https://gitdiagram.com/nkmohit/fableforgeai-storyengine
- Repository: https://github.com/nkmohit/fableforgeai-storyengine

## Overview

##### Project type and purpose
- From the README and file‐tree, this is a full-stack, single-repo Python application serving a Streamlit-based front end and integrating with external AI services (Google Gemini, Hugging Face).
- Purpose: an AI-powered story-engine and chatbot platform that lets users generate text stories, comic videos, audio narration, grammar-checks, translations, etc.

##### File structure
- Top level:
- main.py        → Streamlit application entrypoint (UI router + controllers)
- gemini_utility.py → Helper module encapsulating all calls to Google Gemini API
- install.py     → Automated installer and environment-bootstrapper
- requirements.txt→ Dependency list
- UPGRADE_GUIDE.md→ Migration notes (deployment concerns)
- README.md      → Project overview and usage instructions
- No separate “frontend” or “backend” directories—UI and business logic cohabit under main.py, calls broken out into gemini_utility.py.

##### README for additional insights
- Tech stack: Python 3.9+, Streamlit UI, google-generativeai SDK for Gemini, python-dotenv, Hugging Face REST API for audio, Pillow, NumPy.
- Workflow: Users interact via web UI → Streamlit routes to feature handlers → handlers call gemini_utility or other HTTP clients → responses streamed back to UI.

a. Main components
- Client Browser (end-user)
- Streamlit App (main.py)
– UI Components: ChatBot, Story Generator, Comic Video Generator, AI Assistant
– Controller/Router
- Business Logic Modules
– gemini_utility.py (Gemini API wrapper)
– Audio module (calls Hugging Face via requests)
- Configuration Store
– .env file (API keys for Google Gemini & Hugging Face)
- External Services
– Google Gemini API
– Hugging Face TTS API
b. Component relationships & data flow
1. User → (HTTP/WebSocket) → Streamlit UI
2. Streamlit UI → internal controller → appropriate feature handler
3. Handler → gemini_utility → Google Gemini → back to handler
4. Handler → Audio module → Hugging Face → back to handler
5. Handler → UI streaming response → User
6. install.py (one-time) reads/writes .env, installs dependencies
c. Architectural patterns and design principles
- Modular feature separation (UI vs. API wrapper)
- Single process, event-driven web application (Streamlit)
- External service integration layer (gemini_utility)
- Configuration decoupling via environment variables
d. Key technologies & libraries
- Streamlit (UI framework)
- google-generativeai (Gemini SDK)
- requests (Hugging Face REST)
- python-dotenv (.env config)
- Pillow, NumPy (image preprocessing, media handling)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["Client Browser"]:::user

    %% Streamlit App Layer
    subgraph "Streamlit App\n(main.py)" 
        direction TB
        UI["UI Components & Controllers"]:::internal
        UI -->|“generate story/chat request”| Handlers["Feature Handlers:\nChatBot, StoryGen,\nComicGen, AI Assistant"]:::internal
    end

    %% Business Logic Layer
    Handlers -->|"calls"| GeminiUtil["Google Gemini API Wrapper\n(gemini_utility.py)"]:::internal
    Handlers -->|"calls"| AudioModule["Audio Module (Hugging Face TTS)"]:::internal

    %% External Services Layer
    GeminiUtil -->|“API Request/Response”| GeminiAPI["Google Gemini API"]:::external
    AudioModule -->|“TTS Request/Response”| HFAPI["Hugging Face TTS API"]:::external

    %% Configuration Store
    Env[".env Configuration"]:::config
    UI -.->|reads| Env
    GeminiUtil -.->|reads| Env
    AudioModule -.->|reads| Env

    %% DevOps Setup
    subgraph "DevOps Setup"
        direction TB
        Installer["Installer / Env Bootstrapper\n(install.py)"]:::internal
    end
    Installer -->|“one-time setup”| Env
    Installer -->|“install deps”| Req["requirements.txt"]:::docs

    %% Documentation
    Docs["README.md"]:::docs
    UPG["UPGRADE_GUIDE.md"]:::docs

    %% Data Flow from User
    User --> UI
    UI -->|“stream response”| User

    %% Click Events
    click UI "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/main.py"
    click GeminiUtil "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/gemini_utility.py"
    click Installer "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/install.py"
    click Req "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/requirements.txt"
    click Docs "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/README.md"
    click UPG "https://github.com/nkmohit/fableforgeai-storyengine/blob/main/UPGRADE_GUIDE.md"

    %% Styles
    classDef internal fill:#add8e6,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef docs fill:#e0e0e0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef user fill:#d3d3d3,stroke:#333,stroke-width:1px,shape:circle
```
