# tessera-ui/tessera architecture

> Architecture diagram of the GitHub repository tessera-ui/tessera, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tessera-ui/tessera
- Repository: https://github.com/tessera-ui/tessera

## Overview

1. This is a Rust monorepo organized around a cross-platform UI framework called Tessera, plus a set of companion crates and tools. The main architectural split is between runtime/rendering, reusable UI components, state/routing, platform integration, and build/CLI tooling.

2. The core runtime lives in `tessera-ui`. It is the central execution boundary for apps: declarative component functions are turned into a component tree, laid out, converted into a render graph/scene, and then rendered through a GPU-backed renderer. This crate also owns input and session state such as focus, keyboard, IME, cursor, scroll, timing, profiling, and test support.

3. `tessera-macros` provides the procedural macro entry point used by application code. Its role is to transform user-authored component functions into the form the runtime can execute, so the app author writes declarative UI while the macro bridges that to `tessera-ui`’s execution model.

4. `tessera-components` is the reusable widget layer. It contains higher-level primitives such as buttons, text, layout containers, navigation, dialogs, text fields, sliders, scrollables, and glass/material-style controls. It also includes shader-backed rendering pipelines under `src/pipelines`, so many components are not just layout wrappers but own their own rendering behavior.

5. `tessera-foundation` is the low-level support layer beneath components. It defines core concepts such as alignment, gestures, shapes, and modifier semantics/layout/interaction. This crate is the shared vocabulary for layout and interaction across the UI stack.

6. The rendering path is split between the generic renderer in `tessera-ui` and specialized GPU work in `tessera-components`. `tessera-ui` provides the main render engine and render passes, while components contribute specialized draw/compute pipelines and WGSL shaders for effects like blur, shadows, image/vector rendering, progress arcs, and custom glass visuals. The architecture is clearly GPU-first and designed for custom visual effects.

7. `tessera-shard` is a separate application state/navigation subsystem. It provides handle-based state storage, async support, and a router with destinations/controllers/home state. Conceptually, it sits above the UI runtime as an application-level state and navigation layer rather than a rendering layer.

8. `tessera-platform` encapsulates host-platform features that are not part of the pure UI runtime, such as clipboard and window-related integration. It also contains an Android plugin surface, which makes it the boundary where Tessera reaches into platform-specific native services.

9. `tessera-build` is the build-time integration crate. It appears to support embedding backend assets and selecting platform backends, including Android-specific backend logic. This is the bridge between Rust source, generated artifacts, and native platform packaging.

10. Mobile support is handled by `tessera-mobile` and the higher-level `cargo-tessera` CLI. `tessera-mobile` contains project/config parsers, target detection, device/emulator management, platform-specific logic for Android and Apple, and template generation for app/platform scaffolding. `cargo-tessera` exposes user-facing commands like new, build, dev, check, web, android, plugin, and profiling, acting as the workflow front end for the whole workspace.

11. The repository is template-driven for generated apps and platform projects. Under `cargo-tessera/templates` and `tessera-mobile/templates`, the repo stores skeletons for basic/blank apps, plugins, Android Studio projects, and Xcode projects. The generated `example` tree shows the result of this pipeline: a Rust app plus generated Android and web outputs, demonstrating how source code is turned into deployable platform artifacts.

12. The `example` crate is both a demo and an integration test of the architecture. Its `src/pages/*` modules show how app code is organized around pages and custom shaders, while the generated `gen/` directories show the platform-specific wrappers Tessera produces for web and Android.

13. External technology choices materially shape the architecture: `wgpu` for rendering, `winit` for window/event handling, and `glyphon` for text. On mobile, the repo integrates with Android Gradle/NDK and Apple tooling such as Xcode, simulators/devicectl, and ios-deploy. Those platform toolchains are not incidental; they are part of the deployment boundary of the framework.

