AI Filmmaking Studio

A comprehensive web platform for creating cinematic content using artificial intelligence. Combine prompt engineering, character management, story development, and AI-powered generation into a unified creative workflow.

🎬 Features

The platform provides filmmakers, animators, and content creators with a complete toolkit for AI-assisted filmmaking:

Prompt Engineering - Multi-field prompt builder with context-aware enhancement using LLMs. Craft precise prompts with character, scene, and shot context automatically incorporated.

Character Management - Visual identity system for maintaining character consistency. Define appearance, personality, and background with reference images for AI generation.

Story Development - Script breakdown into scenes and shots. Organize narrative structure with detailed scene descriptions and shot planning.

AI Generation - Generate videos (Veo 3.1, Kling, Wan, LTX-2), images (Nano Banana, Flux), and audio. Each generation is tracked with metadata and parameters.

Asset Organization - Tag-based system and intelligent folders for managing generated content. Organize by project, character, scene, type, or custom tags.

Prompt Templates - Reusable templates with placeholder substitution. Create template libraries for common shot types, character actions, and scene setups.

Generation History - Complete timeline of all generations with comparison and re-generation capabilities. Track which prompts, models, and parameters produced best results.

🚀 Quick Start

Prerequisites

• Node.js 22.13.0 or higher
• pnpm package manager
• MySQL/TiDB database (provided by Manus platform)
• API keys: fal.ai, OpenRouter

Installation

# Clone repository
git clone <repository-url>
cd ai-filmmaking-studio

# Install dependencies
pnpm install

# Set up environment (auto-configured by Manus)
# DATABASE_URL, JWT_SECRET, API keys are pre-configured

# Push database schema
pnpm db:push

# Start development server
pnpm dev

# Run tests
pnpm test

The development server runs on http://localhost:3000 with hot reloading enabled.

📚 Documentation

Comprehensive documentation for developers is organized into focused guides:

Document	Purpose
DEVELOPER_GUIDE.md	Project architecture, core concepts, and development workflow
API_DOCUMENTATION.md	Complete tRPC endpoint reference with examples
FEATURE_EXTENSION_GUIDE.md	Step-by-step guide to adding new features with examples
DATABASE_SCHEMA.md	Complete database schema with relationships and indexes
BEST_PRACTICES.md	Code patterns, conventions, and common pitfalls

🏗️ Architecture

The application follows a clean, layered architecture:

Frontend (React 19)
    ↓
tRPC Client
    ↓
Backend (Express + tRPC)
    ↓
Database Helpers (Drizzle ORM)
    ↓
MySQL/TiDB Database

Frontend - React 19 with Tailwind CSS 4 and shadcn/ui components. All data fetching through tRPC hooks.

Backend - Express 4 server with tRPC 11 for type-safe RPC. All business logic in procedures with Zod input validation.

Database - MySQL/TiDB with Drizzle ORM for type-safe queries. Automatic migrations with pnpm db:push.

External APIs - fal.ai for video/image/audio generation, OpenRouter for LLM enhancement.

📁 Project Structure

ai-filmmaking-studio/
├── client/                    # React frontend
│   ├── src/
│   │   ├── pages/            # Page components
│   │   ├── components/       # Reusable UI components
│   │   ├── contexts/         # React contexts
│   │   ├── hooks/            # Custom hooks
│   │   ├── lib/trpc.ts       # tRPC client
│   │   ├── App.tsx           # Main app with routing
│   │   └── index.css         # Global styles
│   └── public/               # Static assets
│
├── server/                    # Express backend
│   ├── _core/                # Framework infrastructure
│   ├── db.ts                 # Database helpers
│   ├── routers.ts            # tRPC procedures
│   ├── falai.ts              # Video/image/audio generation
│   ├── openrouter.ts         # LLM integration
│   ├── *.test.ts             # Unit tests
│   └── index.ts              # Server entry point
│
├── drizzle/                   # Database schema
│   ├── schema.ts             # Table definitions
│   └── *.sql                 # Migrations
│
├── DEVELOPER_GUIDE.md        # Architecture & concepts
├── API_DOCUMENTATION.md      # Endpoint reference
├── FEATURE_EXTENSION_GUIDE.md # Adding new features
├── DATABASE_SCHEMA.md        # Database reference
├── BEST_PRACTICES.md         # Code patterns
├── package.json
└── tsconfig.json

🔧 Development

Adding a New Feature

Follow the 6-step workflow documented in FEATURE_EXTENSION_GUIDE.md:

1. Design - Clarify requirements and data model
2. Database - Add schema in drizzle/schema.ts
3. Backend Helpers - Add queries in server/db.ts
4. tRPC Procedures - Add endpoints in server/routers.ts
5. Frontend - Create components in client/src/pages/
6. Testing - Write tests and verify

Code Style

The project uses strict TypeScript with these conventions:

• Type Safety - All data is fully typed from database to frontend
• Error Handling - Consistent try-catch patterns with logging
• Naming - camelCase for functions/variables, PascalCase for components/types
• Comments - Explain "why", not "what"
• Testing - Vitest for unit and integration tests

