Core Concepts

Here is a quick overview of each concept before we dive in:

Components

A component is the fundamental unit. It represents any discrete part of your system: a microservice, a database, a load balancer, a frontend app, a message queue, etc.

Properties

Every component carries these properties:

• Name — the display label shown above the 3D block (e.g. "Auth Service")
• Type — a category and template from the component library (e.g. "API/Express", "Database/PostgreSQL")
• Layer — which group the component belongs to (determines its color)
• Tech — technology stack, as a comma-separated list (e.g. "Node.js, Express, TypeScript")
• Description — free-form text explaining what this component does
• Constraints — requirements or limitations (e.g. "max 1000 req/s", "read-only replica")
• Position — coordinates on the horizontal grid (x, z), set by drag-and-drop

Visual appearance

Each component's 3D shape and look are determined by its type in the Component Library. The component is also color-coded by its layer and displays a label above it with its name and type.

Layers

Layers organize components into logical groups. Each layer has its own color, making it easy to see at a glance which tier each component belongs to in the 3D scene.

Every new project starts with four default layers:

When you assign a component to a layer, it takes on that layer's color, making it immediately identifiable on the canvas.

The Layer Legend in the top-left corner of the editor shows all layers with their colors. Pro users can double-click the legend to open the Layer Editor and customize layers: rename, change colors, reorder, add new layers, or delete existing ones. Renaming or deleting a layer automatically updates all components that use it. See Editor Interface for details.

Connections

A connection is a link between two components. It represents communication (HTTP, gRPC, WebSocket), data flow, or a dependency relationship.

Properties

• From / To — the source and target components
• Protocol — the communication method (displayed as a label at the midpoint of the line)
• Description — additional context about what flows through this connection
• Bidirectional — whether the link goes both ways

Visual representation

Connections appear as lines between the centers of two component blocks. A small text label at the midpoint shows the protocol. An arrow indicates direction, unless the connection is bidirectional.

Connections follow their components automatically when you drag them to a new position. If a component is deleted, all its connections are removed as well.

Connections can link components from different layers (e.g. a frontend app calling an API gateway), making dependencies visible at a glance.

Subgraphs

Any component can contain a nested architecture inside it, called a subgraph. This is how Tesseract supports multi-level, hierarchical system design.

How it works

1. Double-click a component to zoom into its subgraph
2. Inside, you see a new canvas with its own components, connections, and layers
3. A breadcrumb bar at the top shows your current path (e.g. / > API Gateway > Auth Module)
4. Click any breadcrumb, press Escape / Backspace, or double-click the ground to navigate back up

Subgraphs can be nested to any depth. A top-level system overview can zoom into a service cluster, which itself contains individual microservices, each with their own internal modules.

The Architecture Graph

Components, connections, and subgraphs form the Architecture Graph — the data structure that holds your entire design:

components     // list of all components at this level
connections    // links between components
subgraphs      // nested architectures inside components (via children)
flows          // saved data flow paths (optional)

Each component's optional children field holds another Architecture Graph — the subgraph. This recursive structure is what makes multi-level navigation possible.

The whole graph is persisted as a single .tesseract.json file.

Flows

A flow is an optional overlay that highlights a specific data path through your architecture. Flows let you visualize how a request travels from one component to another, step by step.

Each flow contains one or more paths, each with its own color. A path is a sequence of segments that follow existing connections. When activated, the segments light up on the canvas, making it easy to trace the journey of a request or event through your system.

Flows are especially useful for:

• Onboarding — walk new team members through critical paths
• Debugging — trace an issue by following the data path
• Documentation — record and share common request flows
• Architecture reviews — highlight what changes when a component is modified

Learn more about creating and using flows in the Data Flows guide.