# elder-plinius/i-llm architecture

> Architecture diagram of the GitHub repository elder-plinius/i-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elder-plinius/i-llm
- Repository: https://github.com/elder-plinius/i-llm

## Overview

1. **What this repository is**
   - I-LLM is an interactive AI “movie maker” workflow built around Streamlit.
   - The core use case is generating a movie concept, style guide, outline, screenplay, and voice/dialogue assets from user prompts.

2. **Primary runtime entrypoint**
   - `app.py` is the documented main application entrypoint (`streamlit run app.py`).
   - The extra variants (`appv2.py`, `appv3.py`, `appv4.py`, `appdalle.py`, `movie_maker_app.py`) suggest iterative UI/prototype versions rather than separate services.

3. **Presentation layer**
   - The Streamlit app is the user-facing boundary.
   - It likely gathers creative inputs from the user, displays generated text/assets, and coordinates the multi-step creation flow.
   - `screen.md` likely documents or captures the UI/output flow.

4. **Orchestration / workflow layer**
   - `agents.py` is the main sign that the app uses a higher-level orchestration layer rather than calling models directly from the UI.
   - This layer likely sequences tasks such as concept generation, style development, outline writing, script drafting, and dialogue/voice preparation.
   - `prompts.py` appears to hold the prompt templates that define those generation steps.

5. **Text-generation model adapters**
   - `openai_chat.py` is the OpenAI text/chat integration.
   - `gemini_chat.py` is the Google Gemini text-generation integration.
   - These appear to be thin service boundaries that isolate vendor-specific API calls from the rest of the application.

6. **Multimodal / image-related functionality**
   - `openai_vision.py` suggests image understanding or vision-based input handling.
   - `dalle.py` and `appdalle.py` indicate image generation capability, probably for concept art or visual accompaniment.
   - This creates a separate model boundary for image generation/analysis alongside text generation.

7. **Voice and audio synthesis**
   - `speech.py` is the audio/voice layer.
   - `elevenlabs_client.py`, `elevenlabs_library.py`, and `11labslibrary.py` indicate ElevenLabs integration for voice synthesis or voice matching.
   - The README explicitly calls out voice matching and dialogue generation, so audio is a distinct subsystem, not just an afterthought.

8. **Shared utilities and support code**
   - `utils.py` likely contains common helpers used across the app, model wrappers, and generation flows.
   - `requirements.txt` defines the Python dependency boundary for the whole system.
   - `.env.example` shows the app depends on runtime secrets, especially `OPENAI_API_KEY` and `ELEVENLABS_API_KEY`.

9. **External services and dependencies**
   - OpenAI is used for chat/text generation and possibly vision/image-related tasks.
   - Google Gemini is an alternate or complementary text-generation backend.
   - ElevenLabs is the external speech synthesis provider.
   - DALL-E is implied for image generation.
   - These services are the main external architecture boundaries the app integrates with.

10. **Deployment/runtime shape**
   - `Procfile` suggests the project is prepared for a process-based deployment platform such as Heroku or similar.
   - `setup.sh` likely automates local or cloud environment setup.
   - The repository is therefore a Python application with a Streamlit frontend and vendor API integrations, not a traditional multi-service backend.

11. **How data flows through the system**
   - User input enters via Streamlit.
   - The app routes that input through prompt templates and orchestration logic.
   - Model adapter modules call external AI APIs.
   - Generated text, images, or audio are returned to the UI for display or playback.
   - The architecture is centered on “UI → orchestrator → provider adapters → external AI services → UI.”

12. **Architecture diagram boundary summary**
   - Draw one clear application boundary around the Python/Streamlit app.
   - Inside it, show separate subsystems for UI, orchestration/prompts, text models, image/vision, and speech.
   - Outside it, show OpenAI, Gemini, ElevenLabs, and image-generation services as external providers.

