teta.so
Sign in

Architecture

Teta is built as a three-tier system: a SvelteKit frontend, an Express.js backend, and isolated cloud sandboxes where your code actually runs. This page explains how these layers work together to deliver an AI-powered development experience.

High-level overview

The architecture follows a clear separation of concerns:

  1. Frontend — The browser-based editor where you chat with the AI, preview your app, edit code, and manage your project.
  2. Backend — An Express.js service that orchestrates the AI agent, manages sandbox lifecycles, handles authentication, and routes deployments.
  3. Sandboxes — Isolated cloud containers (powered by E2B) where your SvelteKit app runs, the AI agent operates, and all file changes happen.
Browser (SvelteKit frontend)
    |
    |  HTTPS + Supabase Realtime
    v
Express.js backend
    |
    |  WebSocket + REST
    v
E2B Sandbox (SvelteKit dev server + AI agent + VS Code)

Each layer communicates through well-defined protocols, and real-time updates flow back to the browser so you see changes as they happen.

Frontend

The frontend is a SvelteKit 5 application built with Svelte 5 runes. It provides the main editor interface, which includes:

  • Chat panel — Send messages to the AI agent and see responses streamed in real time. Supports multiple chat tabs, each with its own independent agent session.
  • Preview iframe — A live preview of your running SvelteKit app, served directly from your sandbox. Changes made by the AI agent are reflected immediately via hot module replacement (HMR).
  • Code editor — A full VS Code instance (code-server) running inside your sandbox, embedded in the editor for direct file access.
  • Console — View build logs, server output, and error messages from your sandbox in real time.

The frontend uses Supabase for authentication and Supabase Realtime broadcast channels for live communication with the backend. The Supabase client is threaded through components via props rather than being a global singleton.

Backend

The Express.js backend is the orchestration layer. It handles:

  • AI agent management — Starts and manages Claude Code CLI sessions inside sandboxes. Each chat tab gets its own agent session, and a single WebSocket connection to the sandbox multiplexes messages by chat ID.
  • Sandbox lifecycle — Creates, reconnects, and manages E2B sandbox containers. Handles sandbox caching, snapshot/restore, and cleanup.
  • Authentication — Validates JWTs from Supabase Auth, ensures users can only access their own projects and sandboxes.
  • Deployment — Orchestrates builds and deployments when you're ready to ship your app.
  • MCP configuration — Deploys Model Context Protocol server configurations to sandboxes so the AI agent has access to tools like image generation, browser interaction, and web search.

The backend communicates with sandboxes via WebSocket connections and with the frontend via both REST endpoints and Supabase Realtime broadcast.

Sandboxes

Sandboxes are isolated cloud containers powered by E2B. Each project gets its own sandbox that runs:

  • A SvelteKit dev server with hot-reload, so your app preview updates instantly.
  • A code-server (VS Code) instance for direct code editing.
  • The Claude Code CLI as the AI agent, with access to the full project file system.
  • MCP tool servers for specialized capabilities like image generation and browser interaction.

Sandboxes are created when you open a project and cached for 10 minutes of inactivity. If your sandbox expires, Teta automatically reconnects or creates a new one and restores your files.

Data flow

Here is the typical flow when you send a message to the AI agent:

  1. You type a message in the chat panel and press send.
  2. The frontend posts the message to the backend via REST API.
  3. The backend forwards the message to the Claude Code CLI agent session running inside your sandbox via WebSocket.
  4. The agent reads your project files, decides what to do, and starts making changes — editing files, running commands, installing packages.
  5. Each action is streamed back through the WebSocket to the backend.
  6. The backend broadcasts updates to the frontend via a Supabase Realtime channel (app_{projectId}).
  7. The frontend renders the agent's responses, and the preview iframe updates automatically through SvelteKit's HMR.

This pipeline means you see the agent's work in real time: file edits appear in the code editor, build output appears in the console, and your app preview refreshes with each change.

Real-time communication

Teta uses Supabase Realtime broadcast channels as the primary communication layer between the backend and frontend. Each project has a dedicated channel (app_{projectId}) that carries:

  • message_added — New chat messages from the AI agent.
  • build_log — Console output and build logs from the sandbox.
  • url_changed — Preview URL updates when the sandbox restarts.
  • chat_error — Error notifications when something goes wrong.
  • tool_approval — Requests for user approval in supervised mode.

Broadcast channels provide low-latency, bidirectional communication without requiring the frontend to maintain a direct WebSocket connection to the sandbox.

Security model

Security is enforced at every layer:

  • Authentication — All API requests require a valid JWT from Supabase Auth. The backend validates tokens before processing any request.
  • Sandbox isolation — Each project runs in its own E2B container with no network access to other sandboxes. There is no cross-project file access.
  • Encrypted secrets — Environment variables and API keys are encrypted at rest and injected into sandboxes at runtime. They are never exposed to the frontend.
  • Tool approval — In supervised mode, every file write, edit, or terminal command by the AI agent requires explicit user approval before execution.
  • Row-Level Security — Supabase RLS policies ensure users can only read and write their own project data.

FAQ

How does real-time preview work without page refreshes?

The SvelteKit dev server running in your sandbox supports hot module replacement (HMR). When the AI agent edits a file, Vite detects the change and pushes an update to the preview iframe over a WebSocket. The browser applies the change without a full page reload, preserving your application state.

What happens if the backend goes down?

If the backend becomes temporarily unavailable, your sandbox continues running independently. The SvelteKit dev server and VS Code remain accessible. When the backend comes back, it reconnects to existing sandboxes. Any in-flight AI agent sessions would need to be restarted, but your code is preserved in the sandbox.

Can multiple people work on the same project simultaneously?

Each project has a single sandbox, and the current architecture is designed for individual use. Multiple browser tabs from the same account can connect to the same project, but concurrent editing from different users is not currently supported.

Why Supabase Realtime instead of direct WebSockets?

Supabase Realtime broadcast provides a managed, scalable pub/sub layer that handles reconnection, authentication, and message routing out of the box. It eliminates the need to maintain persistent WebSocket connections between the browser and the backend, and it integrates naturally with Supabase Auth for secure channel access.

Is my code stored on the backend server?

No. Your code lives inside your sandbox container and in your deployment target. The backend orchestrates operations but does not store your project files. Project metadata (names, settings, chat history) is stored in Supabase, but the source code itself remains in the sandbox and is synced during deployment.