# google/automotive-design-compose architecture

> Architecture diagram of the GitHub repository google/automotive-design-compose, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/automotive-design-compose
- Repository: https://github.com/google/automotive-design-compose

## Overview

1. **This is a mixed Kotlin/Android + Rust monorepo**
   The repository is centered on the DesignCompose SDK for Android Automotive. The Android side is a Gradle multi-project build; the native/live-update path is implemented in Rust crates and bridged into Android through JNI. Several sample apps, test apps, and Figma support tools are included in the same repo.

2. **Primary product boundary: the `designcompose` Android library**
   `designcompose/` is the main runtime library that app developers consume. It contains the Compose renderer, design-doc loading, live update handling, theming/customization, interaction state, layout management, and rendering helpers. It also includes bundled `.dcf` assets used by tests and demos, such as the Design Switcher document.

3. **Document flow starts from Figma and ends in Compose rendering**
   The core architecture is: Figma document → Rust importer/download/serialization → `.dcf` serialized document → Android runtime parses/loads it → Compose UI renders it. The runtime can also fetch updates live, so document state is not only static assets but may be refreshed from Figma over the network.

4. **Rust crates handle document import, bundle format, layout, and native interop**
   The native side is split into focused crates:
   - `dc_figma_import` fetches Figma files/resources and converts them into the internal serialized form.
   - `dc_bundle` defines the serialized document/bundle format and includes inspection tooling.
   - `dc_layout` computes layout and converts document layout into the engine’s layout model.
   - `dc_jni` exposes the Rust functionality to Android through JNI.
   - `dc_squoosh_animation` supports animation-related processing.
   These crates are the boundary between Figma data and the Android runtime.

5. **`common/`, `annotation/`, and `codegen/` define the developer-facing API surface**
   - `common/` holds shared data types and serialization-friendly model objects used across modules.
   - `annotation/` defines annotations like design-document/component markers.
   - `codegen/` is a KSP-based Kotlin compiler plugin that generates stubs and wiring for annotated Composables.
   This is the API/compile-time layer that turns app code into DesignCompose-aware entry points.

6. **Gradle plugins orchestrate native builds, publishing, and configuration**
   The `plugins/` directory contains custom Gradle plugins, including a Cargo plugin that builds Rust artifacts for Android/host targets and a plugin for setting Figma tokens. `build-logic/` contains convention plugins shared across the repo. These pieces are important because the build is not pure Android; Gradle coordinates Kotlin, JNI, and Cargo outputs.

7. **Live update is a distinct runtime subsystem**
   Inside `designcompose/`, live update support includes token handling, document server settings, and a WebSocket update client. There is also a `tools/ws-relay` Python service, suggesting a local relay path for websocket-based update traffic. This makes live update a separate networked subsystem, not just a file-loading feature.

8. **Design-switching and customization are first-class app concerns**
   The runtime includes `DesignSwitcher`, customization contexts, variable management, interaction state, and theme/material mapping. These pieces let an app swap between design docs and override behavior without rebuilding the app. In the architecture diagram, this is the “dynamic configuration” layer sitting between the app and the document renderer.

9. **Sample apps demonstrate different integration modes**
   `reference-apps/` contains standalone example apps:
   - `tutorial` shows the end-user onboarding/tutorial flow.
   - `helloworld` is the minimal app example.
   - `aaos-unbundled/mediacompose` demonstrates an Android Automotive media-centric integration.
   - `cluster-demo` is another sample/test app.
   These are not just demos; they show how the SDK is consumed in real app shells, with their own assets, manifests, fonts, and activities.

10. **`integration-tests/` is the validation and benchmark boundary**
    This folder contains:
    - `validation/` for visually verifying rendering and behavior against many serialized Figma documents.
    - `benchmarks/` for startup/performance measurement, including the battleship benchmark app.
    - `app-common/` for shared test app utilities and fonts.
    The presence of many `.dcf` test assets indicates that serialized document fixtures are a major testing input.

