Development Guide

Overview

This guide will help you set up a development environment to contribute to Tesslate Studio or build custom extensions.

Just want to use Tesslate Studio? See the Self-Hosting Quickstart instead.

Prerequisites

Before you begin, install these tools:

Node.js & npm

Version: Node.js 18+ and npm 9+Download from nodejs.orgVerify:

node --version  # v18.0.0 or higher
npm --version   # 9.0.0 or higher

Python & uv

Version: Python 3.11+Download from python.orgInstall uv (Python package manager):

pip install uv

Docker Desktop

Download from docker.com/products/docker-desktopVerify:

docker --version
docker compose version

Git

Download from git-scm.comVerify:

git --version

Fork and Clone

Fork the Repository

Navigate to github.com/TesslateAI/Studio
Click “Fork” button
Choose your account

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/Studio.git
cd Studio

Replace YOUR-USERNAME with your GitHub username.

Add Upstream Remote

git remote add upstream https://github.com/TesslateAI/Studio.git

This lets you pull latest changes from the main repository.

Verify Remotes

git remote -v

You should see:

origin    https://github.com/YOUR-USERNAME/Studio.git (fetch)
origin    https://github.com/YOUR-USERNAME/Studio.git (push)
upstream  https://github.com/TesslateAI/Studio.git (fetch)
upstream  https://github.com/TesslateAI/Studio.git (push)

Install Dependencies

Frontend
Backend

cd app
npm install

This installs all React dependencies including:

React 19
Vite 7
TypeScript
Tailwind CSS
Monaco Editor
Zustand

cd orchestrator

# Create virtual environment
uv venv

# Activate virtual environment
# On Mac/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

This installs all Python dependencies including:

FastAPI
SQLAlchemy
LiteLLM
Docker SDK
PostgreSQL drivers

Configure Environment

Copy Environment File

cp .env.example .env

Generate Keys

# SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"

# LITELLM_MASTER_KEY
python -c "import secrets; print('sk-' + secrets.token_urlsafe(32))"

Update .env File

# Security
SECRET_KEY=your-generated-key
LITELLM_MASTER_KEY=sk-your-generated-key

# For development, you can use test keys
OPENAI_API_KEY=sk-your-dev-key

# Development settings
LOG_LEVEL=DEBUG
AUTO_SEED_DATABASE=true

Development Modes

Choose the mode that fits your workflow:

Full Docker Mode

Best for: Testing the complete system, minimal setup

docker compose up -d

Pros:

Everything works out of the box
Closest to production
No local dependencies needed

Cons:

Slower feedback loop
Need to rebuild on code changes

Access:

Frontend: http://studio.localhost
Backend API: http://studio.localhost/api
Traefik Dashboard: http://localhost:8080

Hybrid Mode (Recommended)

Best for: Active development with instant feedback

Start Infrastructure

docker compose up -d traefik postgres

This starts only Traefik and PostgreSQL.

Run Backend

cd orchestrator
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Backend runs with hot reload on port 8000.

Run Frontend

cd app
npm run dev

Frontend runs with Vite HMR on port 5173.

Pros:

Instant hot reload
Direct access to logs
Easy debugging
Fast iteration

Cons:

More terminal windows
Manual dependency management

Access:

Frontend: http://localhost:5173
Backend API: http://localhost:8000
Backend Docs: http://localhost:8000/docs

Project Structure

Studio/
├── app/                    # Frontend (React + Vite)
├── orchestrator/          # Backend (FastAPI)
├── scripts/               # Utility scripts
├── docs/                  # Documentation
├── docker-compose.yml     # Docker configuration
├── .env.example           # Environment template
└── README.md              # Project README

Making Changes

Create a Feature Branch

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring
test/ - Tests

Make Your Changes

Frontend Changes
Backend Changes
Database Changes

Edit files in app/src/
Changes auto-reload in browser (HMR)
Check browser console for errors
Test in different screen sizes

Edit files in orchestrator/app/
Server auto-reloads (with --reload flag)
Check terminal for errors
Test endpoints at http://localhost:8000/docs

Create migration in scripts/migrations/

Test migration:

docker compose exec orchestrator python scripts/migrations/your_migration.py

Verify schema changes

Keep Your Branch Updated

# Fetch latest changes
git fetch upstream

# Rebase your branch
git rebase upstream/main

