Skip to main content

​
What is a Project?

A project in Tesslate Studio is a complete, containerized application environment. Each project gets its own isolated infrastructure, including source code, running containers, a live preview, AI chat history, and optional version control. Under the hood, every project is stored as a database record with a unique slug (auto-generated from the name, for example my-app-k3x8n2), an owner_id, and an environment_status that tracks whether its containers are running or paused.

Source Code

All your files, components, and assets live inside the project

Containers

One or more isolated services (frontend, backend, database) managed by Tesslate

Chat History

Conversations with AI agents are saved per project

Git Integration

Optional connection to GitHub, GitLab, or Bitbucket

​
Project Structure

Projects in Tesslate Studio are not limited to a single framework or file layout. When you create a project from the default template, you get a React + Vite starter: 
my-project/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── components/
│   ├── styles/
│   └── assets/
├── public/
├── package.json
├── vite.config.ts
└── tsconfig.json
However, when you use a marketplace base or import from a repository, the structure matches that base’s framework (Next.js, FastAPI, Django, Go, and so on).

​
How Projects Are Created

There are three ways to start a new project:

Template

Blank React + Vite starter, ready to customize

Git Import

Import from GitHub, GitLab, or Bitbucket

Base

Pre-built template from the Marketplace with a defined tech stack
When you create a project, Tesslate runs a background task that sets up the project directory, copies or clones files, generates container configuration, and returns the project slug so you can navigate to the builder.
For a detailed walkthrough of each creation method, see Creating Projects.

​
Multi-Container Projects

Tesslate Studio supports monorepo-style projects with multiple containers. Each container represents an isolated service that runs inside Docker or Kubernetes.

Base Containers

User application code created from marketplace bases. Examples: React frontend, FastAPI backend, Next.js app.

Service Containers

Infrastructure services like PostgreSQL, Redis, or RabbitMQ. Identified by a service_slug such as postgres or redis.

​
Container Types and Deployment Modes

Each container has two key properties that determine how it runs:
Base (container_type = "base"): Application code. Created from a marketplace base template. Runs your frontend, backend, or API server.Service (container_type = "service"): Infrastructure. Pre-configured database, cache, or message queue. Uses a known service_slug (for example, postgres, redis, rabbitmq).

​
Container Connections

Connections define how containers communicate. They appear as edges on the architecture graph (powered by React Flow) and are used to generate Docker Compose files or Kubernetes manifests.
  • env_injection: Inject environment variables from one container to another (for example, passing DATABASE_URL from a Postgres service to a backend)
  • http_api: HTTP-based API connection between services
  • database: Direct database connection with credentials
  • message_queue: Message broker connection (RabbitMQ, Kafka)
  • websocket: WebSocket connection between services
  • cache: Cache connection (Redis, Memcached)
  • depends_on: Generic startup dependency (container B must start after container A)
Frontend (React) ──env_injection──▶ Backend (FastAPI) ──database──▶ PostgreSQL
All containers in a project share a common network. In Docker mode, this is a Docker network named tesslate-{slug}. In Kubernetes mode, all pods run in the same namespace (proj-{uuid}) and communicate via service names.

​
Adding Containers to a Project

1

Open the Architecture Panel

In your project workspace, switch to the architecture view to see the React Flow graph canvas.
2

Add a Container

Click Add Container and choose a base from the marketplace or a service type (PostgreSQL, Redis, etc.).
3

Position and Connect

Drag the new container node into position. Draw edges to other containers to define connections.
4

Configure

Set environment variables, ports, and connection details. For external services, provide the endpoint URL and credentials.
5

Start

Start the container individually or start all containers at once.

​
Project Lifecycle

Every project has an environment_status that tracks the state of its container infrastructure.
1

Creation

Background task sets up the project directory, clones files, and registers containers in the database. Status begins as starting.
2

Active

Containers are running and the project is fully accessible. The live preview is available, and AI agents can read and write files.
3

Stopping

When a project goes idle or you manually stop it, containers begin shutting down. In Kubernetes mode, files may be archived to storage.
4

Hibernated