11. **Figma-side tooling is split into plugins/widgets**
    `support-figma/` contains the Figma ecosystem tooling:
    - `extended-layout-plugin` for authoring/validation of extended layout and customization metadata.
    - `auto-content-preview-widget` for designer-facing content previews.
    - `dc_squoosh_designer` for animation/timeline authoring.
    These tools produce or consume data that ultimately feeds the serialized document flow used by the Android runtime.

12. **Docs, scripts, and CI are part of the operational architecture**
    `docs/` hosts the generated documentation site and architecture docs. `dev-scripts/` automate formatting, testing, asset updates, and release prep. `.github/workflows/` and related files define CI, release, screenshot comparison, code quality, and publishing pipelines. These aren’t runtime components, but they govern how the multi-language system is built, validated, and released.

13. **Key external boundaries to show in a diagram**
    The important external systems are:
    - Figma API / Figma Desktop app
    - Android apps / Compose runtime
    - GitHub Releases and CI
    - Rust toolchain and Android NDK for native builds
    These boundaries materially affect how data and artifacts move through the system.

14. **The simplest accurate architecture diagram**
    A good high-level diagram would show:
    - Figma docs/resources on one side
    - Rust import/serialization/layout/JNI in the middle
    - Android DesignCompose runtime and generated Kotlin APIs on the other
    - Sample/reference apps and test apps consuming the runtime
    - Supporting Figma plugins/widgets and CI/build tooling as side systems
    The main data artifact flowing through the system is the serialized `.dcf` document, with live-update traffic as an additional runtime channel.

