# tenstorrent/tt-studio architecture

> Architecture diagram of the GitHub repository tenstorrent/tt-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tenstorrent/tt-studio
- Repository: https://github.com/tenstorrent/tt-studio

## Overview

##### Project Type and Purpose
- TT-Studio is a full-stack application designed to deploy TT Inference servers locally—with special support for Tenstorrent hardware. The project provides both production and development workflows, containerized via Docker, and integrates a frontend (built with modern web technologies like React/Vite) with a backend (built on Django and Django Rest Framework). It also supports models (like a dummy echo model and vLLM models) and provides extensive support modules (e.g., agent, docker, logs, vector database controls).

##### File Structure to Identify Key Components
- Top-level Directories:
- “app” – Contains the main application components.
- Within “app”, separate directories exist for “api” (backend) and “frontend” (UI).
- Backend (“app/api”):
- Contains various Django sub-applications such as:
- agent_control: Handles AI agent integrations and custom LLM logic.
- docker_control: Manages Docker operations (with a dedicated UI via Django templates).
- model_control: Manages model configuration, deployment, and API endpoints.
- logs_control: Offers logs monitoring endpoints.
- vector_db_control: Manages vector database interactions, likely for storing/retrieving model contexts or embeddings.
- Additionally, “shared_config” holds configuration modules that standardize logger setups, model configurations, and device setups.
- Uses Dockerfiles and docker-compose files to containerize the backend.
- Frontend (“app/frontend”):
- Contains all the source code (React/Vite based) for user interface components including pages for chat UI, image generation, object detection, logs, and models.
- Supports live reloading and integration with the backend API.
- Models Directory:
- Contains the “dummy_echo_model” which demonstrates how inference models are managed and deployed.
- Other Components:
- The “startup.sh” script and associated documentation in the README ensure that the environment can be quickly bootstrapped. The configuration for Tenstorrent hardware (mounting /dev/tenstorrent) is managed through Docker Compose configurations.

a. Main Components to Represent:
- Frontend Service:
- Represented as a containerized service with its dedicated Dockerfile.
- Labeled “Frontend (React/Vite)” or “UI Application.”
- Components like pages (Chat UI, ImageGen, Object Detection, etc.) as subdivisions if necessary.
- Backend API Service:
- Represented as a container “Backend (Django/DRF).”
- Subdivide into logical modules:
- Agent Control Module
- Docker Control Module
- Model Control Module
- Logs Control Module
- Vector DB Control Module
- Shared Configuration (supporting all modules)
- Inference/Model Service:
- A separate component for deployed models (e.g., the dummy echo model). This may be shown as an independently containerized service or as a component within the “models” ecosystem.
- Data/Configuration Components:
- Docker Compose set-up that orchestrates communication between frontend, backend, and model containers.
- Tenstorrent Hardware (depicted as an external resource) that connects to the backend container through volume/mount configurations.

b. Relationships and Interactions:
- The Frontend making HTTP requests to the Backend API.
- The Backend interfacing with sub-modules (agent, docker, model, logs, vector DB controls).
- The Backend (or specific model control module) connecting to the inference model service.
- If applicable, connections or dependencies between the backend and persistence layers (database – even if implicit in Django’s ORM).

c. Architectural Patterns:
- The project uses containerization (Docker) and orchestration (docker-compose), typical in a microservices-inspired approach.
- The backend is structured in a modular fashion using Django apps based on functionality.
- Hot-reloading and volume mounting for development environments.
- Mention that there is a clear separation between frontend and backend responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Orchestration Layer
    subgraph "Docker Orchestration"
        DC1["Docker Compose (Standard)"]:::orchestration
        DC2["Docker Compose (TT Hardware)"]:::orchestration
    end

    %% Main Container Nodes
    UI["Frontend (React/Vite)"]:::frontend
    BContainer["Backend (Django/DRF)"]:::backend
    Inference["Inference/Model Service (Dummy Echo)"]:::service
    Hardware["Tenstorrent Hardware"]:::hardware

    %% Backend Modules Subgraph
    subgraph "Backend Modules"
        B_Agent["Agent Control Module"]:::module
        B_Docker["Docker Control Module"]:::module
        B_Model["Model Control Module"]:::module
        B_Logs["Logs Control Module"]:::module
        B_Vector["Vector DB Control Module"]:::module
        Shared["Shared Configuration"]:::module
    end

    %% Connections from Orchestration to Containers
    DC1 --> UI
    DC1 --> BContainer
    DC1 --> Inference
    DC2 --> UI
    DC2 --> BContainer
    DC2 --> Inference

    %% Interactions between Frontend and Backend
    UI -->|"HTTP"| BContainer

    %% Backend container configures its internal modules
    BContainer -->|"configures"| B_Agent
    BContainer -->|"configures"| B_Docker
    BContainer -->|"configures"| B_Model
    BContainer -->|"configures"| B_Logs
    BContainer -->|"configures"| B_Vector
    BContainer -->|"uses"| Shared

    %% Model Control Module calls the Inference Service
    B_Model -->|"calls"| Inference

    %% Backend mounts Tenstorrent Hardware support via volume configurations
    BContainer -->|"mounts"| Hardware

    %% Style definitions
    classDef frontend fill:#a2d2ff,stroke:#023e8a,stroke-width:2px;
    classDef backend fill:#bde0fe,stroke:#03045e,stroke-width:2px;
    classDef module fill:#ffffb3,stroke:#b58900,stroke-width:2px;
    classDef service fill:#aff8db,stroke:#2ec4b6,stroke-width:2px;
    classDef orchestration fill:#ffc8dd,stroke:#ff758f,stroke-width:2px;
    classDef hardware fill:#ffafcc,stroke:#ff477e,stroke-width:2px;

    %% Click Events mapping
    click UI "https://github.com/tenstorrent/tt-studio/tree/main/app/frontend"
    click BContainer "https://github.com/tenstorrent/tt-studio/tree/main/app/api"
    click B_Agent "https://github.com/tenstorrent/tt-studio/tree/main/app/api/agent_control"
    click B_Docker "https://github.com/tenstorrent/tt-studio/tree/main/app/api/docker_control"
    click B_Model "https://github.com/tenstorrent/tt-studio/tree/main/app/api/model_control"
    click B_Logs "https://github.com/tenstorrent/tt-studio/tree/main/app/api/logs_control"
    click B_Vector "https://github.com/tenstorrent/tt-studio/tree/main/app/api/vector_db_control"
    click Shared "https://github.com/tenstorrent/tt-studio/tree/main/app/api/shared_config"
    click Inference "https://github.com/tenstorrent/tt-studio/tree/main/models/dummy_echo_model"
    click DC1 "https://github.com/tenstorrent/tt-studio/blob/main/app/docker-compose.yml"
    click DC2 "https://github.com/tenstorrent/tt-studio/blob/main/app/docker-compose.tt-hardware.yml"
```