Containers are stopped and project files are preserved. In Kubernetes, an EBS VolumeSnapshot or S3 archive stores the project state. Restarting restores from the snapshot.
active ──▶ stopping ──▶ hibernated
hibernated ──▶ starting ──▶ active
Hibernation happens automatically after a configurable idle timeout (default: 30 minutes). This saves resources without losing any of your work. When you return, the project restores and picks up where you left off.

​
Container Orchestration

Tesslate Studio supports two deployment modes for running project containers. The platform uses a factory pattern so that all code interacts with the same abstract interface, regardless of which mode is active.
How it works: Tesslate generates a docker-compose.yml for each project and runs docker-compose up. Containers communicate over a shared Docker network.Routing: Traefik reverse proxy routes traffic to containers. Preview URLs follow the pattern:
{project-slug}-{container-name}.localhost
File access: Direct filesystem access through a shared volume mounted at /projects/{slug}.Volume isolation: Uses Docker Compose v2.23.0+ volume.subpath to isolate each project’s files within a shared volume.Best for: Local development and testing.

​
Port Resolution

Every container has an effective_port property that determines which port the dev server listens on. The resolution order is:
  1. internal_port (set from TESSLATE.md or framework detection during project creation)
  2. port (the exposed/mapped port)
  3. 3000 (last-resort default)
Always rely on effective_port rather than hardcoding port values. At startup, the orchestrator also checks for a TESSLATE.md file in the project root, which can override the port at runtime.

​
Project Management

​
Dashboard

All your projects appear on the Dashboard page with status indicators and quick actions:
  • Grid view with project cards showing name, status, and last activity
  • Status phases: Idea, Build, or Launch (user-defined organizational labels)
  • Quick actions: Open, delete, or fork a project

​
Opening a Project

Click any project card to enter the builder workspace, which includes:
  • Code editor (Monaco)
  • Live preview (iframe)
  • Chat interface (AI agents)
  • Architecture graph (React Flow canvas)
  • File browser, terminal, kanban board, and asset manager

​
Deleting Projects

Deleting a project is permanent. All code, containers, chat history, and assets will be removed. In Kubernetes mode, the entire project namespace is deleted, including persistent volumes.
1

Hover over the project card on the Dashboard

2

Click the trash icon

3

Confirm deletion in the dialog

​
Working with Files

​
File Operations

  • Create: AI agents auto-create files, or create them manually in the file tree
  • Edit: Use the Monaco code editor with full IntelliSense
  • Save: Files save to the container filesystem. The API call is projectsApi.saveFile(slug, filePath, content).
  • Delete: Remove files through the file tree or via projectsApi.deleteFile(slug, filePath)

​
Assets

Binary files (images, fonts, videos, documents) are managed separately through the Assets panel. Each asset is tracked in the database with metadata including filename, MIME type, dimensions (for images), and file size.
  • Code: .tsx, .jsx, .ts, .js, .css, .scss, .json
  • Images: PNG, JPG, SVG, GIF, WebP
  • Fonts: TTF, WOFF, WOFF2, OTF
  • Documents: PDF, TXT, Markdown

​
Project Settings

Access settings through the gear icon in the project workspace:
  • Normal: Single browser view in the preview panel
  • Browser Tabs: Multiple tab support for testing multi-page navigation
  • View container status (running, stopped, failed)
  • Restart individual containers or all containers at once
  • Check the assigned preview URL
  • Project name and description
  • Status phase (Idea, Build, Launch)
  • Architecture diagram settings

​
Best Practices

Before adding containers, decide which services your project needs. A typical full-stack project might include a frontend (React), a backend (FastAPI or Express), and a database (PostgreSQL). Define your connections up front to avoid reconfiguring later.
Connect your project to GitHub, GitLab, or Bitbucket early. Commit regularly so you have a history to roll back to if needed. Tesslate also supports project hibernation, which preserves your state automatically.
Name your containers clearly (for example, frontend, api, database) so the architecture graph is easy to understand. Use meaningful project names that describe the application.
If a container fails to start automatically (common with community bases that do not include a TESSLATE.md file), use the “Ask Agent to start it” button. The AI agent will inspect the project files and run the correct startup command.

​
Next Steps

Create Your First Project

Step-by-step guide to creating a project from template, Git, or base

Code Editor

Learn how to use the Monaco-powered code editor

Live Preview

Understand how container-based live preview works

Git Integration

Connect to GitHub, GitLab, or Bitbucket