# madhoor/ai-story-engine architecture

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

- Interactive diagram: https://gitdiagram.com/madhoor/ai-story-engine
- Repository: https://github.com/madhoor/ai-story-engine

## Overview

AI-Story-Engine generates several story candidates, reviews them, selects the highest-scoring result, saves it, and synthesizes audio. The editor is a separate, currently inactive rewrite option. The README is empty, so the map follows the sampled runtime code; prompt files are shown as inputs, and no unsampled behavior is assumed.

Main entry points: [`main.py`](https://github.com/madhoor/ai-story-engine/blob/main/main.py) (Workflow runner), [`app/critic.py`](https://github.com/madhoor/ai-story-engine/blob/main/app/critic.py) (Story critic), [`app/editor.py`](https://github.com/madhoor/ai-story-engine/blob/main/app/editor.py) (Story editor), [`app/llm.py`](https://github.com/madhoor/ai-story-engine/blob/main/app/llm.py) (Story generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Story workflow"]
  node_runner["Workflow runner<br/>[main.py]"]
  node_critic["Story critic<br/>[critic.py]"]
  node_editor["Story editor<br/>[editor.py]"]
  node_storyfiles[("Saved stories")]
end

subgraph group_language["Language generation"]
  node_storymaker["Story generator<br/>[llm.py]"]
  node_ollama{{"Ollama API"}}
end

subgraph group_speech["Speech output"]
  node_tts["Voice synthesizer<br/>[tts.py]"]
  node_kokoro{{"Kokoro TTS"}}
  node_audiofiles["Audio files"]
end

subgraph group_settings["Prompts and settings"]
  node_storyprompt["Story prompt<br/>[story_prompt.txt]"]
  node_criticprompt["Critic prompt<br/>[critic_prompt.txt]"]
  node_editorprompt["Editor prompt<br/>[editor_prompt.txt]"]
  node_config["Model settings<br/>[config.py]"]
end

node_user(("User"))

node_user -->|"starts"| node_runner
node_runner -->|"generates candidates"| node_storymaker
node_runner -->|"reviews candidates"| node_critic
node_runner -->|"saves winner"| node_storyfiles
node_runner -->|"synthesizes winner"| node_tts
node_runner -.->|"may rewrite"| node_editor
node_storymaker -->|"loads prompt"| node_storyprompt
node_critic -->|"loads prompt"| node_criticprompt
node_editor -->|"loads prompt"| node_editorprompt
node_storymaker -->|"reads settings"| node_config
node_critic -->|"reads settings"| node_config
node_editor -->|"reads settings"| node_config
node_storymaker -->|"requests generation"| node_ollama
node_critic -->|"requests review"| node_ollama
node_editor -->|"requests rewrite"| node_ollama
node_tts -->|"runs synthesis"| node_kokoro
node_tts -->|"writes audio"| node_audiofiles

click node_runner "https://github.com/madhoor/ai-story-engine/blob/main/main.py"
click node_critic "https://github.com/madhoor/ai-story-engine/blob/main/app/critic.py"
click node_editor "https://github.com/madhoor/ai-story-engine/blob/main/app/editor.py"
click node_storymaker "https://github.com/madhoor/ai-story-engine/blob/main/app/llm.py"
click node_storyprompt "https://github.com/madhoor/ai-story-engine/blob/main/prompts/story_prompt.txt"
click node_criticprompt "https://github.com/madhoor/ai-story-engine/blob/main/prompts/critic_prompt.txt"
click node_editorprompt "https://github.com/madhoor/ai-story-engine/blob/main/prompts/editor_prompt.txt"
click node_config "https://github.com/madhoor/ai-story-engine/blob/main/app/config.py"
click node_tts "https://github.com/madhoor/ai-story-engine/blob/main/app/tts.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_runner,node_critic,node_editor,node_storyfiles,node_user toneBlue
class node_storymaker,node_ollama toneAmber
class node_tts,node_kokoro,node_audiofiles toneMint
class node_storyprompt,node_criticprompt,node_editorprompt,node_config toneRose
```

## Components

### Story workflow

- [Workflow runner](https://github.com/madhoor/ai-story-engine/blob/main/main.py): `main.py`
- [Story critic](https://github.com/madhoor/ai-story-engine/blob/main/app/critic.py): `app/critic.py`
- [Story editor](https://github.com/madhoor/ai-story-engine/blob/main/app/editor.py): `app/editor.py`
- **Saved stories**

### Language generation

- [Story generator](https://github.com/madhoor/ai-story-engine/blob/main/app/llm.py): `app/llm.py`
- **Ollama API**

### Speech output

- [Voice synthesizer](https://github.com/madhoor/ai-story-engine/blob/main/app/tts.py): `app/tts.py`
- **Kokoro TTS**
- **Audio files**

### Prompts and settings

- [Story prompt](https://github.com/madhoor/ai-story-engine/blob/main/prompts/story_prompt.txt): `prompts/story_prompt.txt`
- [Critic prompt](https://github.com/madhoor/ai-story-engine/blob/main/prompts/critic_prompt.txt): `prompts/critic_prompt.txt`
- [Editor prompt](https://github.com/madhoor/ai-story-engine/blob/main/prompts/editor_prompt.txt): `prompts/editor_prompt.txt`
- [Model settings](https://github.com/madhoor/ai-story-engine/blob/main/app/config.py): `app/config.py`

### Other components

- **User**

## Connections

- User → Workflow runner: starts (evidence: `main.py`)
- Workflow runner → Story generator: generates candidates (evidence: `main.py`)
- Workflow runner → Story critic: reviews candidates (evidence: `main.py`)
- Workflow runner → Saved stories: saves winner (evidence: `main.py`)
- Workflow runner → Voice synthesizer: synthesizes winner (evidence: `main.py`)
- Workflow runner → Story editor: may rewrite (evidence: `main.py`)
- Story generator → Story prompt: loads prompt (evidence: `app/llm.py`)
- Story critic → Critic prompt: loads prompt (evidence: `app/critic.py`)
- Story editor → Editor prompt: loads prompt (evidence: `app/editor.py`)
- Story generator → Model settings: reads settings (evidence: `app/llm.py`)
- Story critic → Model settings: reads settings (evidence: `app/critic.py`)
- Story editor → Model settings: reads settings (evidence: `app/editor.py`)
- Story generator → Ollama API: requests generation (evidence: `app/llm.py`)
- Story critic → Ollama API: requests review (evidence: `app/critic.py`)
- Story editor → Ollama API: requests rewrite (evidence: `app/editor.py`)
- Voice synthesizer → Kokoro TTS: runs synthesis (evidence: `app/tts.py`)
- Voice synthesizer → Audio files: writes audio (evidence: `app/tts.py`)