# jaybaradd/screenplay architecture

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

- Interactive diagram: https://gitdiagram.com/jaybaradd/screenplay
- Repository: https://github.com/jaybaradd/screenplay

## Overview

This is a local, single-user studio for turning screenplay text into a human-approved cultural adaptation and production-ready visual assets. Its main path runs from project setup and scene extraction through continuity control, cultural research and planning, screenplay adaptation, visual production, sequential scene generation, and export. The README documents the workflow gates and major visual, audit, and export capabilities; sampled source and the SOURCE INDEX support the API, workflow, provider, persistence, and culture components. Some detailed stage-to-stage implementation links are documented rather than visible in the excerpts.

Main entry points: [`backend/workflow.py`](https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py) (LangGraph engine), [`backend/api.py`](https://github.com/jaybaradd/screenplay/blob/main/backend/api.py) (FastAPI), [`frontend/pages`](https://github.com/jaybaradd/screenplay/tree/main/frontend/pages) (Streamlit screens), [`backend/providers.py`](https://github.com/jaybaradd/screenplay/blob/main/backend/providers.py) (AI provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Studio experience"]
  node_ui["Streamlit screens"]
  node_api["FastAPI<br/>[api.py]"]
end

subgraph group_workflow["Adaptation workflow"]
  node_project_setup["Project setup<br/>[api.py]"]
  node_extraction["Scene extraction<br/>[services.py]"]
  node_plan["Six-layer plan<br/>[workflow.py]"]
  node_adaptation["Screenplay adaptation<br/>[services.py]"]
  node_workflow_engine["LangGraph engine<br/>[workflow.py]"]
end

subgraph group_culture["Culture and continuity"]
  node_continuity["Continuity control<br/>[continuity.py]"]
  node_research["Cultural brief<br/>[workflow.py]"]
  node_culture_profiles["Culture profiles<br/>[registry.py]"]
  node_context["Prompt context<br/>[context.py]"]
end

subgraph group_visual["Visual production"]
  node_visual_manifest["Visual manifest<br/>[services.py]"]
  node_asset_generation["Asset generation<br/>[services.py]"]
  node_scene_prompts["Scene prompts<br/>[services.py]"]
  node_verification["Visual verification<br/>[services.py]"]
  node_export["Export package<br/>[services.py]"]
end

subgraph group_platform["Persistence and operations"]
  node_ai_provider["AI provider<br/>[providers.py]"]
  node_structured_store[("Revision store<br/>[storage.py]")]
  node_checkpoint_store[("Workflow checkpoints<br/>[workflow.py]")]
  node_asset_store[("Local assets<br/>[config.py]")]
  node_observability["Usage and traces<br/>[observability.py]"]
end

node_writer(("Screenplay author"))
node_reviewer(("Human reviewer"))
node_langfuse["Langfuse"]

node_writer -->|"provides screenplay"| node_ui
node_reviewer -->|"reviews and approves"| node_ui
node_ui -->|"sends HTTP requests"| node_api
node_api -->|"creates project"| node_project_setup
node_api -->|"starts and advances"| node_workflow_engine
node_api -->|"reads and writes"| node_structured_store
node_api -->|"lists profiles"| node_culture_profiles
node_workflow_engine -->|"runs extraction"| node_extraction
node_workflow_engine -->|"checks continuity"| node_continuity
node_workflow_engine -->|"builds brief"| node_research
node_workflow_engine -->|"builds plan"| node_plan
node_workflow_engine -->|"adapts screenplay"| node_adaptation
node_workflow_engine -->|"builds manifest"| node_visual_manifest
node_workflow_engine -->|"compiles prompts"| node_scene_prompts
node_workflow_engine -->|"generates assets"| node_asset_generation
node_workflow_engine -->|"requests verification"| node_verification
node_workflow_engine -->|"exports project"| node_export
node_workflow_engine -->|"checkpoints state"| node_checkpoint_store
node_workflow_engine -->|"stores revisions"| node_structured_store
node_workflow_engine -->|"uses profile snapshot"| node_culture_profiles
node_workflow_engine -->|"compiles stage context"| node_context
node_workflow_engine -->|"requests model work"| node_ai_provider
node_research -->|"grounds research"| node_ai_provider
node_asset_generation -->|"stores image bytes"| node_asset_store
node_export -->|"packages images"| node_asset_store
node_ai_provider -->|"records usage"| node_observability
node_observability -.->|"sends optional traces"| node_langfuse

click node_ui "https://github.com/jaybaradd/screenplay/tree/main/frontend/pages"
click node_api "https://github.com/jaybaradd/screenplay/blob/main/backend/api.py"
click node_project_setup "https://github.com/jaybaradd/screenplay/blob/main/backend/api.py"
click node_extraction "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_continuity "https://github.com/jaybaradd/screenplay/blob/main/backend/continuity.py"
click node_research "https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py"
click node_culture_profiles "https://github.com/jaybaradd/screenplay/blob/main/backend/cultures/registry.py"
click node_context "https://github.com/jaybaradd/screenplay/blob/main/backend/cultures/context.py"
click node_plan "https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py"
click node_adaptation "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_visual_manifest "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_asset_generation "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_scene_prompts "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_verification "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_export "https://github.com/jaybaradd/screenplay/blob/main/backend/services.py"
click node_workflow_engine "https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py"
click node_ai_provider "https://github.com/jaybaradd/screenplay/blob/main/backend/providers.py"
click node_structured_store "https://github.com/jaybaradd/screenplay/blob/main/backend/storage.py"
click node_checkpoint_store "https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py"
click node_asset_store "https://github.com/jaybaradd/screenplay/blob/main/backend/config.py"
click node_observability "https://github.com/jaybaradd/screenplay/blob/main/backend/observability.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_ui,node_api,node_writer,node_reviewer toneBlue
class node_project_setup,node_extraction,node_plan,node_adaptation,node_workflow_engine toneAmber
class node_continuity,node_research,node_culture_profiles,node_context toneMint
class node_visual_manifest,node_asset_generation,node_scene_prompts,node_verification,node_export toneRose
class node_ai_provider,node_structured_store,node_checkpoint_store,node_asset_store,node_observability,node_langfuse toneIndigo
```

## Components

### Studio experience

- [Streamlit screens](https://github.com/jaybaradd/screenplay/tree/main/frontend/pages): `frontend/pages`
- [FastAPI](https://github.com/jaybaradd/screenplay/blob/main/backend/api.py): `backend/api.py`

### Adaptation workflow

- [Project setup](https://github.com/jaybaradd/screenplay/blob/main/backend/api.py): `backend/api.py`
- [Scene extraction](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [Six-layer plan](https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py): `backend/workflow.py`
- [Screenplay adaptation](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [LangGraph engine](https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py): `backend/workflow.py`

### Culture and continuity

- [Continuity control](https://github.com/jaybaradd/screenplay/blob/main/backend/continuity.py): `backend/continuity.py`
- [Cultural brief](https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py): `backend/workflow.py`
- [Culture profiles](https://github.com/jaybaradd/screenplay/blob/main/backend/cultures/registry.py): `backend/cultures/registry.py`
- [Prompt context](https://github.com/jaybaradd/screenplay/blob/main/backend/cultures/context.py): `backend/cultures/context.py`

### Visual production

- [Visual manifest](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [Asset generation](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [Scene prompts](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [Visual verification](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`
- [Export package](https://github.com/jaybaradd/screenplay/blob/main/backend/services.py): `backend/services.py`

### Persistence and operations

- [AI provider](https://github.com/jaybaradd/screenplay/blob/main/backend/providers.py): `backend/providers.py`
- [Revision store](https://github.com/jaybaradd/screenplay/blob/main/backend/storage.py): `backend/storage.py`
- [Workflow checkpoints](https://github.com/jaybaradd/screenplay/blob/main/backend/workflow.py): `backend/workflow.py`
- [Local assets](https://github.com/jaybaradd/screenplay/blob/main/backend/config.py): `backend/config.py`
- [Usage and traces](https://github.com/jaybaradd/screenplay/blob/main/backend/observability.py): `backend/observability.py`

### Other components

- **Screenplay author**
- **Human reviewer**
- **Langfuse**

## Connections

- Screenplay author → Streamlit screens: provides screenplay (evidence: `README.md`)
- Human reviewer → Streamlit screens: reviews and approves (evidence: `README.md`)
- Streamlit screens → FastAPI: sends HTTP requests (evidence: `README.md`)
- FastAPI → Project setup: creates project (evidence: `backend/api.py`)
- FastAPI → LangGraph engine: starts and advances (evidence: `backend/api.py`)
- FastAPI → Revision store: reads and writes (evidence: `backend/api.py`)
- FastAPI → Culture profiles: lists profiles (evidence: `backend/api.py`)
- LangGraph engine → Scene extraction: runs extraction (evidence: `README.md`)
- LangGraph engine → Continuity control: checks continuity (evidence: `backend/workflow.py`)
- LangGraph engine → Cultural brief: builds brief (evidence: `README.md`)
- LangGraph engine → Six-layer plan: builds plan (evidence: `README.md`)
- LangGraph engine → Screenplay adaptation: adapts screenplay (evidence: `backend/workflow.py`)
- LangGraph engine → Visual manifest: builds manifest (evidence: `backend/workflow.py`)
- LangGraph engine → Scene prompts: compiles prompts (evidence: `README.md`)
- LangGraph engine → Asset generation: generates assets (evidence: `README.md`)
- LangGraph engine → Visual verification: requests verification (evidence: `README.md`)
- LangGraph engine → Export package: exports project (evidence: `README.md`)
- LangGraph engine → Workflow checkpoints: checkpoints state (evidence: `README.md`)
- LangGraph engine → Revision store: stores revisions (evidence: `README.md`)
- LangGraph engine → Culture profiles: uses profile snapshot (evidence: `README.md`)
- LangGraph engine → Prompt context: compiles stage context (evidence: `backend/workflow.py`)
- LangGraph engine → AI provider: requests model work (evidence: `backend/workflow.py`)
- Cultural brief → AI provider: grounds research (evidence: `README.md`)
- Asset generation → Local assets: stores image bytes (evidence: `README.md`)
- Export package → Local assets: packages images (evidence: `README.md`)
- AI provider → Usage and traces: records usage (evidence: `backend/providers.py`)
- Usage and traces → Langfuse: sends optional traces (evidence: `backend/observability.py`)
