# sudoanxu/automated-story-engine architecture

> Architecture diagram of the GitHub repository sudoanxu/automated-story-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sudoanxu/automated-story-engine
- Repository: https://github.com/sudoanxu/automated-story-engine

## Overview

##### Project type and purpose
- This is a Python-based, CLI-driven “Automated Story Engine” prototype.
- It ingests user story concepts and orchestrates AI services to produce multimodal narratives (text, images, audio, HTML).

##### File structure
- Top-level scripts:
- interactive_story_creator.py – CLI interface guiding questions.
- main_public.py – programmatic entry point (StoryEngineApp).
- setup_env.py – environment/API key setup.
- Core package: story_engine/
- core/ – models.py (data classes), orchestrator.py (main controller), prompt_builder.py.
- generators/ – image_generator.py, audio_generator.py.
- assemblers/ – story_compiler.py (assembles scenes into JSON/HTML/audio/video).
- Output directories:
- generated_stories/ – final story artifacts.
- examples/ – sample input JSON and expected output.
- Config: config.example.yaml, REQUIREMENTS and setup scripts.

##### Key README insights
- Uses OpenAI, Anthropic, Google AI for text and DALL-E for images.
- MoviePy optional for video.
- Asynchronous calls (asyncio example in README).
- Modular, extensible prototype.

##### Main components
a. User Interfaces
- CLI: interactive_story_creator.py
- Programmatic API: StoryEngineApp in main_public.py
b. Core Engine
- Orchestrator – central coordinator calling prompt_builder, generators, and assembler
- Prompt Builder – constructs provider-specific prompts from StoryConcept
- Data Models – StoryConcept, Scene, etc.
c. Generators
- Text generation – OpenAI/Anthropic/Google AI (external REST/gRPC)
- Image generation – OpenAI DALL-E
- Audio generation – OpenAI TTS or fallback providers
d. Assemblers
- Story Compiler – combines text, images, audio into JSON, HTML viewer, video (optional via MoviePy)
e. Persistence & Outputs
- File System – generated_stories/[title]/
- JSON, HTML, .mp3, .json package files
f. Configuration & Secrets
- config.yaml or env vars set by setup_env.py
g. External Services
- OpenAI API
- Anthropic Claude API
- Google Gemini API
- (Optional) MoviePy library for video

##### Relationships & data flow
- User → CLI/API → Orchestrator
- Orchestrator → Prompt Builder → AI Service(s) → receives text outputs
- Orchestrator → Generators (image/audio) → AI Service(s) → receives media outputs
- Orchestrator → Assembler → writes files to generated_stories/
- Orchestrator reports success/failure back to user

##### Architectural patterns & design principles
- Orchestrator as Facade/Controller for modular services
- Separation of concerns: core logic, generation, assembly
- Asynchronous I/O for parallel calls to AI services
- Configurable pluggable providers (OpenAI, Anthropic, Google)
- Extensible: new generators or assemblers can be added under story_engine/

##### Detailed elements to capture
- Entry points (interactive_story_creator.py / main_public.py)
- Core orchestrator calling sub-components
- Prompt construction phase
- Parallel text, image, audio generation
- Story compilation phase producing JSON/HTML/audio/video
- Configuration loading and environment setup
- Error/fallback paths (e.g., provider fallback strategies in orchestrator)

- The modular structure of the prototype
- Flow of data from user concept through AI services to final files
- Key technology dependencies and extensibility points
- Clear demarcation of internal vs. external components

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        CLI["CLI Interface"]:::internal
        API["Programmatic API"]:::internal
    end

    subgraph "Configuration & Setup"
        Env["Env & Config Setup"]:::internal
        ConfigEx["Configuration Example"]:::internal
    end

    subgraph "Core Engine"
        Orch["Orchestrator"]:::internal
        Prompt["Prompt Builder"]:::internal
        Models["Data Models"]:::internal
    end

    subgraph "Generators"
        TextGen["Text Generator"]:::internal
        ImgGen["Image Generator"]:::internal
        AudioGen["Audio Generator"]:::internal
    end

    subgraph "Assemblers"
        Compiler["Story Compiler"]:::internal
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
        Google["Google API"]:::external
    end

    subgraph "Persistence & Examples"
        Output["Generated Stories"]:::storage
        Examples["Sample Input Examples"]:::storage
    end

    %% Connections
    CLI -->|start|Orch
    API -->|start|Orch
    Orch -->|load config|Env
    Env -->|reads|ConfigEx
    Orch -->|uses|Models
    Orch -->|construct prompts|Prompt
    Prompt -->|returns prompts|Orch
    Orch -->|parallel calls|TextGen
    Orch -->|parallel calls|ImgGen
    Orch -->|parallel calls|AudioGen
    TextGen -->|HTTP REST|OpenAI
    TextGen -->|HTTP REST|Anthropic
    TextGen -->|HTTP REST|Google
    ImgGen -->|HTTP REST|OpenAI
    AudioGen -->|HTTP REST|OpenAI
    Orch -->|compiles outputs|Compiler
    Compiler -->|writes files|Output
    Examples -->|sample input|Orch

    %% Click Events
    click CLI "https://github.com/sudoanxu/automated-story-engine/blob/master/interactive_story_creator.py"
    click API "https://github.com/sudoanxu/automated-story-engine/blob/master/main_public.py"
    click Env "https://github.com/sudoanxu/automated-story-engine/blob/master/setup_env.py"
    click ConfigEx "https://github.com/sudoanxu/automated-story-engine/blob/master/config.example.yaml"
    click Orch "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/core/orchestrator.py"
    click Prompt "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/core/prompt_builder.py"
    click Models "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/core/models.py"
    click ImgGen "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/generators/image_generator.py"
    click AudioGen "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/generators/audio_generator.py"
    click Compiler "https://github.com/sudoanxu/automated-story-engine/blob/master/story_engine/assemblers/story_compiler.py"
    click Examples "https://github.com/sudoanxu/automated-story-engine/blob/master/examples/sample_romance_story.json"
    click Output "https://github.com/sudoanxu/automated-story-engine/tree/master/generated_stories/"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085;
    classDef external fill:#d4edda,stroke:#155724,color:#155724;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
