# telemetree/telemetree-pixel architecture

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

- Interactive diagram: https://gitdiagram.com/telemetree/telemetree-pixel
- Repository: https://github.com/telemetree/telemetree-pixel

## Overview

##### Main Components

a) Client-Side Components:
- Telemetree Pixel Core (Main SDK)
- Event Builders System
- Transport Layer
- Storage Management
- Telegram Web App Integration
- TON Connect Integration

b) External Systems:
- Telegram Web App Platform
- TON Blockchain
- Telemetree Backend Services

##### Key Architectural Elements

**1. Integration Layer**
- Telegram Web App Context
- TON Connect Integration

**2. Core SDK Layer**
- Event Builder System
- Hooks & Observers
- Configuration Management

**3. Data Processing Layer**
- Event Processing
- Encryption System
- Transport Management

**4. External Services Layer**
- Telemetree API
- Telegram Platform
- TON Blockchain

##### Specific Implementation Details

a) Event Flow:
- How events are created using the EventBuilder (src/builders)
- Flow through observers (src/observers)
- Demonstrate how events are processed and transported (src/transports)

b) Integration Points:
- Connection with Telegram Web App (src/telegram)
- TON Connect integration (src/observers/ton-connect.observer.ts)
- Tracking groups implementation (src/setup/trackGroups.ts)

##### Data Flow Representation

- Event creation → Event building → Transport
- Telegram Web App events → SDK processing
- TON Connect events → SDK processing
- Encrypted data → Telemetree Backend

##### Important Details to Highlight

- RSA encryption process for data transmission
- Different tracking groups (high, medium, low)
- Automatic event collection system
- Custom event tracking capabilities

##### Component Relationships

Clear connections between:
- Event builders and transport layer
- Observers and event processing
- Storage management and local data
- Configuration and feature toggles

##### Integration flexibility

- Component types
- Tracking group levels

Keep the abstraction level high enough to show the overall architecture while including crucial implementation details that make this SDK unique, such as the Telegram Web App integration and TON Connect support.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef core fill:#2196F3,color:white
    classDef external fill:#4CAF50,color:white
    classDef processing fill:#FF9800,color:white
    classDef transport fill:#9C27B0,color:white
    classDef config fill:#757575,color:white
    classDef utility fill:#607D8B,color:white

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[External Systems]:::external
        L3[Processing]:::processing
        L4[Transport]:::transport
        L5[Configuration]:::config
        L6[Utilities]:::utility
    end

    %% Integration Layer
    subgraph Integration
        TG[Telegram Web App]:::external
        TON[TON Blockchain]:::external
        TONC[TON Connect]:::external
    end

    %% Core SDK Layer
    subgraph CoreSDK
        SETUP["SDK Setup"]:::core
        HOOKS["Hooks System"]:::core
        EB["Event Builder"]:::core
        OBS["Observers"]:::core
        CFG["Configuration"]:::config
    end

    %% Data Processing Layer
    subgraph Processing
        EP["Event Processing"]:::processing
        ES["Encryption System"]:::processing
        TG_GROUPS["Track Groups"]:::processing
    end

    %% Transport Layer
    subgraph Transport
        TL["Transport Layer"]:::transport
        HTTP["HTTP Transport"]:::transport
    end

    %% Utility Layer
    subgraph Utilities
        STORE["Storage Management"]:::utility
        LOG["Logger"]:::utility
        ID["ID Generator"]:::utility
        DH["Date Helper"]:::utility
    end

    %% External Services
    BACKEND["Telemetree Backend"]:::external

    %% Relationships
    TG --> OBS
    TON --> TONC
    TONC --> OBS
    OBS --> EB
    EB --> EP
    EP --> ES
    ES --> TL
    TL --> HTTP
    HTTP --> BACKEND
    CFG --> SETUP
    SETUP --> EB
    HOOKS --> EB
    TG_GROUPS --> EP
    STORE --> EP
    LOG --> EP
    ID --> EP
    DH --> EP

    %% Click Events
    click EB "https://github.com/Telemetree/telemetree-pixel/tree/main/src/builders/"
    click TONC "https://github.com/Telemetree/telemetree-pixel/blob/main/src/observers/ton-connect.observer.ts"
    click STORE "https://github.com/Telemetree/telemetree-pixel/blob/main/src/utils/local-storage.ts"
    click TG "https://github.com/Telemetree/telemetree-pixel/tree/main/src/telegram/"
    click ES "https://github.com/Telemetree/telemetree-pixel/blob/main/src/helpers/encryption.helper.ts"
    click CFG "https://github.com/Telemetree/telemetree-pixel/blob/main/src/config.ts"
    click TG_GROUPS "https://github.com/Telemetree/telemetree-pixel/blob/main/src/setup/trackGroups.ts"
    click EP "https://github.com/Telemetree/telemetree-pixel/blob/main/src/event-push-handler.ts"
    click HOOKS "https://github.com/Telemetree/telemetree-pixel/blob/main/src/hooks/use-event.hook.ts"
    click SETUP "https://github.com/Telemetree/telemetree-pixel/blob/main/src/setup/telemetree.ts"
    click LOG "https://github.com/Telemetree/telemetree-pixel/blob/main/src/utils/logger.ts"
    click ID "https://github.com/Telemetree/telemetree-pixel/blob/main/src/utils/id.ts"
    click DH "https://github.com/Telemetree/telemetree-pixel/blob/main/src/helpers/date.helper.ts"
    click TL "https://github.com/Telemetree/telemetree-pixel/tree/main/src/transports/"
    click HTTP "https://github.com/Telemetree/telemetree-pixel/blob/main/src/transports/http.ts"
```