14. A useful diagram of this repo should therefore show three main planes: application code and macros at the top; shared UI/runtime/component/state crates in the middle; and platform/build/CLI/template tooling around the edges that generates, packages, and launches platform-specific projects.

Main entry points: [`tessera-ui`](https://github.com/tessera-ui/tessera/tree/main/tessera-ui) (UI runtime), [`example`](https://github.com/tessera-ui/tessera/tree/main/example) (Example app), [`tessera-components`](https://github.com/tessera-ui/tessera/tree/main/tessera-components) (Components), [`cargo-tessera`](https://github.com/tessera-ui/tessera/tree/main/cargo-tessera) (cargo-tessera)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App layer"]
  node_example["Example app<br/>demo app"]
end

subgraph group_core["Core UI stack"]
  node_tessera_macros{{"Macros<br/>proc-macro"}}
  node_tessera_ui_runtime["UI runtime<br/>render runtime"]
  node_tessera_ui_tree["Tree builder<br/>component tree<br/>[build_tree.rs]"]
  node_tessera_ui_layout["Layout<br/>[layout.rs]"]
  node_tessera_ui_renderer["Renderer<br/>[renderer.rs]"]
  node_tessera_ui_state["Session state<br/>input/runtime state<br/>[context.rs]"]
  node_tessera_foundation["Foundation<br/>primitives"]
  node_tessera_components["Components<br/>widget crate"]
  node_tessera_components_widgets["Widgets<br/>controls<br/>[lib.rs]"]
  node_tessera_components_pipelines["Pipelines<br/>[pipelines.rs]"]
  node_tessera_shard["Shard<br/>state/router"]
end

subgraph group_tooling["Tooling and platform"]
  node_tessera_platform["Platform<br/>host integration"]
  node_tessera_build["Build bridge<br/>build-time crate"]
  node_cargo_tessera["cargo-tessera<br/>CLI/workflow"]
  node_tessera_mobile["Mobile tooling<br/>mobile workspace"]
end

subgraph group_generated["Generated outputs"]
  node_templates["Templates<br/>scaffolding"]
  node_example_gen["Generated app<br/>generated outputs"]
end

node_example -->|"uses macros"| node_tessera_macros
node_example -->|"runs on"| node_tessera_ui_runtime
node_example -->|"uses widgets"| node_tessera_components
node_example -->|"uses state"| node_tessera_shard
node_tessera_macros -->|"expands for"| node_tessera_ui_runtime
node_tessera_ui_runtime -->|"builds"| node_tessera_ui_tree
node_tessera_ui_tree -->|"feeds"| node_tessera_ui_layout
node_tessera_ui_layout -->|"emits scene"| node_tessera_ui_renderer
node_tessera_ui_runtime -->|"owns state"| node_tessera_ui_state
node_tessera_ui_runtime -->|"depends on"| node_tessera_foundation
node_tessera_components -->|"builds on"| node_tessera_foundation
node_tessera_components -->|"contains"| node_tessera_components_widgets
node_tessera_components -->|"contains"| node_tessera_components_pipelines
node_tessera_components_widgets -->|"drives visuals"| node_tessera_components_pipelines
node_tessera_shard -->|"sits above"| node_tessera_ui_runtime
node_tessera_platform -->|"integrates with"| node_tessera_ui_runtime
node_tessera_build -->|"packages"| node_tessera_platform
node_cargo_tessera -->|"invokes"| node_tessera_mobile
node_cargo_tessera -->|"orchestrates"| node_tessera_build
node_cargo_tessera -->|"generates"| node_templates
node_tessera_mobile -->|"renders"| node_templates
node_example_gen -->|"result of"| node_tessera_mobile
node_example_gen -->|"includes"| node_tessera_platform

click node_example "https://github.com/tessera-ui/tessera/tree/main/example"
click node_tessera_macros "https://github.com/tessera-ui/tessera/tree/main/tessera-macros"
click node_tessera_ui_runtime "https://github.com/tessera-ui/tessera/tree/main/tessera-ui"
click node_tessera_ui_tree "https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/build_tree.rs"
click node_tessera_ui_layout "https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/layout.rs"
click node_tessera_ui_renderer "https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/renderer.rs"
click node_tessera_ui_state "https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/context.rs"
click node_tessera_foundation "https://github.com/tessera-ui/tessera/tree/main/tessera-foundation"
click node_tessera_components "https://github.com/tessera-ui/tessera/tree/main/tessera-components"
click node_tessera_components_widgets "https://github.com/tessera-ui/tessera/blob/main/tessera-components/src/lib.rs"
click node_tessera_components_pipelines "https://github.com/tessera-ui/tessera/blob/main/tessera-components/src/pipelines.rs"
click node_tessera_shard "https://github.com/tessera-ui/tessera/tree/main/tessera-shard"
click node_tessera_platform "https://github.com/tessera-ui/tessera/tree/main/tessera-platform"
click node_tessera_build "https://github.com/tessera-ui/tessera/tree/main/tessera-build"
click node_cargo_tessera "https://github.com/tessera-ui/tessera/tree/main/cargo-tessera"
click node_tessera_mobile "https://github.com/tessera-ui/tessera/tree/main/tessera-mobile"
click node_templates "https://github.com/tessera-ui/tessera/tree/main/cargo-tessera/templates"
click node_example_gen "https://github.com/tessera-ui/tessera/tree/main/example/gen"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_example toneBlue
class node_tessera_macros,node_tessera_ui_runtime,node_tessera_ui_tree,node_tessera_ui_layout,node_tessera_ui_renderer,node_tessera_ui_state,node_tessera_foundation,node_tessera_components,node_tessera_components_widgets,node_tessera_components_pipelines,node_tessera_shard toneAmber
class node_tessera_platform,node_tessera_build,node_cargo_tessera,node_tessera_mobile toneMint
class node_templates,node_example_gen toneRose
```

## Components

### App layer

Application code, declarative UI entry points, and generated app scaffolds.

- [Example app](https://github.com/tessera-ui/tessera/tree/main/example): demo app · Reference application showing pages, custom shaders, and generated platform outputs. · `example`

### Core UI stack

Shared foundation, runtime execution, component widgets, and app-state/navigation.

- [Macros](https://github.com/tessera-ui/tessera/tree/main/tessera-macros): proc-macro · Transforms declarative component functions into runtime-ready entry points. · `tessera-macros`
- [UI runtime](https://github.com/tessera-ui/tessera/tree/main/tessera-ui): render runtime · Executes component trees, manages app context, and orchestrates runtime state. · `tessera-ui`
- [Tree builder](https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/build_tree.rs): component tree · Builds component trees and constraints before layout and rendering. · `tessera-ui/src/build_tree.rs`
- [Layout](https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/layout.rs): layout engine · Computes constraints, layout, and render-scene preparation. · `tessera-ui/src/layout.rs`
- [Renderer](https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/renderer.rs): GPU renderer · Owns render graph, render passes, scenes, and GPU-backed drawing. · `tessera-ui/src/renderer.rs`
- [Session state](https://github.com/tessera-ui/tessera/blob/main/tessera-ui/src/context.rs): input/runtime state · Focus, keyboard, IME, cursor, scroll, timing, profiling, and testing support. · `tessera-ui/src/context.rs`
- [Foundation](https://github.com/tessera-ui/tessera/tree/main/tessera-foundation): primitives · Shared alignment, gesture, shape, and modifier semantics for the UI stack. · `tessera-foundation`
- [Components](https://github.com/tessera-ui/tessera/tree/main/tessera-components): widget crate · Reusable UI widgets, controls, and specialized visual components. · `tessera-components`
- [Widgets](https://github.com/tessera-ui/tessera/blob/main/tessera-components/src/lib.rs): controls · Buttons, text fields, dialogs, navigation, sliders, scrollables, and layout primitives. · `tessera-components/src/lib.rs`
- [Pipelines](https://github.com/tessera-ui/tessera/blob/main/tessera-components/src/pipelines.rs): shader pipelines · Component-owned GPU pipelines and WGSL shaders for blur, shadow, image, text, glass, and effects. · `tessera-components/src/pipelines.rs`
- [Shard](https://github.com/tessera-ui/tessera/tree/main/tessera-shard): state/router · Handle-based state storage, async support, and router/navigation state. · `tessera-shard`

### Tooling and platform

Build-time, CLI, and host-platform integration for desktop/mobile packaging and launch.

- [Platform](https://github.com/tessera-ui/tessera/tree/main/tessera-platform): host integration · Clipboard, window, and Android plugin surface for native host features. · `tessera-platform`
- [Build bridge](https://github.com/tessera-ui/tessera/tree/main/tessera-build): build-time crate · Embeds backend assets and selects platform backend logic, including Android-specific build support. · `tessera-build`
- [cargo-tessera](https://github.com/tessera-ui/tessera/tree/main/cargo-tessera): CLI/workflow · User-facing commands for new, build, dev, check, web, android, plugin, and profiling workflows. · `cargo-tessera`
- [Mobile tooling](https://github.com/tessera-ui/tessera/tree/main/tessera-mobile): mobile workspace · Project parsing, target detection, device/emulator management, platform logic, and template generation. · `tessera-mobile`

### Generated outputs

Example app outputs and template sources used to scaffold new projects and platform wrappers.

- [Templates](https://github.com/tessera-ui/tessera/tree/main/cargo-tessera/templates): scaffolding · App and platform skeletons used to generate Rust, Android, and Xcode project structures. · `cargo-tessera/templates`
- [Generated app](https://github.com/tessera-ui/tessera/tree/main/example/gen): generated outputs · Example-generated Android and web outputs showing the packaging pipeline in action. · `example/gen`

## Connections

- Example app → Macros: uses macros · App code is authored declaratively and bridged through procedural macros.
- Example app → UI runtime: runs on · The app executes inside the Tessera runtime boundary.
- Example app → Components: uses widgets · Pages compose reusable widgets and component-level effects.
- Example app → Shard: uses state · App-level navigation and state management can sit above the UI runtime.
- Macros → UI runtime: expands for · Macro output is shaped for the runtime execution model.
- UI runtime → Tree builder: builds · Component functions are turned into a component tree.
- Tree builder → Layout: feeds · Tree structure is laid out and constrained.
- Layout → Renderer: emits scene · Layout results are converted into render graphs and scenes.
- UI runtime → Session state: owns state · Runtime manages focus, keyboard, IME, cursor, scroll, timing, and profiling.
- UI runtime → Foundation: depends on · Runtime shares foundational layout and interaction semantics.
- Components → Foundation: builds on · Widgets and modifiers use the shared foundation vocabulary.
- Components → Widgets: contains · High-level controls and layout primitives live here.
- Components → Pipelines: contains · Specialized rendering pipelines are part of the component layer.
- Widgets → Pipelines: drives visuals · Many widgets rely on shader-backed drawing and effects.
- Shard → UI runtime: sits above · State and routing coordinate app behavior without owning rendering.
- Platform → UI runtime: integrates with · Host clipboard and window services connect into the runtime boundary.
- Build bridge → Platform: packages · Build logic helps produce platform-specific bundles and backends.
- cargo-tessera → Mobile tooling: invokes · The CLI fronts mobile/project workflows and platform commands.
- cargo-tessera → Build bridge: orchestrates · Build and packaging commands rely on the build bridge.
- cargo-tessera → Templates: generates · New project commands scaffold from repository templates.
- Mobile tooling → Templates: renders · Mobile tooling expands app and platform templates into projects.
- Generated app → Mobile tooling: result of · The generated example tree demonstrates the mobile/project generation pipeline.
- Generated app → Platform: includes · Generated outputs include platform wrappers and native integration surfaces.