# staking-facilities-gmbh/tidal architecture

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

- Interactive diagram: https://gitdiagram.com/staking-facilities-gmbh/tidal
- Repository: https://github.com/staking-facilities-gmbh/tidal

## Overview

##### Project Type and Purpose
- Tidal is a full-stack decentralized asset trading platform (dApp) built on the Sui blockchain.
- Core functions: encrypted file storage/trading, on-chain asset registration, subscription/access control.

##### File Structure & README
- Frontend (React + Vite + Typescript + Supabase client + Seal/Walrus SDKs)
- Smart contracts in Move (sources under move/sources) plus tests
- Supabase migrations for metadata
- No traditional “backend” server: business logic split between on-chain Move contracts and off-chain services (Supabase, Walrus, Seal).

##### Main Components
a. Frontend Client
- React/Vite app (frontend/src)
- Pages: asset creation, store, user purchases
- Uses Seal SDK, Walrus SDK, Supabase client, Sui RPC (via networkConfig.ts)
b. Sui Blockchain (On-chain Layer)
- Move contracts for assets, allowlists, payments, subscriptions
- Invoked via Sui RPC from frontend
c. Encryption Layer (Seal)
- Seal SDK running in frontend (gif.worker.js) for encrypt/decrypt
- Key servers for session key management (external service)
d. Storage Layer (Walrus)
- Encrypted blob storage providers (via Walrus SDK)
- Returns content-addressed URLs
e. Database Layer (Supabase)
- PostgreSQL metadata tables (assets, purchases) via Supabase migrations
- Stores file references & user records
f. External Services & Infrastructure
- Supabase instance (hosted)
- Sui node/RPC endpoint
- Key servers for Seal
- Walrus storage providers
- Vercel (or similar) hosting for frontend

##### Relationships & Data Flows
- Asset Creation Flow:
User → Frontend → Seal SDK (Encrypt) → Walrus Store → Frontend → Sui RPC (Move.create_asset) → Frontend → Supabase (insert metadata)
- Asset Purchase Flow:
User → Frontend → Sui RPC (Move.payment) → Frontend → Seal SDK (verify access + session key) → Frontend → Walrus (get encrypted blob) → Seal SDK (decrypt) → User
- Metadata Queries: Frontend ↔ Supabase (list assets, purchases)
- On-chain State: Move contracts maintain allowlists and ownership.

##### Architectural Patterns & Design Principles
- Layered Separation:
- Presentation (React)
- Business Logic (Move contracts)
- Off-chain Services (Supabase, Seal, Walrus)
- Security by Design:
- End-to-end encryption (Seal)
- On-chain access control (allowlists)
- Content addressing & redundancy (Walrus)
- Micro-integrations: each service has a single responsibility and is consumed directly by the frontend.

