Skip to main content

​
Overview

Architecture Diagrams in Tesslate Studio let you visualize your project’s multi-container structure, dependency graphs, and data flow. Built on top of React Flow (XYFlow), diagrams are interactive, AI-generated, and directly tied to your live project containers.

React Flow Powered

Interactive graph canvas with drag, zoom, and pan

AI Generated

AI analyzes your code and creates diagrams automatically

Live Containers

Diagrams reflect running containers and their connections

Export Ready

Download as PNG, SVG, or JSON for documentation

​
How Diagrams Work

Tesslate Studio uses a graph canvas built on React Flow to render architecture diagrams. Each container in your project becomes a node, and connections between containers become edges.
1

Project Analysis

When you open a project, Tesslate reads the container definitions and their connections from the database. Each Container model has position coordinates (position_x, position_y) stored for layout persistence.
2

Node Generation

Each container is rendered as a custom ContainerNode inside the React Flow canvas. Node data includes the container name, status (running, stopped, building), port, and framework type.
3

Edge Mapping

ContainerConnection records define edges between nodes. These represent networking dependencies, such as a frontend container connecting to a backend API container.
4

Live Preview Nodes

BrowserPreview nodes can be attached to containers, showing a live iframe preview of the running application directly on the canvas.
5

AI Enhancement

Ask the AI agent to generate or refine diagrams. The agent uses the diagram_model preference (configurable per user) to analyze your codebase and produce visual output.
First-time diagram generation may take 30 to 60 seconds while the AI analyzes your entire project structure.

​
Multi-Container Project Visualization

Tesslate projects can contain multiple containers (frontend, backend, database, cache, etc.), and the architecture diagram shows how they all connect.
Each container appears as a node on the canvasNode data includes:
  • Container name and type (base or service)
  • Framework (React, Next.js, FastAPI, etc.)
  • Running status with live indicators
  • Port information (the effective_port property resolves internal_port, then port, then defaults to 3000)
  • Deployment mode (container or external)
Nodes are draggable; positions persist to the database.

​
Diagram Types

Project infrastructure viewShows all containers in your project, how they connect, and their current status. This is the primary diagram type, rendered automatically when you open a project.Best for: Understanding project architecture at a glance

​
Interactive Features

Click to Navigate

Click container nodes to open their files in the code editor

Zoom and Pan

Scroll to zoom, drag the canvas to pan around large diagrams

Drag to Reposition

Drag nodes to rearrange; positions save automatically

Live Status

Nodes show real-time container status (running, stopped, error)

​
Customization

  • Color schemes follow your active theme (dark or light mode)
  • Layout direction: vertical or horizontal
  • Adjustable spacing and sizing
  • Node styles adapt to container type
  • Show or hide service containers (databases, caches)
  • Filter by container type (base vs. service)
  • Focus on specific containers
  • Collapse or expand grouped sections
You can choose which AI model generates your diagrams. Go to Settings > Preferences and set your preferred diagram_model. The model processes your codebase and outputs structured diagram data.

​
Generating AI Diagrams

​
Natural Language Requests

Ask the AI agent to generate or modify diagrams:
  • “Show me the full architecture of this project”
  • “Diagram how authentication works across the frontend and API”
  • “Visualize the data flow from the shopping cart to Stripe checkout”
  • “Show only the containers that connect to the database”
  • “Create a component tree for the dashboard page”

​
Refining Diagrams

  • “Include the port numbers on each container node”
  • “Show which containers fetch data from external APIs”
  • “Add the database schema to the diagram”

​
Exporting Diagrams

1

Open the Diagram

View the architecture diagram you want to export
2

Click Export

Click the Export button in the diagram toolbar
3

Choose Format

  • PNG: For documents, presentations, and READMEs
  • SVG: For scalable web graphics
  • JSON: For re-importing the diagram layout later
4

Adjust Settings

Set resolution, background color, and included area
5

Download

Save the exported file to your computer

​
Technical Details

For developers who want to understand the underlying implementation:
The graph canvas uses @xyflow/react (React Flow) with custom node types:
  • containerNode: Renders a ContainerNode component with status, port, and framework info
  • browserPreview: Renders a BrowserPreviewNode with an embedded iframe
Node types are registered via the nodeTypes object passed to the ReactFlow component.
Three database models power the diagram:
  • Container: Stores position_x, position_y, name, port, internal_port, container_type, and status
  • ContainerConnection: Stores source_container_id, target_container_id, connector_type, and config (JSON)
  • BrowserPreview: Stores connected_container_id, position_x, position_y, and current_path
The auto-layout utility in autoLayout.ts uses the Dagre directed graph layout library to compute optimal node positions. It considers:
  • Edge direction (top to bottom or left to right)
  • Node dimensions
  • Connection density
  • Minimum spacing between nodes

​
Use Cases

​
Onboarding New Developers

1

Generate Overview

Open the project and let the container graph render automatically
2

Explain Architecture

Walk through each container and its role in the system
3

Show Data Flow

Ask AI to generate a data flow diagram across containers
4

Export for Docs

Export the diagram as PNG and include it in your project README

​
Refactoring

  1. Current State: Open the architecture diagram to see the existing container structure
  2. Identify Issues: Spot unnecessary connections, missing services, or overly coupled containers
  3. Plan Changes: Use the AI to sketch a proposed architecture
  4. Refactor: Make changes to your containers and connections
  5. Verify: Refresh the diagram to confirm the improved structure

​
Troubleshooting

Solutions:
  • Ensure the project has at least one container
  • Check that containers have valid position data
  • Refresh the page to reload the React Flow canvas
  • Verify the project is in “active” or “running” status
Solutions:
  • Use the visibility filters to hide service containers
  • Generate feature-specific diagrams instead of full project views
  • Use the auto-layout to clean up overlapping nodes
  • Split visualization into multiple focused diagrams
Solutions:
  • Click the “Auto Layout” button to recalculate positions
  • Manually drag nodes to better positions (positions save automatically)
  • Adjust layout direction from vertical to horizontal
Solutions:
  • Verify the connected container is running
  • Check that the container’s port is accessible
  • Refresh the browser preview node
  • Ensure the dev server inside the container has started

​
Best Practices

Start with the Container Graph

The default container graph gives you the best high-level overview before drilling into specifics

Use Descriptive Container Names

Container names appear in diagram nodes, so clear names improve readability

Export for Documentation

Include architecture diagrams in your README and project docs

Refresh After Changes

Regenerate diagrams after adding or removing containers to keep visuals current

​
Next Steps

Projects

Learn about project structure and containers

Code Editor

Navigate your codebase from diagram nodes

Using Agents

Let AI generate and refine architecture diagrams

GitHub Integration

Include diagrams in your repository