See BEST_PRACTICES.md for detailed patterns and examples.

Running Tests

# Run all tests
pnpm test

# Watch mode
pnpm test --watch

# UI mode
pnpm test --ui

# Coverage
pnpm test --coverage

Building for Production

# Build frontend and backend
pnpm build

# Start production server
pnpm start

🔐 Security

The platform implements multiple security layers:

User Isolation - All queries filter by userId to prevent cross-user data access. This is enforced at the database helper level.

Authentication - Manus OAuth integration with session-based authentication. Protected procedures require valid user context.

Input Validation - All tRPC inputs validated with Zod schemas. Type mismatches caught at compile time and runtime.

Permission Checks - Procedures verify user ownership before operations. Admin-only procedures use dedicated adminProcedure.

Environment Secrets - API keys and database credentials never hardcoded. All configuration through environment variables.

📊 Database

The application uses MySQL/TiDB with Drizzle ORM for type-safe database operations.

Key Tables

Table	Purpose
users	User accounts and authentication
projects	Main project containers
characters	Character definitions with visual identity
scenes	Story scenes and narrative structure
shots	Individual camera angles within scenes
prompts	Text prompts for generation
assets	Generated videos, images, and audio
tags	Flexible categorization system
intelligent_folders	Smart collections with auto-categorization
prompt_templates	Reusable templates with placeholders

See DATABASE_SCHEMA.md for complete schema documentation.

Migrations

Database schema is managed with Drizzle ORM:

# Push schema changes to database
pnpm db:push

# Generate migration files
pnpm db:generate

# View migration status
pnpm db:check

🤖 AI Integration

LLM Enhancement

Prompts are enhanced using OpenRouter LLM with project context:

const enhanced = await trpc.prompts.enhance.mutate({
  projectId: 1,
  content: "A character walking in a city",
  context: "character",
  contextId: 5,
});

Video Generation

Generate videos using fal.ai with multiple model options:

const video = await trpc.generation.generateVideo.mutate({
  projectId: 1,
  prompt: "Cinematic shot of hero in sunset",
  model: "veo", // veo, kling, wan, ltx
  duration: 10,
});

Image Generation

Generate images with Flux or Nano Banana:

const image = await trpc.generation.generateImage.mutate({
  projectId: 1,
  prompt: "Portrait of character",
  model: "flux", // flux, nano-banana
  width: 1024,
  height: 768,
});

Audio Generation

Generate audio narration and sound design:

const audio = await trpc.generation.generateAudio.mutate({
  projectId: 1,
  prompt: "Dramatic orchestral music",
  duration: 30,
});

🛠️ API Reference

All backend functionality is exposed through tRPC procedures. Complete API documentation is available in API_DOCUMENTATION.md.

Example: Creating a Project

// Frontend
const createProject = trpc.projects.create.useMutation();
const project = await createProject.mutateAsync({
  title: "My Film",
  genre: "Drama",
  description: "A story about...",
});

// Backend (automatic)
// 1. Input validated with Zod
// 2. User context extracted
// 3. Database helper called
// 4. Response typed and returned

🧪 Testing

The project uses Vitest for unit and integration testing:

import { describe, it, expect } from "vitest";
import { createProject, getProjectsByUser } from "./db";

describe("Projects", () => {
  it("should create a project", async () => {
    const project = await createProject({
      userId: 1,
      title: "Test Project",
    });
    expect(project?.title).toBe("Test Project");
  });
});

Run tests with pnpm test. All new features should include corresponding tests.

📦 Dependencies

Frontend

• React 19 - UI framework
• Tailwind CSS 4 - Styling
• shadcn/ui - Component library
• tRPC - Type-safe RPC client
• Wouter - Lightweight router
• Sonner - Toast notifications

Backend

• Express 4 - Web framework
• tRPC 11 - RPC framework
• Drizzle ORM - Database ORM
• Zod - Input validation
• Node.js 22 - Runtime

External Services

• fal.ai - Video/image/audio generation
• OpenRouter - LLM API
• Manus OAuth - Authentication

🚀 Deployment

The application is deployed on the Manus platform with automatic:

• SSL/TLS certificates
• Database backups
• Environment variable management
• Scaling and load balancing

To deploy, create a checkpoint and click the Publish button in the Manus UI.

🤝 Contributing

When contributing to this project:

1. Create a feature branch: git checkout -b feat/your-feature
2. Follow the development workflow in DEVELOPER_GUIDE.md
3. Write tests for new functionality
4. Update documentation
5. Create a pull request with clear description

See BEST_PRACTICES.md for code style and patterns.

📝 License

This project is proprietary software developed by Manus.

🆘 Support

For issues, questions, or feature requests:

1. Check existing documentation in the /docs folder
2. Review similar features in the codebase
3. Check test files for usage examples
4. Review commit history for context

📞 Contact

For support or inquiries, visit help.manus.im

---

Version: 1.0
Last Updated: March 2026
Maintainers: Manus AI Development Team
Status: Active Development