Trelby Core

A modern, full-stack screenplay writing application with real-time collaboration, AI assistance, and comprehensive breakdown tools.

🎬 Overview

Trelby Core is a comprehensive screenplay writing platform consisting of:

• Backend API: FastAPI-based REST API server for screenplay operations
• Frontend: Next.js React application with advanced editing capabilities
• AI Integration: Multi-provider LLM support for screenplay generation and translation
• Breakdown Tools: Advanced screenplay breakdown and production planning

✨ Features

Core Functionality

• Modern web-based screenplay editor with proper industry formatting
• Real-time auto-save and version control
• User authentication and script management
• Multi-format export (PDF, Fountain, Final Draft FDX, HTML)

Advanced Features

• AI-Powered Translation: Multi-language screenplay translation
• Screenplay Breakdown: Automatic and manual element extraction for production planning
• Scene Navigation: Smart scene detection and quick navigation
• Character Management: Comprehensive character tracking and metadata
• Import Support: PDF, FDX, and plain text import capabilities

Production Tools

• Comprehensive breakdown reports with filtering
• Production summary generation
• Element categorization and highlighting
• Export capabilities for production teams

🏗️ Project Structure

trelby-core/
├── src/                    # Backend API server (FastAPI)
│   ├── app/               # Application logic
│   ├── requirements.txt   # Python dependencies
│   └── dockerfile        # Container configuration
├── sc_app/               # Frontend (Next.js + React)
│   ├── components/       # React components
│   ├── lib/             # Utilities and helpers
│   ├── services/        # API services
│   ├── store/           # State management (Zustand)
│   └── package.json     # Node.js dependencies
└── README.md            # This file

🚀 Quick Start

Prerequisites

• Python 3.8+ with pip
• Node.js 16+ with npm/yarn/bun
• PostgreSQL 13+
• Docker (optional, for containerized deployment)

1. Clone the Repository

git clone https://github.com/yourusername/trelby-core.git
cd trelby-core

2. Backend Setup

cd src

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your configuration (see Environment Variables section)

# Initialize the database
python -m app.db.init_db

# Start the development server
uvicorn app.main:app --reload

The API will be available at http://localhost:8000 with documentation at http://localhost:8000/api/docs

3. Frontend Setup

cd sc_app

# Install dependencies
npm install
# or: bun install / yarn install

# Configure environment variables
cp .env.local.example .env.local
# Edit .env.local with your configuration

# Start development server
npm run dev

The frontend will be available at http://localhost:3000

🔧 Environment Variables

Backend (.env)

Create a .env file in the src/ directory:

# Security
SECRET_KEY=your-secret-key-here-change-this-in-production

# Database Configuration
DB_NAME=trelby
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432

# CORS Origins (comma-separated URLs)
BACKEND_CORS_ORIGINS=http://localhost:3000,http://localhost:3001,https://your-domain.com

# AI Service API Keys (Optional)
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GEMINI_API_KEY=your-gemini-key
GROQ_API_KEY=your-groq-key

# Babel LLM Service Configuration
BABEL_LLM_ENABLED=true
BABEL_LLM_API_URL=http://localhost:8001
BABEL_LLM_TIMEOUT=30
BABEL_LLM_MAX_RETRIES=3

Frontend (.env.local)

Create a .env.local file in the sc_app/ directory:

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000

# Environment
NODE_ENV=development

🔒 Security

Generate a Secure Secret Key

# Using OpenSSL
openssl rand -hex 32

# Using Python
python -c "import secrets; print(secrets.token_hex(32))"

CORS Configuration

For production, update BACKEND_CORS_ORIGINS to include only your frontend domains:

BACKEND_CORS_ORIGINS=https://your-frontend-domain.com,https://your-admin-domain.com

🚢 Deployment

Using Docker

# Build and run with Docker Compose
docker-compose up --build

# Or build individual containers
docker build -t trelby-backend ./src
docker build -t trelby-frontend ./sc_app

Manual Deployment

Backend (Production)

cd src

# Install dependencies
pip install -r requirements.txt

# Set production environment variables
export SECRET_KEY="your-production-secret-key"
export DB_HOST="your-production-db-host"
# ... other production variables

# Run with Gunicorn
gunicorn app.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Frontend (Production)

cd sc_app

# Install dependencies
npm install

# Set production environment variables
export NEXT_PUBLIC_API_URL="https://your-api-domain.com"

# Build for production
npm run build

# Start production server
npm start

🧪 Development

Running Tests

# Backend tests
cd src
pytest

# Frontend tests
cd sc_app
npm test

Code Quality

This project uses:

• ESLint & Prettier for frontend code formatting
• Black & isort for backend code formatting
• TypeScript for type safety
• Proper logging instead of console statements in production

Development Workflow

1. Backend: FastAPI with auto-reload for development
2. Frontend: Next.js with hot reloading
3. Database: PostgreSQL with SQLAlchemy ORM
4. State Management: Zustand for client-side state
5. Styling: Tailwind CSS with custom components

📚 API Documentation

Once the backend is running, visit:

• Interactive Docs: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI JSON: http://localhost:8000/api/openapi.json

🤖 AI Features

Supported Providers

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude)
• Google (Gemini)
• Groq (Open-source models)
• Custom BabelLLM (Self-hosted)

Translation Support

• UI element translation
• Full screenplay translation
• Batch processing with progress tracking
• Error handling and retry mechanisms

🔧 Troubleshooting

Common Issues

1. Database Connection: Ensure PostgreSQL is running and credentials are correct
2. CORS Errors: Update BACKEND_CORS_ORIGINS to include your frontend URL
3. Import Issues: Check file format support and file size limits
4. AI Features: Verify API keys are set correctly

Performance Tips

1. Database: Use connection pooling for production
2. Frontend: Enable caching for static assets
3. Logging: Use appropriate log levels for production
4. Memory: Monitor memory usage with large screenplays

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Use proper TypeScript types
• Implement proper error handling

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the foundation of the original Trelby screenplay editor
• Uses industry-standard screenplay formatting conventions
• Inspired by modern web development best practices

📞 Support

For questions, issues, or contributions:

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Available in the /docs directory

---

Trelby Core - Professional screenplay writing for the modern age. 🎬✨