Main entry points: [`designcompose`](https://github.com/google/automotive-design-compose/tree/main/designcompose) (Runtime SDK), [`crates/dc_bundle`](https://github.com/google/automotive-design-compose/tree/main/crates/dc_bundle) (Bundle Format), [`crates/dc_jni`](https://github.com/google/automotive-design-compose/tree/main/crates/dc_jni) (JNI Bridge), [`crates/dc_figma_import`](https://github.com/google/automotive-design-compose/tree/main/crates/dc_figma_import) (Figma Import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External Systems"]
  node_figma_api(("Figma<br/>external design source"))
  node_android_runtime(("Compose<br/>external UI runtime"))
  node_github_ci(("CI / Releases<br/>external delivery"))
end

subgraph group_android_sdk["Android SDK"]
  node_designcompose["Runtime SDK<br/>Android library"]
  node_api_surface["API Surface<br/>Kotlin API"]
  node_renderer["Renderer"]
  node_live_update["Live Update<br/>network runtime"]
  node_dynamic_config["Dynamic Config<br/>runtime state<br/>[DesignSwitcher.kt]"]
  node_codegen["Codegen<br/>KSP processor"]
  node_annotation["Annotations<br/>marker API"]
end

subgraph group_native["Native Rust"]
  node_dc_figma_import["Figma Import<br/>Rust importer"]
  node_dc_bundle["Bundle Format<br/>Rust schema"]
  node_dc_layout["Layout Engine<br/>Rust layout"]
  node_dc_jni["JNI Bridge<br/>Rust interop"]
  node_dc_squoosh_animation{{"Animation Proc<br/>Rust helper"}}
end

subgraph group_apps_tests["Apps & Tests"]
  node_reference_apps["Reference Apps<br/>sample apps"]
  node_integration_tests["Validation Suite<br/>test harness"]
  node_designcompose_tests["SDK Tests<br/>android tests"]
end

subgraph group_figma_tools["Figma Tools"]
  node_support_figma["Figma Support<br/>plugins/widgets"]
end

subgraph group_build_ops["Build & Ops"]
  node_cargo_plugin["Cargo Plugin<br/>Gradle plugin"]
  node_gradle_plugins["Gradle Plugins<br/>build plugins"]
  node_build_logic["Build Logic<br/>convention plugins"]
  node_docs_scripts["Docs & Scripts<br/>ops tooling"]
end

node_figma_api -->|"design docs"| node_dc_figma_import
node_dc_figma_import -->|"serialize"| node_dc_bundle
node_dc_bundle -->|"load .dcf"| node_designcompose
node_dc_bundle -->|"fixtures"| node_integration_tests
node_dc_bundle -->|"sample assets"| node_reference_apps
node_dc_layout -->|"layout model"| node_designcompose
node_dc_jni -->|"native bridge"| node_designcompose
node_dc_figma_import -->|"interop"| node_dc_jni
node_dc_layout -->|"interop"| node_dc_jni
node_dc_squoosh_animation -->|"animation data"| node_dc_bundle
node_annotation -->|"annotate"| node_codegen
node_codegen -->|"generate stubs"| node_api_surface
node_api_surface -->|"consume"| node_designcompose
node_designcompose -->|"render"| node_renderer
node_renderer -->|"compose UI"| node_android_runtime
node_dynamic_config -->|"customize"| node_renderer
node_live_update -->|"refresh"| node_designcompose
node_figma_api -->|"websocket / fetch"| node_live_update
node_support_figma -->|"authoring tools"| node_figma_api
node_reference_apps -->|"embed SDK"| node_designcompose
node_integration_tests -->|"verify SDK"| node_designcompose
node_designcompose_tests -->|"test runtime"| node_designcompose
node_cargo_plugin -->|"build native"| node_dc_jni
node_gradle_plugins -->|"configure"| node_cargo_plugin
node_build_logic -->|"shared conventions"| node_gradle_plugins
node_docs_scripts -->|"automation"| node_github_ci
node_docs_scripts -->|"asset updates"| node_reference_apps

click node_designcompose "https://github.com/google/automotive-design-compose/tree/main/designcompose"
click node_api_surface "https://github.com/google/automotive-design-compose/tree/main/common"
click node_renderer "https://github.com/google/automotive-design-compose/tree/main/designcompose/src/main/java/com/android/designcompose"
click node_live_update "https://github.com/google/automotive-design-compose/blob/main/designcompose/src/main/java/com/android/designcompose/WebSocketUpdateClient.kt"
click node_dynamic_config "https://github.com/google/automotive-design-compose/blob/main/designcompose/src/main/java/com/android/designcompose/DesignSwitcher.kt"
click node_codegen "https://github.com/google/automotive-design-compose/tree/main/codegen"
click node_annotation "https://github.com/google/automotive-design-compose/tree/main/annotation"
click node_dc_figma_import "https://github.com/google/automotive-design-compose/tree/main/crates/dc_figma_import"
click node_dc_bundle "https://github.com/google/automotive-design-compose/tree/main/crates/dc_bundle"
click node_dc_layout "https://github.com/google/automotive-design-compose/tree/main/crates/dc_layout"
click node_dc_jni "https://github.com/google/automotive-design-compose/tree/main/crates/dc_jni"
click node_dc_squoosh_animation "https://github.com/google/automotive-design-compose/tree/main/crates/dc_squoosh_animation"
click node_reference_apps "https://github.com/google/automotive-design-compose/tree/main/reference-apps"
click node_integration_tests "https://github.com/google/automotive-design-compose/tree/main/integration-tests"
click node_designcompose_tests "https://github.com/google/automotive-design-compose/tree/main/designcompose/src/androidTest"
click node_support_figma "https://github.com/google/automotive-design-compose/tree/main/support-figma"
click node_cargo_plugin "https://github.com/google/automotive-design-compose/tree/main/plugins/cargo-plugin"
click node_gradle_plugins "https://github.com/google/automotive-design-compose/tree/main/plugins/gradle-plugin"
click node_build_logic "https://github.com/google/automotive-design-compose/tree/main/build-logic"
click node_docs_scripts "https://github.com/google/automotive-design-compose/tree/main/docs"

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_figma_api,node_android_runtime,node_github_ci toneBlue
class node_designcompose,node_api_surface,node_renderer,node_live_update,node_dynamic_config,node_codegen,node_annotation toneAmber
class node_dc_figma_import,node_dc_bundle,node_dc_layout,node_dc_jni,node_dc_squoosh_animation toneMint
class node_reference_apps,node_integration_tests,node_designcompose_tests toneRose
class node_support_figma toneIndigo
class node_cargo_plugin,node_gradle_plugins,node_build_logic,node_docs_scripts toneTeal
```

## Components

### External Systems

Outside services and runtimes the repo integrates with

- **Figma**: external design source · Source of design documents, resources, and live-update data
- **Compose**: external UI runtime · Android UI runtime that DesignCompose renders into
- **CI / Releases**: external delivery · GitHub-based validation, publishing, and release automation

### Android SDK

Public runtime, API surface, and generated Kotlin entry points

- [Runtime SDK](https://github.com/google/automotive-design-compose/tree/main/designcompose): Android library · Main DesignCompose library consumed by app developers · `designcompose`
- [API Surface](https://github.com/google/automotive-design-compose/tree/main/common): Kotlin API · Common data types, annotations, and generated stubs used by apps · `common`
- [Renderer](https://github.com/google/automotive-design-compose/tree/main/designcompose/src/main/java/com/android/designcompose): Compose renderer · Document loading, layout coordination, and Compose rendering path · `designcompose/src/main/java/com/android/designcompose`
- [Live Update](https://github.com/google/automotive-design-compose/blob/main/designcompose/src/main/java/com/android/designcompose/WebSocketUpdateClient.kt): network runtime · WebSocket client, server settings, and update handling · `designcompose/src/main/java/com/android/designcompose/WebSocketUpdateClient.kt`
- [Dynamic Config](https://github.com/google/automotive-design-compose/blob/main/designcompose/src/main/java/com/android/designcompose/DesignSwitcher.kt): runtime state · Design switching, customization, variables, interactions, and theme mapping · `designcompose/src/main/java/com/android/designcompose/DesignSwitcher.kt`
- [Codegen](https://github.com/google/automotive-design-compose/tree/main/codegen): KSP processor · Annotation processor that generates DesignCompose wiring · `codegen`
- [Annotations](https://github.com/google/automotive-design-compose/tree/main/annotation): marker API · Developer-facing annotations for design-aware components · `annotation`

### Native Rust

Document import, bundle, layout, and JNI bridge layer

- [Figma Import](https://github.com/google/automotive-design-compose/tree/main/crates/dc_figma_import): Rust importer · Fetches Figma files/resources and converts them into serialized document form · `crates/dc_figma_import`
- [Bundle Format](https://github.com/google/automotive-design-compose/tree/main/crates/dc_bundle): Rust schema · Serialized document and bundle definition, including inspection tooling · `crates/dc_bundle`
- [Layout Engine](https://github.com/google/automotive-design-compose/tree/main/crates/dc_layout): Rust layout · Computes and converts document layout into the engine model · `crates/dc_layout`
- [JNI Bridge](https://github.com/google/automotive-design-compose/tree/main/crates/dc_jni): Rust interop · Exposes Rust functionality to Android through JNI · `crates/dc_jni`
- [Animation Proc](https://github.com/google/automotive-design-compose/tree/main/crates/dc_squoosh_animation): Rust helper · Animation-related processing support for native document flow · `crates/dc_squoosh_animation`

### Apps & Tests

Reference apps and validation harnesses consuming the SDK

- [Reference Apps](https://github.com/google/automotive-design-compose/tree/main/reference-apps): sample apps · Standalone example apps demonstrating SDK integration modes · `reference-apps`
- [Validation Suite](https://github.com/google/automotive-design-compose/tree/main/integration-tests): test harness · Rendering validation, benchmarks, and shared test app infrastructure · `integration-tests`
- [SDK Tests](https://github.com/google/automotive-design-compose/tree/main/designcompose/src/androidTest): android tests · Runtime tests and fixtures for the main SDK module · `designcompose/src/androidTest`

### Figma Tools

Designer-facing plugins and widgets that produce or inspect design data

- [Figma Support](https://github.com/google/automotive-design-compose/tree/main/support-figma): plugins/widgets · Designer-side tooling that emits or consumes design data and timelines · `support-figma`

### Build & Ops

Gradle, Cargo, scripts, docs, and CI orchestration

- [Cargo Plugin](https://github.com/google/automotive-design-compose/tree/main/plugins/cargo-plugin): Gradle plugin · Builds Rust artifacts for Android and host targets · `plugins/cargo-plugin`
- [Gradle Plugins](https://github.com/google/automotive-design-compose/tree/main/plugins/gradle-plugin): build plugins · Custom Gradle plugins and configuration helpers · `plugins/gradle-plugin`
- [Build Logic](https://github.com/google/automotive-design-compose/tree/main/build-logic): convention plugins · Shared Gradle convention plugins across the repo · `build-logic`
- [Docs & Scripts](https://github.com/google/automotive-design-compose/tree/main/docs): ops tooling · Documentation, developer scripts, and release automation support · `docs`

## Connections

- Figma → Figma Import: design docs · Figma files and resources are imported into serialized form
- Figma Import → Bundle Format: serialize · Importer emits the repository's serialized .dcf document format
- Bundle Format → Runtime SDK: load .dcf · Android runtime loads serialized bundles and fixtures
- Bundle Format → Validation Suite: fixtures · Validation and benchmark suites consume many .dcf test assets
- Bundle Format → Reference Apps: sample assets · Reference apps ship bundled design documents for demos
- Layout Engine → Runtime SDK: layout model · Native layout results are consumed by the Android renderer
- JNI Bridge → Runtime SDK: native bridge · JNI exposes Rust capabilities to the Kotlin runtime
- Figma Import → JNI Bridge: interop · Importer functionality is surfaced through the JNI boundary
- Layout Engine → JNI Bridge: interop · Layout computation is surfaced through the JNI boundary
- Animation Proc → Bundle Format: animation data · Animation processing contributes to serialized document handling
- Annotations → Codegen: annotate · Annotations are the input to generated component wiring
- Codegen → API Surface: generate stubs · KSP generates runtime-facing Kotlin entry points and helpers
- API Surface → Runtime SDK: consume · Apps and generated code compile against the shared API layer
- Runtime SDK → Renderer: render · Main runtime coordinates document parsing, layout, and Compose rendering
- Renderer → Compose: compose UI · Rendered document state is shown inside the host Compose runtime
- Dynamic Config → Renderer: customize · Switching, variables, interactions, and themes modify rendering behavior
- Live Update → Runtime SDK: refresh · Live update changes document state over the network
- Figma → Live Update: websocket / fetch · Runtime can pull remote updates and document content from Figma-related services
- Figma Support → Figma: authoring tools · Plugins and widgets produce or inspect data that feeds the document pipeline
- Reference Apps → Runtime SDK: embed SDK · Samples show how app shells consume the runtime library
- Validation Suite → Runtime SDK: verify SDK · Validation and benchmark apps exercise runtime behavior
- SDK Tests → Runtime SDK: test runtime · SDK-specific tests validate live update, JNI, and rendering behavior
- Cargo Plugin → JNI Bridge: build native · Gradle plugin coordinates Rust builds for Android and host targets
- Gradle Plugins → Cargo Plugin: configure · Higher-level Gradle plugins wrap and configure native build tasks
- Build Logic → Gradle Plugins: shared conventions · Convention plugins are reused across modules and examples
- Docs & Scripts → CI / Releases: automation · Docs, scripts, and workflows support CI, release, and validation flows
- Docs & Scripts → Reference Apps: asset updates · Developer scripts regenerate bundled docs and sample assets