##### Final Checklist
[ ] All major components represented with clear labels

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Client"
        direction TB
        ReactApp["React/Vite App"]:::client
        subgraph "Pages"
            direction TB
            CreateAssetPage["Create Asset Page"]:::client
            StorePage["Store Page"]:::client
            UserPurchasesPage["User Purchases Page"]:::client
            CreateSubscriptionPage["Create Subscription Service"]:::client
            SubscriptionDetailPage["Subscription Service Detail"]:::client
            SubscriptionViewPage["Subscription View"]:::client
            CreateAllowlistPage["Create Allowlist"]:::client
            AllowlistViewPage["Allowlist View"]:::client
            OwnedAllowlistsPage["Owned Allowlists"]:::client
        end
        NetworkConfig["networkConfig.ts"]:::client
        SupabaseUtil["supabase.ts"]:::client
        EncryptAndUpload["EncryptAndUpload Component"]:::client
        EncryptedUpload["EncryptedUpload Component"]:::client
        WalrusUpload["WalrusUpload Component"]:::client
        UseAssetsHook["useAssets Hook"]:::client
        TidalSubscriptionService["TidalSubscriptionService"]:::client
        MainApp["App.tsx"]:::client
        EntryScript["main.tsx"]:::client
    end

    %% On-chain Layer
    subgraph "Sui Blockchain (On-chain)" 
        direction TB
        MoveCore["tidal.move"]:::onchain
        MoveUtils["utils.move"]:::onchain
        MoveTests["tidal_tests.move"]:::onchain
    end

    %% Off-chain Services
    subgraph "Off-chain Services"
        direction TB
        SealSDK["Seal SDK (gif.worker.js)"]:::offchain
        WalrusSDK["Walrus SDK"]:::offchain
        subgraph "Supabase"
            direction TB
            SupabaseClient["Supabase Client"]:::offchain
            SupabaseDB["Postgres Metadata DB"]:::offchain
        end
    end

    %% External Infrastructure
    subgraph "External Services"
        direction TB
        SuiRPC["Sui RPC Endpoint"]:::external
        KeyServers["Seal Key Servers"]:::external
        WalrusProviders["Walrus Storage Providers"]:::external
        SupabaseHost["Supabase Instance"]:::external
        Vercel["Vercel Hosting"]:::external
    end

    %% Data Flows - Asset Creation
    ReactApp -->|"encrypt via Seal SDK"| SealSDK
    SealSDK -->|"upload encrypted blob"| WalrusProviders
    WalrusProviders -->|"return content URL"| ReactApp
    ReactApp -->|"create asset on-chain"| SuiRPC
    SuiRPC -->|"invoke Move.create_asset"| MoveCore
    MoveCore -->|"transaction confirmed"| ReactApp
    ReactApp -->|"insert metadata"| SupabaseClient
    SupabaseClient -->|"write metadata"| SupabaseDB

    %% Data Flows - Asset Purchase
    ReactApp -->|"payment txn"| SuiRPC
    SuiRPC -->|"invoke Move.payment"| MoveCore
    MoveCore -->|"txn confirmed"| ReactApp
    ReactApp -->|"request session key"| SealSDK
    SealSDK -->|"session key from"| KeyServers
    ReactApp -->|"fetch encrypted blob"| WalrusProviders
    ReactApp -->|"decrypt blob"| SealSDK
    SealSDK -->|"deliver plaintext asset"| ReactApp

    %% Metadata Queries
    ReactApp <-->|"list assets/purchases"| SupabaseClient
    SupabaseClient -->|"read metadata"| SupabaseDB

    %% Access Control On-chain
    ReactApp -->|"manage allowlist"| SuiRPC
    SuiRPC --> MoveCore

    %% Hooks and utilities usage
    ReactApp --> UseAssetsHook
    ReactApp --> NetworkConfig
    ReactApp --> SupabaseUtil

    %% Click Events
    click ReactApp "https://github.com/staking-facilities-gmbh/tidal/tree/main/frontend/src"
    click CreateAssetPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/pages/CreateAssetPage.tsx"
    click StorePage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/pages/StorePage.tsx"
    click UserPurchasesPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/pages/UserPurchasesPage.tsx"
    click NetworkConfig "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/networkConfig.ts"
    click SupabaseUtil "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/utils/supabase.ts"
    click EncryptAndUpload "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/EncryptAndUpload.tsx"
    click EncryptedUpload "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/components/upload/EncryptedUpload.tsx"
    click WalrusUpload "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/WalrusUpload.tsx"
    click MoveCore "https://github.com/staking-facilities-gmbh/tidal/blob/main/move/sources/tidal.move"
    click MoveUtils "https://github.com/staking-facilities-gmbh/tidal/blob/main/move/sources/utils.move"
    click MoveTests "https://github.com/staking-facilities-gmbh/tidal/blob/main/move/tests/tidal_tests.move"
    click SupabaseClient "https://github.com/staking-facilities-gmbh/tidal/tree/main/frontend/supabase/migrations/"
    click EntryScript "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/main.tsx"
    click MainApp "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/App.tsx"
    click TidalSubscriptionService "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/TidalSubscriptionService.tsx"
    click CreateSubscriptionPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/CreateSubscriptionService.tsx"
    click SubscriptionDetailPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/SubscriptionService.tsx"
    click SubscriptionViewPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/SubscriptionView.tsx"
    click CreateAllowlistPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/CreateAllowlist.tsx"
    click AllowlistViewPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/AllowlistView.tsx"
    click OwnedAllowlistsPage "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/src/OwnedAllowlists.tsx"
    click SupabaseDB "https://github.com/staking-facilities-gmbh/tidal/blob/main/frontend/supabase/config.toml"

    %% Styling
    classDef client fill:#f9d5b3,stroke:#333,stroke-width:1px
    classDef onchain fill:#c2e0f4,stroke:#333,stroke-width:1px
    classDef offchain fill:#d5f5e3,stroke:#333,stroke-width:1px
    classDef external fill:#f0e68c,stroke:#333,stroke-width:1px
```
