Skip to main content

​
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

1

Fork the Repository

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

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/Studio.git
cd Studio
Replace YOUR-USERNAME with your GitHub username.
3

Add Upstream Remote

git remote add upstream https://github.com/TesslateAI/Studio.git
This lets you pull latest changes from the main repository.
4

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

​
Configure Environment

1

Copy Environment File

cp .env.example .env
2

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))"
3

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
Best for: Active development with instant feedback
1

Start Infrastructure

docker compose up -d traefik postgres
This starts only Traefik and PostgreSQL.
2

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.
3

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
  1. Edit files in app/src/
  2. Changes auto-reload in browser (HMR)
  3. Check browser console for errors
  4. Test in different screen sizes

​
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

1

Test User Flow

  1. Create a new account
  2. Create a project
  3. Chat with AI agent
  4. Verify code generation
  5. Check live preview
2

Test Edge Cases

  • Empty inputs
  • Invalid data
  • Network errors
  • Long-running operations
3

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

​
Backend Debugging

​
Common Tasks

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

# All logs
docker compose logs -f

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

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

# Stop all containers
docker compose down

# Remove all volumes
docker compose down -v

# Remove unused images
docker system prune -a

​
Contributing Workflow

1

Create Feature Branch

git checkout -b feature/amazing-feature
2

Make Changes

Write code, add tests, update docs.
3

Test Locally

Run all tests and manual testing.
4

Commit Changes

git add .
git commit -m "feat: add amazing feature"
Follow commit message conventions.
5

Push to Fork

git push origin feature/amazing-feature
6

Create Pull Request

  1. Go to your fork on GitHub
  2. Click “Pull Request”
  3. Fill in the template
  4. 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