Main entry points: [`agents.py`](https://github.com/elder-plinius/i-llm/blob/main/agents.py) (Agents), [`app.py`](https://github.com/elder-plinius/i-llm/blob/main/app.py) (Main app), [`openai_chat.py`](https://github.com/elder-plinius/i-llm/blob/main/openai_chat.py) (OpenAI chat), [`gemini_chat.py`](https://github.com/elder-plinius/i-llm/blob/main/gemini_chat.py) (Gemini chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app_py["Main app<br/>streamlit entrypoint<br/>[app.py]"]
  node_app_variants["App variants<br/>ui prototypes"]
  node_agents["Agents<br/>workflow orchestrator<br/>[agents.py]"]
  node_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_utils["Utils<br/>shared helpers<br/>[utils.py]"]
  node_openai_chat["OpenAI chat<br/>text adapter<br/>[openai_chat.py]"]
  node_gemini_chat["Gemini chat<br/>text adapter<br/>[gemini_chat.py]"]
  node_openai_vision["OpenAI vision<br/>vision adapter<br/>[openai_vision.py]"]
  node_dalle["DALL-E<br/>image adapter<br/>[dalle.py]"]
  node_speech["Speech<br/>audio pipeline<br/>[speech.py]"]
  node_elevenlabs_client["11Labs client<br/>voice API client"]
  node_elevenlabs_library["11Labs lib<br/>voice helper"]
  node_elevenlabs_legacy["11Labs alt<br/>voice helper<br/>[11labslibrary.py]"]
  node_screen_md["Screen notes<br/>ui doc<br/>[screen.md]"]
end

subgraph group_external["Providers"]
  node_openai(("OpenAI<br/>external service"))
  node_gemini(("Gemini<br/>external service"))
  node_elevenlabs(("ElevenLabs<br/>external service"))
  node_dalle_api(("DALL-E API<br/>external service"))
end

node_app_py -->|"starts flow"| node_agents
node_app_py -->|"uses"| node_utils
node_app_py -.->|"documents"| node_screen_md
node_app_variants -.->|"iterates"| node_app_py
node_agents -->|"loads"| node_prompts
node_agents -->|"calls"| node_openai_chat
node_agents -->|"calls"| node_gemini_chat
node_agents -->|"calls"| node_openai_vision
node_agents -->|"calls"| node_dalle
node_agents -->|"calls"| node_speech
node_openai_chat -->|"API"| node_openai
node_openai_vision -->|"API"| node_openai
node_gemini_chat -->|"API"| node_gemini
node_dalle -->|"API"| node_dalle_api
node_speech -->|"uses"| node_elevenlabs_client
node_elevenlabs_client -->|"API"| node_elevenlabs
node_elevenlabs_library -.->|"API"| node_elevenlabs
node_elevenlabs_legacy -.->|"API"| node_elevenlabs

click node_app_py "https://github.com/elder-plinius/i-llm/blob/main/app.py"
click node_agents "https://github.com/elder-plinius/i-llm/blob/main/agents.py"
click node_prompts "https://github.com/elder-plinius/i-llm/blob/main/prompts.py"
click node_utils "https://github.com/elder-plinius/i-llm/blob/main/utils.py"
click node_openai_chat "https://github.com/elder-plinius/i-llm/blob/main/openai_chat.py"
click node_gemini_chat "https://github.com/elder-plinius/i-llm/blob/main/gemini_chat.py"
click node_openai_vision "https://github.com/elder-plinius/i-llm/blob/main/openai_vision.py"
click node_dalle "https://github.com/elder-plinius/i-llm/blob/main/dalle.py"
click node_speech "https://github.com/elder-plinius/i-llm/blob/main/speech.py"
click node_elevenlabs_client "https://github.com/elder-plinius/i-llm/blob/main/elevenlabs_client.py"
click node_elevenlabs_library "https://github.com/elder-plinius/i-llm/blob/main/elevenlabs_library.py"
click node_elevenlabs_legacy "https://github.com/elder-plinius/i-llm/blob/main/11labslibrary.py"
click node_screen_md "https://github.com/elder-plinius/i-llm/blob/main/screen.md"

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_app_py,node_app_variants,node_agents,node_prompts,node_utils,node_openai_chat,node_gemini_chat,node_openai_vision,node_dalle,node_speech,node_elevenlabs_client,node_elevenlabs_library,node_elevenlabs_legacy,node_screen_md toneBlue
class node_openai,node_gemini,node_elevenlabs,node_dalle_api toneAmber
```

## Components

### Application

Streamlit UI and orchestration code inside the Python app

- [Main app](https://github.com/elder-plinius/i-llm/blob/main/app.py): streamlit entrypoint · Primary Streamlit application entrypoint · `app.py`
- **App variants**: ui prototypes · Alternative UI/prototype entrypoints
- [Agents](https://github.com/elder-plinius/i-llm/blob/main/agents.py): workflow orchestrator · Coordinates the multi-step movie generation flow · `agents.py`
- [Prompts](https://github.com/elder-plinius/i-llm/blob/main/prompts.py): prompt templates · Reusable prompt templates for generation stages · `prompts.py`
- [Utils](https://github.com/elder-plinius/i-llm/blob/main/utils.py): shared helpers · Common helper functions used across the app · `utils.py`
- [OpenAI chat](https://github.com/elder-plinius/i-llm/blob/main/openai_chat.py): text adapter · Chat/text generation integration for OpenAI models · `openai_chat.py`
- [Gemini chat](https://github.com/elder-plinius/i-llm/blob/main/gemini_chat.py): text adapter · Chat/text generation integration for Gemini models · `gemini_chat.py`
- [OpenAI vision](https://github.com/elder-plinius/i-llm/blob/main/openai_vision.py): vision adapter · Image understanding and multimodal input integration · `openai_vision.py`
- [DALL-E](https://github.com/elder-plinius/i-llm/blob/main/dalle.py): image adapter · Image generation integration for concept art or visuals · `dalle.py`
- [Speech](https://github.com/elder-plinius/i-llm/blob/main/speech.py): audio pipeline · Voice and dialogue synthesis workflow · `speech.py`
- [11Labs client](https://github.com/elder-plinius/i-llm/blob/main/elevenlabs_client.py): voice API client · Primary ElevenLabs service integration · `elevenlabs_client.py`
- [11Labs lib](https://github.com/elder-plinius/i-llm/blob/main/elevenlabs_library.py): voice helper · ElevenLabs-related helper library · `elevenlabs_library.py`
- [11Labs alt](https://github.com/elder-plinius/i-llm/blob/main/11labslibrary.py): voice helper · Legacy or alternate ElevenLabs helper module · `11labslibrary.py`
- [Screen notes](https://github.com/elder-plinius/i-llm/blob/main/screen.md): ui doc · Documentation or capture of the UI flow · `screen.md`

### Providers

Third-party AI services used by the app

- **OpenAI**: external service · External provider for chat and vision capabilities
- **Gemini**: external service · External provider for text generation
- **ElevenLabs**: external service · External provider for speech synthesis
- **DALL-E API**: external service · External image generation service

## Connections

- Main app → Agents: starts flow · Main UI delegates creative workflow steps to the orchestrator
- Main app → Utils: uses · UI shares common helpers
- Main app → Screen notes: documents · Screen notes capture the presentation flow
- App variants → Main app: iterates · Prototype UI versions evolve from the main app
- Agents → Prompts: loads · Orchestrator uses prompt templates for each generation stage
- Agents → OpenAI chat: calls · Routes text generation tasks to OpenAI adapter
- Agents → Gemini chat: calls · Routes text generation tasks to Gemini adapter
- Agents → OpenAI vision: calls · Uses vision adapter when image understanding is needed
- Agents → DALL-E: calls · Triggers image generation for visuals or concept art
- Agents → Speech: calls · Hands off voice and dialogue generation
- OpenAI chat → OpenAI: API · OpenAI text/chat service boundary
- OpenAI vision → OpenAI: API · OpenAI multimodal vision service boundary
- Gemini chat → Gemini: API · Gemini text generation service boundary
- DALL-E → DALL-E API: API · Image generation service boundary
- Speech → 11Labs client: uses · Speech pipeline delegates to ElevenLabs client
- 11Labs client → ElevenLabs: API · ElevenLabs speech synthesis service boundary
- 11Labs lib → ElevenLabs: API · Helper library also wraps ElevenLabs service
- 11Labs alt → ElevenLabs: API · Alternate legacy helper also wraps ElevenLabs service