# thehiggsfieldai/openhiggsfield architecture

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

- Interactive diagram: https://gitdiagram.com/thehiggsfieldai/openhiggsfield
- Repository: https://github.com/thehiggsfieldai/openhiggsfield

## Overview

OpenHiggsfield is a self-hostable character-to-film studio. Its main workflow is to choose or upload a character, create a story, review scenes and an estimate, connect provider credentials, render clips, and assemble a film. The graph also preserves the separate beta creative-studio capabilities visible in the source index. Relationships are limited to documented README statements and shown imports or calls; some UI and server behavior is unsampled, so uncertain wiring is omitted.

Main entry points: [`deploy/beta/studio-api.mjs`](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/studio-api.mjs) (Creative studio API), [`deploy/studio/server.mjs`](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/server.mjs) (HTTP server), [`apps/story-studio/src/App.tsx`](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/App.tsx) (Studio app), [`apps/story-studio/src/lib/studio/pipeline.ts`](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/pipeline.ts) (Render pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Studio experience"]
  node_app["Studio app<br/>[App.tsx]"]
  node_create["Story creation UI<br/>[create-form.tsx]"]
  node_production_ui["Production progress"]
  node_library_ui["Film library<br/>[films-page.tsx]"]
  node_connections_ui["Provider connections"]
end

subgraph group_story["Story production"]
  node_pipeline["Render pipeline<br/>[pipeline.ts]"]
  node_director["Scene director<br/>[director.ts]"]
  node_story_data["Story catalog<br/>[data.ts]"]
  node_fal["fal provider<br/>[fal.ts]"]
  node_voice["Voice tools<br/>[voices.ts]"]
  node_film_store[("Job records<br/>[store.ts]")]
  node_story_api["Story and character API<br/>[api.mjs]"]
  node_film_service["Film rendering service<br/>[films.mjs]"]
  node_film_export["MP4 assembly<br/>[film-export.mjs]"]
end

subgraph group_platform["Accounts and media"]
  node_server["HTTP server<br/>[server.mjs]"]
  node_auth["Magic-link auth<br/>[auth.mjs]"]
  node_account["Account management<br/>[account.mjs]"]
  node_media["Provider media<br/>[media.mjs]"]
end

subgraph group_beta["Beta creative tools"]
  node_workspace["Workspace tools"]
  node_beta_api["Creative studio API<br/>[studio-api.mjs]"]
  node_image_studio["Image generation<br/>[image-studio.mjs]"]
  node_model_routing["Video model routing<br/>[model-routing.mjs]"]
  node_models["Model catalog<br/>[models.mjs]"]
  node_treatment["Creative treatment"]
  node_research["Research assessment"]
  node_vault[("Credential vault<br/>[vault.mjs]")]
end

node_user(("Studio user"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_create
node_app -->|"renders"| node_production_ui
node_app -->|"renders"| node_library_ui
node_app -->|"renders"| node_connections_ui
node_app -->|"starts jobs"| node_pipeline
node_pipeline -->|"requests scenes"| node_director
node_pipeline -->|"reads catalog"| node_story_data
node_pipeline -->|"requests generation"| node_fal
node_pipeline -->|"checks voice"| node_voice
node_pipeline -->|"saves records"| node_film_store
node_director -->|"uses provider"| node_fal
node_director -->|"reads data"| node_story_data
node_server -->|"configures auth"| node_auth
node_server -->|"creates handler"| node_account
node_server -->|"creates handler"| node_media
node_server -->|"creates handler"| node_story_api
node_server -->|"creates handler"| node_film_service
node_film_service -->|"reads characters"| node_story_api
node_film_service -->|"resolves media"| node_media
node_film_service -->|"assembles film"| node_film_export
node_server -->|"routes requests"| node_beta_api
node_beta_api -->|"dispatches tools"| node_workspace
node_beta_api -->|"dispatches images"| node_image_studio
node_beta_api -->|"estimates models"| node_model_routing
node_model_routing -->|"filters catalog"| node_models
node_beta_api -->|"validates treatment"| node_treatment
node_beta_api -->|"uses assessment"| node_research
node_beta_api -->|"uses credentials"| node_vault

click node_app "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/App.tsx"
click node_create "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/create-form.tsx"
click node_production_ui "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/film-production.tsx"
click node_library_ui "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/films-page.tsx"
click node_connections_ui "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/connections-page.tsx"
click node_pipeline "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/pipeline.ts"
click node_director "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/director.ts"
click node_story_data "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/data.ts"
click node_fal "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/fal.ts"
click node_voice "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/voices.ts"
click node_film_store "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/store.ts"
click node_story_api "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/api.mjs"
click node_film_service "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/films.mjs"
click node_film_export "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/film-export.mjs"
click node_server "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/server.mjs"
click node_auth "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/auth.mjs"
click node_account "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/account.mjs"
click node_media "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/media.mjs"
click node_workspace "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/workspace-tools.mjs"
click node_beta_api "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/studio-api.mjs"
click node_image_studio "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/image-studio.mjs"
click node_model_routing "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/model-routing.mjs"
click node_models "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/models.mjs"
click node_treatment "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/lib/creative-treatment.ts"
click node_research "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/research-assessment.mjs"
click node_vault "https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/vault.mjs"

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,node_create,node_production_ui,node_library_ui,node_connections_ui,node_user toneBlue
class node_pipeline,node_director,node_story_data,node_fal,node_voice,node_film_store,node_story_api,node_film_service,node_film_export toneAmber
class node_server,node_auth,node_account,node_media toneMint
class node_workspace,node_beta_api,node_image_studio,node_model_routing,node_models,node_treatment,node_research,node_vault toneRose
```

## Components

### Studio experience

- [Studio app](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/App.tsx): `apps/story-studio/src/App.tsx`
- [Story creation UI](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/create-form.tsx): `apps/story-studio/src/components/app/create-form.tsx`
- [Production progress](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/film-production.tsx): `apps/story-studio/src/components/app/film-production.tsx`
- [Film library](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/films-page.tsx): `apps/story-studio/src/components/app/films-page.tsx`
- [Provider connections](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/components/app/connections-page.tsx): `apps/story-studio/src/components/app/connections-page.tsx`

### Story production

- [Render pipeline](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/pipeline.ts): `apps/story-studio/src/lib/studio/pipeline.ts`
- [Scene director](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/director.ts): `apps/story-studio/src/lib/studio/director.ts`
- [Story catalog](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/data.ts): `apps/story-studio/src/lib/studio/data.ts`
- [fal provider](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/fal.ts): `apps/story-studio/src/lib/studio/fal.ts`
- [Voice tools](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/voices.ts): `apps/story-studio/src/lib/studio/voices.ts`
- [Job records](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/apps/story-studio/src/lib/studio/store.ts): `apps/story-studio/src/lib/studio/store.ts`
- [Story and character API](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/api.mjs): `deploy/story/api.mjs`
- [Film rendering service](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/films.mjs): `deploy/story/films.mjs`
- [MP4 assembly](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/story/film-export.mjs): `deploy/story/film-export.mjs`

### Accounts and media

- [HTTP server](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/server.mjs): `deploy/studio/server.mjs`
- [Magic-link auth](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/auth.mjs): `deploy/studio/auth.mjs`
- [Account management](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/account.mjs): `deploy/studio/account.mjs`
- [Provider media](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/studio/media.mjs): `deploy/studio/media.mjs`

### Beta creative tools

- [Workspace tools](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/workspace-tools.mjs): `deploy/beta/workspace-tools.mjs`
- [Creative studio API](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/studio-api.mjs): `deploy/beta/studio-api.mjs`
- [Image generation](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/image-studio.mjs): `deploy/beta/image-studio.mjs`
- [Video model routing](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/model-routing.mjs): `deploy/beta/model-routing.mjs`
- [Model catalog](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/models.mjs): `deploy/beta/models.mjs`
- [Creative treatment](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/lib/creative-treatment.ts): `lib/creative-treatment.ts`
- [Research assessment](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/research-assessment.mjs): `deploy/beta/research-assessment.mjs`
- [Credential vault](https://github.com/thehiggsfieldai/openhiggsfield/blob/main/deploy/beta/vault.mjs): `deploy/beta/vault.mjs`

### Other components

- **Studio user**

## Connections

- Studio user → Studio app: uses (evidence: `README.md`)
- Studio app → Story creation UI: renders (evidence: `apps/story-studio/src/App.tsx`)
- Studio app → Production progress: renders (evidence: `apps/story-studio/src/App.tsx`)
- Studio app → Film library: renders (evidence: `apps/story-studio/src/App.tsx`)
- Studio app → Provider connections: renders (evidence: `apps/story-studio/src/App.tsx`)
- Studio app → Render pipeline: starts jobs (evidence: `apps/story-studio/src/App.tsx`)
- Render pipeline → Scene director: requests scenes (evidence: `apps/story-studio/src/lib/studio/pipeline.ts`)
- Render pipeline → Story catalog: reads catalog (evidence: `apps/story-studio/src/lib/studio/pipeline.ts`)
- Render pipeline → fal provider: requests generation (evidence: `apps/story-studio/src/lib/studio/pipeline.ts`)
- Render pipeline → Voice tools: checks voice (evidence: `apps/story-studio/src/lib/studio/pipeline.ts`)
- Render pipeline → Job records: saves records (evidence: `apps/story-studio/src/lib/studio/pipeline.ts`)
- Scene director → fal provider: uses provider (evidence: `apps/story-studio/src/lib/studio/director.ts`)
- Scene director → Story catalog: reads data (evidence: `apps/story-studio/src/lib/studio/director.ts`)
- HTTP server → Magic-link auth: configures auth (evidence: `deploy/studio/server.mjs`)
- HTTP server → Account management: creates handler (evidence: `deploy/studio/server.mjs`)
- HTTP server → Provider media: creates handler (evidence: `deploy/studio/server.mjs`)
- HTTP server → Story and character API: creates handler (evidence: `deploy/studio/server.mjs`)
- HTTP server → Film rendering service: creates handler (evidence: `deploy/studio/server.mjs`)
- Film rendering service → Story and character API: reads characters (evidence: `deploy/story/films.mjs`)
- Film rendering service → Provider media: resolves media (evidence: `deploy/story/films.mjs`)
- Film rendering service → MP4 assembly: assembles film (evidence: `deploy/story/films.mjs`)
- HTTP server → Creative studio API: routes requests (evidence: `deploy/studio/server.mjs`)
- Creative studio API → Workspace tools: dispatches tools (evidence: `deploy/beta/studio-api.mjs`)
- Creative studio API → Image generation: dispatches images (evidence: `deploy/beta/studio-api.mjs`)
- Creative studio API → Video model routing: estimates models (evidence: `deploy/beta/studio-api.mjs`)
- Video model routing → Model catalog: filters catalog (evidence: `deploy/beta/model-routing.mjs`)
- Creative studio API → Creative treatment: validates treatment (evidence: `deploy/beta/studio-api.mjs`)
- Creative studio API → Research assessment: uses assessment (evidence: `deploy/beta/studio-api.mjs`)
- Creative studio API → Credential vault: uses credentials (evidence: `deploy/beta/studio-api.mjs`)
