# account-link/teleport-gramine-rs architecture

> Architecture diagram of the GitHub repository account-link/teleport-gramine-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/account-link/teleport-gramine-rs
- Repository: https://github.com/account-link/teleport-gramine-rs

## Overview

##### Project Type and Purpose
- Teleport is a backend service (with some auxiliary Python scripts) that leverages trusted execution environments (TEEs) to ensure that one-time Twitter posts (represented as NFTs) are executed exactly once and under strict enforced policies.
- It integrates on-chain NFT creation/minting, secure certificate and attestation verification, and external interactions with both Twitter (for posting) and LLM (for content-safeguard policy verification).

##### Analyzing the File Structure
- There’s a strong use of Rust (Cargo.toml, src/ folder, etc.) which handles the core business logic, TEE attestation (src/sgx_attest.rs), database/client management (src/db directory) and various endpoints (src/endpoints.rs).
- The “abi” folder contains JSON files for NFT and redemption interfaces, hinting at blockchain integration.
- The “auditing” folder includes snapshots and certificates, providing evidence of certificate transparency and remote attestation.
- There are Python scripts (e.g., app.py, scripts/) which likely support orchestration, data conversion, or tooling around certificate fetching and minting.
- Docker, GitHub workflows, and configuration files are also present to aid in deployment and continuous integration.

##### Core Components
a. Secure Enclave/TEE
- TEE component (with modules like src/sgx_attest.rs) which manages remote attestation to guarantee that the code enforcing “one post” and LLM safeguard is running in a secure, auditable environment.

b. Backend Business Logic
- Main service (src/main.rs, src/lib.rs) containing:
- Endpoint modules for handling incoming requests (src/endpoints.rs).
- NFT minting and redemption actions (src/actions, src/bin/redeem.rs).
- Database interaction modules (src/db) for in-memory or persisted state tracking.

c. Twitter Integration
- Integration layer contained in src/twitter, which handles authentication, tweet creation, posting, and any content response logic.

d. Blockchain / NFT Layer
- NFT processes, noting that NFT data is defined in the abi folder (nft.json and redeem.json) and that minted NFTs represent ownership of the one-time-use link.

e. LLM / Safeguard Enforcement
- That a GPT-4 or similar LLM is used as a safeguard policy enforcer (referenced in the README and possibly initiated in src/oai.rs). This component makes API calls to evaluate policy conditions before permitting a tweet.

f. Auditing and Certificate Transparency
- Auditing system which manages remote attestation certificates and snapshots (see auditing/ folder), ensuring that the TEE’s security guarantees are verifiable.

g. Auxiliary Components and Deployment Tools
- Deployment orchestrators (Dockerfiles, docker-compose.yml), CI pipelines (.github/workflows), and auxiliary scripts (Python in app.py and the scripts/ folder) which contribute to bootstrapping, certificate management, and minting operations.

##### Relationships and Interactions
- Then, the backend communicates with:
- The TEE module for attestation and secure execution.
- The LLM API for enforcing the safeguard policy.
- Once validated, the service interacts with:
- The Twitter backend via the Twitter integration module.
- The NFT/blockchain component to mint or record the one-time use token.
- Auditing components monitor and record attestation events, interacting with the TEE layer.

##### Architectural Patterns and Design Principles
- Separation of concerns by splitting functionalities across clearly separated modules: secure processing (TEE), business logic (Rust core), external API integration (Twitter and LLM safeguards), data storage (database modules), and auditing.
- The system leverages containerization (Docker) and CI/CD for consistent deployment and version management.
- Security and auditability are prioritized, as seen with rigorous certificate management and attestation snapshot logging.

- “TEE Enclave” (secure processing and remote attestation).
- “LLM Safeguard (API)” (enforcing post policies).
- “Twitter Integration Module” (connecting with Twitter’s API).
- “NFT/Blockchain Module” (managing minting and on-chain representation).
- “Database/Storage” (state management for one-time links and auditing data).
- “Auxiliary Scripts & Deployment” (Python scripts, Docker, CI/CD) as peripheral components aiding operational overhead.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    incoming("Incoming Request"):::core

    %% Backend Business Logic Subgraph
    subgraph "Backend Business Logic"
        direction TB
        E("Endpoints"):::core
        M("Main"):::core
        L("Lib"):::core
        A("Actions"):::core
        NA("NFT Action"):::core
        WA("Wallet Action"):::core
        E --> M
        M --> L
        L --> A
        A --> NA
        A --> WA
    end

    %% External Modules
    TEE("TEE Enclave"):::security
    LLM("LLM Safeguard (API)"):::integration
    Twitter("Twitter Integration Module"):::integration
    NFT("NFT/Blockchain Module"):::blockchain
    DB("Database/Storage Module"):::database
    Auditing("Auditing Module"):::security
    Aux("Auxiliary Scripts & Deployment Tools"):::auxiliary

    %% Connections
    incoming --> E
    E --> TEE
    E --> LLM
    E --> Twitter
    E --> NFT
    E --> DB
    TEE --> Auditing
    Aux --> E
    Aux --> Auditing

    %% Click Events for Backend Business Logic
    click E "https://github.com/account-link/teleport-gramine-rs/blob/main/src/endpoints.rs"
    click M "https://github.com/account-link/teleport-gramine-rs/blob/main/src/main.rs"
    click L "https://github.com/account-link/teleport-gramine-rs/blob/main/src/lib.rs"
    click A "https://github.com/account-link/teleport-gramine-rs/tree/main/src/actions"
    click NA "https://github.com/account-link/teleport-gramine-rs/blob/main/src/actions/nft.rs"
    click WA "https://github.com/account-link/teleport-gramine-rs/blob/main/src/actions/wallet.rs"

    %% Click Events for TEE Enclave
    click TEE "https://github.com/account-link/teleport-gramine-rs/blob/main/src/sgx_attest.rs"

    %% Click Events for Twitter Integration Module
    click Twitter "https://github.com/account-link/teleport-gramine-rs/tree/main/src/twitter"

    %% Click Events for NFT/Blockchain Module
    click NFT "https://github.com/account-link/teleport-gramine-rs/blob/main/abi/nft.json"
    click NFT "https://github.com/account-link/teleport-gramine-rs/blob/main/abi/redeem.json"

    %% Click Events for LLM Safeguard (API)
    click LLM "https://github.com/account-link/teleport-gramine-rs/blob/main/src/oai.rs"

    %% Click Events for Database/Storage Module
    click DB "https://github.com/account-link/teleport-gramine-rs/tree/main/src/db"
    click DB "https://github.com/account-link/teleport-gramine-rs/blob/main/src/db/client_db.rs"
    click DB "https://github.com/account-link/teleport-gramine-rs/blob/main/src/db/in_memory.rs"
    click DB "https://github.com/account-link/teleport-gramine-rs/blob/main/src/db/mod.rs"

    %% Click Events for Auditing Module
    click Auditing "https://github.com/account-link/teleport-gramine-rs/tree/main/auditing"

    %% Click Events for Auxiliary Scripts & Deployment Tools
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/app.py"
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/scripts/convert.py"
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/scripts/fetch-certs.py"
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/scripts/login.py"
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/scripts/mint.py"
    click Aux "https://github.com/account-link/teleport-gramine-rs/tree/main/Dockerfile"
    click Aux "https://github.com/account-link/teleport-gramine-rs/blob/main/docker-compose.yml"
    click Aux "https://github.com/account-link/teleport-gramine-rs/tree/main/.github/workflows"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef security fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef integration fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef blockchain fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef database fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef auxiliary fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
```