Testing

Frontend Tests

cd app

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Backend Tests

cd orchestrator
source .venv/bin/activate

# Run all tests
pytest

# Run specific test file
pytest tests/test_agents.py

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=app --cov-report=html

Manual Testing

Test User Flow

Create a new account
Create a project
Chat with AI agent
Verify code generation
Check live preview

Test Edge Cases

Empty inputs
Invalid data
Network errors
Long-running operations

Browser Testing

Test in multiple browsers:

Chrome
Firefox
Safari (if on Mac)
Edge

Debugging

Frontend Debugging

React DevTools
Console Logging
VS Code Debugger

Install React DevTools extension:

Use to inspect:

Component tree
Props and state
Performance

Add debug logs:

console.log('Debug:', variable);
console.table(array);
console.group('Component Render');
console.log('Props:', props);
console.groupEnd();

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Frontend",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/app/src"
    }
  ]
}

Set breakpoints and press F5.

Backend Debugging

Print Debugging
pdb Debugger
VS Code Debugger

print(f"Debug: {variable}")
logger.debug(f"Processing {item}")

Add breakpoint:

import pdb; pdb.set_trace()

Commands:

n - Next line
s - Step into
c - Continue
p variable - Print variable
q - Quit

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Backend",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "app.main:app",
        "--reload",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "cwd": "${workspaceFolder}/orchestrator"
    }
  ]
}

Set breakpoints and press F5.

Common Tasks

Reset Database

docker compose down -v
docker compose up -d postgres
docker compose exec orchestrator python scripts/migrations/create_tables.py

View Container Logs

# All logs
docker compose logs -f

# Specific service
docker compose logs -f orchestrator
docker compose logs -f app

Access Database

docker compose exec postgres psql -U tesslate -d tesslate_db

Useful SQL commands:

\dt                    -- List tables
\d users              -- Describe table
SELECT * FROM users;  -- Query data

Clean Docker Resources

# Stop all containers
docker compose down

# Remove all volumes
docker compose down -v

# Remove unused images
docker system prune -a

Contributing Workflow

Create Feature Branch

git checkout -b feature/amazing-feature

Make Changes

Write code, add tests, update docs.

Test Locally

Run all tests and manual testing.

Commit Changes

git add .
git commit -m "feat: add amazing feature"

Follow commit message conventions.

Push to Fork

git push origin feature/amazing-feature

Create Pull Request

Go to your fork on GitHub
Click “Pull Request”
Fill in the template
Link related issues

Next Steps

Custom Agents

Learn how to build custom AI agents

Best Practices

Follow coding standards and conventions

API Reference

Explore the REST API

Architecture

Understand the system design

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

Overview

Prerequisites

Node.js & npm

Python & uv

Docker Desktop

Git

Fork and Clone

Install Dependencies

Configure Environment

Development Modes

Full Docker Mode

Hybrid Mode (Recommended)

Project Structure

Making Changes

Create a Feature Branch

Make Your Changes

Keep Your Branch Updated

Testing

Frontend Tests

Backend Tests

Manual Testing

Debugging

Frontend Debugging

Backend Debugging

Common Tasks

Contributing Workflow

Next Steps

Custom Agents

Best Practices

API Reference

Architecture

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

​Overview

​Prerequisites

Node.js & npm

Python & uv

Docker Desktop

Git

​Fork and Clone

​Install Dependencies

​Configure Environment

​Development Modes

​Full Docker Mode

​Hybrid Mode (Recommended)

​Project Structure

​Making Changes

​Create a Feature Branch

​Make Your Changes

​Keep Your Branch Updated

​Testing

​Frontend Tests

​Backend Tests

​Manual Testing

​Debugging

​Frontend Debugging

​Backend Debugging

​Common Tasks

​Contributing Workflow

​Next Steps

Custom Agents

Best Practices

API Reference

Architecture

Overview

Prerequisites

Fork and Clone

Install Dependencies

Configure Environment

Development Modes

Full Docker Mode

Hybrid Mode (Recommended)

Project Structure

Making Changes

Create a Feature Branch

Make Your Changes

Keep Your Branch Updated

Testing

Frontend Tests

Backend Tests

Manual Testing

Debugging

Frontend Debugging

Backend Debugging

Common Tasks

Contributing Workflow

Next Steps