# apache/incubator-teaclave-trustzone-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/apache/incubator-teaclave-trustzone-sdk
- Repository: https://github.com/apache/incubator-teaclave-trustzone-sdk

## Overview

Based on your project’s file tree and README, this is a Rust SDK built for developing TrustZone applications (specifically for OP-TEE). It supplies both “no-std” and “std” development modes and contains multiple layers of functionality:

##### Project Type and Purpose
- It is a specialized SDK for writing Trusted Applications (TAs) running in the secure world using OP-TEE.
- It maintains separate libraries for the client side (CA) and the TA side (“optee-teec” for client/host interaction and “optee-utee” for TA internals), plus supporting examples to help demonstrate common secure functionalities (e.g., AES, Diffie-Hellman, authentication, and even a web3 eth_wallet).
- The README highlights the two development modes (“no-std” vs. “std”) along with integration to OP-TEE (QEMUv8 and other platforms), so the system spans from build tools to runtime deployment environments.

##### Analyzing the File Structure
- At the top level, there are build configuration files (like Makefile, Dockerfile, setup.sh), CI pipelines (in .github/workflows), and various documentation (in docs/).
- The “examples/” folder is extensive—each subdirectory (e.g., aes-rs, auth, hello_world-rs, etc.) is organized with subdirectories:
– “host” contains the client-side Rust code that leverages optee-teec to communicate with the TEE.
– “proto” defines common protocols or API contracts.
– “ta” holds the Trusted Application code that interfaces with the secure world via optee-utee.
- Similarly, “optee-teec” and “optee-utee” are distinct libraries representing the interface for client and TA sides. “optee-utee-build” contains the build scripts and code generators that ease the process of building TAs.
- There is also a “projects/” folder (with a “web3” subproject) that shows the versatility and additional integrations like ETH wallet examples.

##### Diagramming the System Architecture

a. Main Components:
- Development Environment & Build System:
– Setup scripts (setup.sh, setup_std_dependencies.sh)
– Environment configuration (the “environment” file)
– Build automation (Makefile, Dockerfile, CI scripts)
- SDK Core Libraries:
– optee-teec: Client-side library offering TEE communication APIs.
– optee-utee: Trusted Application runtime library.
– optee-utee-build: Tools and code generators for building TAs.
- Examples & Demonstration Apps:
– Multiple examples under “examples/”, following the same structure: “host”, “proto”, “ta”, with each sample demonstrating distinct functionalities.
– Additional specialized projects (e.g., projects/web3/eth_wallet)
- Testing & CI Pipeline:
– A tests/ directory containing scripts that automate testing across different functionalities and examples.
- Underlying OP-TEE / Platform Integration:
– Integration points with OP-TEE for QEMUv8 (or other platforms), including instructions in the README for copying built artifacts into shared folders, QEMU setup, and mounting within the guest system.

b. Relationships and Interactions:
- How “proto” represents the shared or agreed API interfaces that standardize communication between CA and TA.
- That these components are aggregated to form a complete TrustZone application.

c. Architectural Patterns & Design Principles:
- Layered architecture: separation of concerns between client code (host), protocol interfaces (proto), and trusted application code (ta).
- Modularity: the examples are independent modules, and core libraries (optee-teec and optee-utee) are maintained as separate components.
- That the system leverages Rust’s cargo package management and build mechanisms (with Cargo.toml configurations) across multiple subprojects.

d. Relevant Technologies & Frameworks:
- Programming Language: Rust (with both “no-std” and “std” modes).
- Build and Packaging: Makefile, Cargo, Docker.
- Continuous Integration: GitHub Actions (.github/workflows).
- Underlying TEE Infrastructure: OP-TEE (including QEMUv8 configurations) and adherence to GlobalPlatform TEE specifications.

##### Final Recommendations
- Start from the largest view (the overall SDK use-case and integration with OP-TEE) then zoom in into layers (build system → core libraries → examples).
- Clearly presenting how each part works together: how a developer sets up the environment, builds the TA and CA, how they communicate, and then how tests and CI validate everything.
- Avoid overcomplication; break the system into as many discrete components as possible and illustrate the interactions using directional flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Development Environment & Build System"
        DevBuild("Build Config"):::build
        CIPipeline("CI Pipelines"):::build
        Setup("Setup Scripts"):::build
    end

    subgraph "SDK Core Libraries"
        ClientLib("OP-TEE Client Library (optee-teec)"):::core
        TrustedLib("Trusted Application Library (optee-utee)"):::core
        BuildTools("TA Build Tools (optee-utee-build)"):::core
    end

    subgraph "Examples & Demonstration Apps"
        Examples("Example Applications (host,proto,ta)"):::example
        EthWallet("ETH Wallet Project"):::example
    end

    subgraph "Testing & CI Pipeline"
        Tests("Automated Tests"):::test
        CIJobs("CI Workflows"):::test
    end

    subgraph "Underlying OP-TEE / Platform Integration"
        Platform("OP-TEE & Platform Integration"):::platform
        Docs("Documentation & Config"):::platform
    end

    %% Connections
    DevBuild --> ClientLib
    DevBuild --> TrustedLib
    DevBuild --> BuildTools
    DevBuild --> CIPipeline
    DevBuild --> Setup

    ClientLib -->|"communicates_with"| Examples
    TrustedLib -->|"serves"| Examples
    Examples -->|"integrates_with"| EthWallet
    CIJobs --> Tests
    Tests -->|"validates"| Examples
    Examples -->|"deploys_to"| Platform
    Docs --> Platform

    %% Click Events
    click DevBuild "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/Makefile"
    click CIPipeline "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/.github/workflows/"
    click Setup "https://github.com/apache/incubator-teaclave-trustzone-sdk/blob/main/setup.sh"
    click ClientLib "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/optee-teec/"
    click TrustedLib "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/optee-utee/"
    click BuildTools "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/optee-utee-build/"
    click Examples "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/examples/"
    click EthWallet "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/projects/web3/eth_wallet/"
    click Tests "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/tests/"
    click CIJobs "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/.github/workflows/"
    click Docs "https://github.com/apache/incubator-teaclave-trustzone-sdk/tree/main/docs/"

    %% Styles
    classDef build fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef core fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef example fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef platform fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
