# mblanc/storycraft architecture

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

- Interactive diagram: https://gitdiagram.com/mblanc/storycraft
- Repository: https://github.com/mblanc/storycraft

## Overview

##### Project Type and Purpose
- StoryCraft is a full-stack web application built with Next.js (App Router) that provides an AI-powered video storyboard generation workflow.
- It transforms user-entered text into cinematic scenes, voiceovers, music, and final video exports by orchestrating Google’s Vertex AI models (Imagen 4.0, Veo 3.0, Chirp 3, Lyria 2), FFmpeg processing, and Google Cloud services.

##### File Structure Highlights
- **app/** – Next.js App Router:
- app/actions/ – Server actions for AI generation, media processing, GCS interactions
- app/api/ – REST endpoints for scenarios, scenes, users, videos
- app/components/ – React UI components organized by feature (create, editor, storyboard, video, UI primitives)
- app/client-layout.tsx, layout.tsx, page.tsx – Top-level layouts and pages
- **lib/** – Core utilities and service wrappers: FFmpeg logic, Firestore client, Vertex AI model calls, Cloud Storage, TTS
- **public/** – Static assets: sample videos, audio tracks, generated TTS files, style references
- **scripts/** & **terraform/** – Deployment automation: container build & deploy, Terraform infra for Cloud Run & associated resources
- **Configuration** – Dockerfile, next.config.mjs, tailwind.config.ts, ESLint, CORS, PostCSS, TSConfig

##### Key Architectural Components
a. Frontend Layer (Next.js + React)
- Pages & layouts serve UI; TanStack Query manages server state & caching
- Components: timeline editor (audio waveform via Web Audio API), creation wizards, story scenario manager
- UI libraries: Radix UI primitives, Framer Motion animations, Tailwind CSS styling
b. API & Server Actions Layer
- API Routes (app/api/*/route.ts) for CRUD on scenarios, scenes, users, videos
- Server Actions (app/actions/*) triggered from client for AI calls, upload/download, media processing
c. Business Logic & Processing
- lib/ffmpeg.ts orchestrates video concatenation, audio mixing, overlays with fluent-ffmpeg
- Prompt utilities and retry logic in lib/prompt-utils.ts for robust Vertex AI calls
- Storage signed URLs in lib/storage.ts for secure GCS access
d. Data & Storage
- Firestore (lib/firestore.ts) holds metadata: scenario definitions, scene settings, user profiles, video records
- Google Cloud Storage (via signed URLs) stores raw/generated images, audio, video assets
e. External AI Services
- Imagen (image generation), Veo (video generation), Chirp (voice synthesis), Lyria (music composition)
- Google Cloud Text-to-Speech for neural voiceovers
f. Infrastructure & Deployment
- Docker container for Cloud Run
- Terraform scripts to provision Cloud Run service, Firestore, GCS buckets, IAM roles

##### Relationships and Data Flows
- Client UI → API Routes / Server Actions → Business Logic → External AI Services & FFmpeg → GCS (store assets) → Firestore (save metadata) → Client UI
- User request → Next.js frontend → server
- Server calls to Vertex AI / TTS → asset outputs
- FFmpeg processing → final video
- Asset storage in GCS & metadata in Firestore → retrieval by frontend

##### Architectural Patterns and Design Principles
- **Next.js App Router** with server actions for collocating UI and server code
- **Separation of Concerns**: UI components vs. API routes vs. processing logic in lib/
- **Event-driven Workflow**: each AI generation step as a discrete server action
- **Retry with Exponential Backoff** for stability on AI calls
- **Infrastructure as Code**: Terraform for reproducible Cloud Run & storage provisioning

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Page["app/page.tsx"]:::frontend
        Layout["app/layout.tsx"]:::frontend
        ClientLayout["app/client-layout.tsx"]:::frontend
        TimelineEditor["audio-waveform Editor"]:::frontend
        CreationWizard["Creation Wizard UI"]:::frontend
        ScenarioManager["Story Scenario Manager"]:::frontend
        EditModal1["Conversational Edit Modal"]:::frontend
        EditModal2["Edit Scene Modal"]:::frontend
    end

    %% API & Server Actions Layer
    subgraph "API & Server Actions Layer"
        direction TB
        ScenariosAPI["Scenarios CRUD API"]:::api
        SceneAPI["Scene CRUD API"]:::api
        UsersAPI["Users CRUD API"]:::api
        VideosAPI["Videos CRUD API"]:::api
        AuthAPI["Auth API (NextAuth)"]:::api
        RegenerateImageAPI["Image Regeneration API"]:::api

        generateScenes["generate-scenes.ts"]:::actions
        generateVideo["generate-video.ts"]:::actions
        generateMusic["generate-music.ts"]:::actions
        generateVoiceover["generate-voiceover.ts"]:::actions
        conversationalEdit["conversational-edit.ts"]:::actions
        modifyScenario["modify-scenario.ts"]:::actions
        resizeImage["resize-image.ts"]:::actions
        storageActions["storageActions.ts"]:::actions
        uploadImage["upload-image.ts"]:::actions
    end

    %% Business Logic & Processing
    subgraph "Business Logic & Processing"
        direction TB
        FFmpegService["lib/ffmpeg.ts"]:::logic
        PromptUtils["lib/prompt-utils.ts"]:::logic
        StorageHelpers["lib/storage.ts"]:::logic
        FirestoreClient["lib/firestore.ts"]:::logic
        ImagenWrapper["lib/imagen.ts"]:::logic
        VeoWrapper["lib/veo.ts"]:::logic
        LyriaWrapper["lib/lyria.ts"]:::logic
        GeminiHelpers["lib/gemini.ts / lib/rai.ts"]:::logic
        TTSWrapper["lib/tts.ts"]:::logic
        Utils["lib/utils.ts"]:::logic
    end

    %% Data & Storage
    subgraph "Data & Asset Storage"
        direction TB
        FirestoreDB["Firestore (Metadata)"]:::datastore
        GCSBucket["GCS Bucket (Assets)"]:::datastore
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        ImagenService["Imagen 4.0"]:::external
        VeoService["Veo 3.0"]:::external
        ChirpService["Chirp 3"]:::external
        LyriaService["Lyria 2"]:::external
        GCloudTTS["Google Cloud TTS"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        DockerDef["Dockerfile"]:::infra
        BuildDeploy["scripts/build-and-deploy.sh"]:::infra
        TerraformMain["terraform/main.tf"]:::infra
        TerraformVars["terraform/variables.tf"]:::infra
        TerraformOutputs["terraform/outputs.tf"]:::infra
        TerraformVersions["terraform/versions.tf"]:::infra
        SetupTerraform["scripts/setup-terraform.sh"]:::infra
    end

    %% Connections
    Page -->|renders| ScenariosAPI
    Page -->|renders| SceneAPI
    Page -->|renders| UsersAPI
    Page -->|renders| VideosAPI
    Page -->|calls| AuthAPI
    Page -->|calls| RegenerateImageAPI

    Page -->|uses| TimelineEditor
    Page -->|uses| CreationWizard
    Page -->|uses| ScenarioManager
    ScenarioManager -->|opens| EditModal1
    ScenarioManager -->|opens| EditModal2

    ScenariosAPI -->|invokes| generateScenes
    SceneAPI -->|invokes| conversationalEdit
    SceneAPI -->|invokes| modifyScenario
    SceneAPI -->|invokes| resizeImage
    VideosAPI -->|invokes| generateVideo
    VideosAPI -->|invokes| generateMusic
    VideosAPI -->|invokes| generateVoiceover
    VideosAPI -->|invokes| storageActions
    VideosAPI -->|invokes| uploadImage

    generateScenes -->|calls| ImagenService
    generateVideo -->|calls| FFmpegService
    generateMusic -->|calls| LyriaService
    generateVoiceover -->|calls| ChirpService
    generateVoiceover -->|calls| GCloudTTS

    generateScenes -->|uses| PromptUtils
    generateVideo -->|uses| PromptUtils
    generateVoiceover -->|uses| PromptUtils
    conversationalEdit -->|uses| PromptUtils
    modifyScenario -->|uses| PromptUtils
    resizeImage -->|uses| Utils

    storageActions -->|uses| StorageHelpers
    uploadImage -->|uses| StorageHelpers

    ScenariosAPI -->|reads/writes| FirestoreDB
    SceneAPI -->|reads/writes| FirestoreDB
    UsersAPI -->|reads/writes| FirestoreDB
    VideosAPI -->|reads/writes| FirestoreDB

    generateScenes -->|stores assets| GCSBucket
    generateVideo -->|stores assets| GCSBucket
    generateMusic -->|stores assets| GCSBucket
    generateVoiceover -->|stores assets| GCSBucket
    uploadImage -->|stores assets| GCSBucket

    DockerDef --> CloudRun["Cloud Run"]:::infra
    BuildDeploy --> DockerDef
    BuildDeploy --> TerraformMain
    TerraformMain -->|provisions| CloudRun
    TerraformMain -->|provisions| FirestoreDB
    TerraformMain -->|provisions| GCSBucket

    %% Click Events
    click Page "https://github.com/mblanc/storycraft/blob/main/app/page.tsx"
    click Layout "https://github.com/mblanc/storycraft/blob/main/app/layout.tsx"
    click ClientLayout "https://github.com/mblanc/storycraft/blob/main/app/client-layout.tsx"
    click TimelineEditor "https://github.com/mblanc/storycraft/blob/main/app/components/editor/audio-wave-form.tsx"
    click CreationWizard "https://github.com/mblanc/storycraft/blob/main/app/components/create/create-tab.tsx"
    click ScenarioManager "https://github.com/mblanc/storycraft/blob/main/app/components/scenario/scenario-tab.tsx"
    click EditModal1 "https://github.com/mblanc/storycraft/blob/main/app/components/storyboard/conversational-edit-modal.tsx"
    click EditModal2 "https://github.com/mblanc/storycraft/blob/main/app/components/storyboard/edit-scene-modal.tsx"
    click ScenariosAPI "https://github.com/mblanc/storycraft/blob/main/app/api/scenarios/route.ts"
    click SceneAPI "https://github.com/mblanc/storycraft/blob/main/app/api/scene/route.ts"
    click UsersAPI "https://github.com/mblanc/storycraft/blob/main/app/api/users/route.ts"
    click VideosAPI "https://github.com/mblanc/storycraft/blob/main/app/api/videos/route.ts"
    click AuthAPI "https://github.com/mblanc/storycraft/blob/main/app/api/auth/[...nextauth]/route.ts"
    click RegenerateImageAPI "https://github.com/mblanc/storycraft/blob/main/app/api/regenerate-image/route.ts"
    click generateScenes "https://github.com/mblanc/storycraft/blob/main/app/actions/generate-scenes.ts"
    click generateVideo "https://github.com/mblanc/storycraft/blob/main/app/actions/generate-video.ts"
    click generateMusic "https://github.com/mblanc/storycraft/blob/main/app/actions/generate-music.ts"
    click generateVoiceover "https://github.com/mblanc/storycraft/blob/main/app/actions/generate-voiceover.ts"
    click conversationalEdit "https://github.com/mblanc/storycraft/blob/main/app/actions/conversational-edit.ts"
    click modifyScenario "https://github.com/mblanc/storycraft/blob/main/app/actions/modify-scenario.ts"
    click resizeImage "https://github.com/mblanc/storycraft/blob/main/app/actions/resize-image.ts"
    click storageActions "https://github.com/mblanc/storycraft/blob/main/app/actions/storageActions.ts"
    click uploadImage "https://github.com/mblanc/storycraft/blob/main/app/actions/upload-image.ts"
    click FFmpegService "https://github.com/mblanc/storycraft/blob/main/lib/ffmpeg.ts"
    click PromptUtils "https://github.com/mblanc/storycraft/blob/main/lib/prompt-utils.ts"
    click StorageHelpers "https://github.com/mblanc/storycraft/blob/main/lib/storage.ts"
    click FirestoreClient "https://github.com/mblanc/storycraft/blob/main/lib/firestore.ts"
    click ImagenWrapper "https://github.com/mblanc/storycraft/blob/main/lib/imagen.ts"
    click VeoWrapper "https://github.com/mblanc/storycraft/blob/main/lib/veo.ts"
    click LyriaWrapper "https://github.com/mblanc/storycraft/blob/main/lib/lyria.ts"
    click GeminiHelpers "https://github.com/mblanc/storycraft/blob/main/lib/gemini.ts"
    click TTSWrapper "https://github.com/mblanc/storycraft/blob/main/lib/tts.ts"
    click Utils "https://github.com/mblanc/storycraft/blob/main/lib/utils.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E70BF,color:#000
    classDef api fill:#DFFFD0,stroke:#5FAF1F,color:#000
    classDef actions fill:#EFD8A1,stroke:#D49E0D,color:#000
    classDef logic fill:#FFD8C2,stroke:#E0702D,color:#000
    classDef datastore fill:#C2F0FF,stroke:#1F8FD4,color:#000
    classDef external fill:#F0DFFF,stroke:#A740D0,color:#000
    classDef infra fill:#E0E0E0,stroke:#7A7A7A,color:#000
```
