# mirrorworld-universe/sonic-code-examples architecture

> Architecture diagram of the GitHub repository mirrorworld-universe/sonic-code-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mirrorworld-universe/sonic-code-examples
- Repository: https://github.com/mirrorworld-universe/sonic-code-examples

## Overview

##### Main Components
- Sonic Blockchain: At the core, all these examples interact with the Sonic blockchain. Represent this as the central external service.
- Typescript-based Code Examples: These include:
- Basic Sonic Operations (fetching balances, sending transactions, memo programs, priority fees, and gRPC interactions)
- SPL Token Operations (minting and transferring SPL tokens, fetching token balances)
- NFT Operations (minting NFTs using Metaplex)
- Pyth Integration (fetching price feeds from the Pyth network)
- Agent Kit (demonstrating AI agent interactions with onchain actions)
- Rust-based Code Examples:
- Rush ECS Framework Examples – illustrating game development examples (including the “position” blueprint for storing/updating entity positions)

##### Out the Relationships and Interactions
- For the TypeScript side, create blocks for “Basic Operations”, “SPL Token”, “NFT”, “Pyth Integration”, and “Agent Kit”. Each block should display how they send/receive data or commands to/from the Sonic blockchain (e.g., using RPC endpoints as configured via environment variables).
- For the Rust example, illustrate the “Rush ECS Framework” as a separate component that also connects to the Sonic blockchain. Within this, show a sub-component like “Position Blueprint”, representing an example of onchain game state management.
- External dependencies where applicable—for example, the Pyth Network (for price feeds) or external API keys used in the Agent Kit (e.g., OpenAI API).

##### Architectural Patterns & Design Principles
- Clearly separate the concerns between the TypeScript examples and Rust (Rush ECS) examples.
- That while this project is not a traditional full-stack application with separate “frontend” and “backend” layers, it still touches on separation of concerns by having distinct modules for each type of operation.
- Reusability and modular design: each sample is self-contained and demonstrates a particular capability or integration, which aids extensibility for developers.

##### Relevant Technologies
- Technologies like Node.js (for executing TypeScript examples, npm management, ts-node execution), Rust (with Cargo for build and dependency management), and associated configuration (like .env for RPC_URL, keys) should be noted.
- Mention integration points like gRPC (for real‑time account updates) and external services (Pyth, OpenAI for Agent Kit).

- To one side, arrange the TypeScript examples by grouping them as:
- Basic Operations (with sub-items: fetch balance, send transaction, memo program, add priority fees, gRPC interaction)
- SPL Token Operations (mint SPL token, send SPL token, fetch token balance)
- NFT Operations (mint NFT)
- Pyth Integration (get price feed)
- Agent Kit (AI agent example)
- A “Rush Quickstart” for general ECS and a “Position Blueprint” submodule (as shown by the directories under rust/rush/)
- Use callouts to indicate technology stacks (e.g., “Node.js, TypeScript, ts-node” for the TS examples, “Rust, Cargo” for the Rush sample)

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Service
    blockchain["Sonic Blockchain (SonicSVM Ecosystem)"]:::external

    %% External Dependencies
    openaiAPI["OpenAI API"]:::external
    pythNetwork["Pyth Network"]:::external

    %% TypeScript Examples Subgraph
    subgraph "TypeScript Examples"
        %% Basic Sonic Operations
        subgraph "Basic Sonic Operations"
            fetchBalance["fetch balance"]:::ts
            sendTransaction["send transaction"]:::ts
            memoProgram["memo program"]:::ts
            addPriorityFees["add priority fees"]:::ts
            grpcInteraction["gRPC interaction"]:::ts
        end

        %% SPL Token Operations
        subgraph "SPL Token Operations"
            mintSPL["mint SPL token"]:::ts
            sendSPL["send SPL token"]:::ts
            fetchTokenBalance["fetch token balance"]:::ts
        end

        %% NFT Operations
        nft["NFT Operations – mint NFT"]:::ts

        %% Pyth Integration
        pyth["Pyth Integration – get price feed"]:::ts

        %% Agent Kit
        agent["Agent Kit – AI agent example"]:::ts
    end

    %% Rust Examples Subgraph
    subgraph "Rust Examples (Rush ECS Framework)"
        rushGeneral["General Rush ECS Example"]:::rust
        subgraph "Position Blueprint"
            positionBlueprint["Position Blueprint"]:::rust
            worldToml["world.toml"]:::rust
        end
    end

    %% Data Flow from TS Examples to Sonic Blockchain
    fetchBalance -->|"calls"| blockchain
    sendTransaction -->|"calls"| blockchain
    memoProgram -->|"calls"| blockchain
    addPriorityFees -->|"calls"| blockchain
    grpcInteraction -->|"calls"| blockchain
    mintSPL -->|"calls"| blockchain
    sendSPL -->|"calls"| blockchain
    fetchTokenBalance -->|"calls"| blockchain
    nft -->|"calls"| blockchain
    pyth -->|"calls"| blockchain
    agent -->|"calls"| blockchain

    %% Data Flow from Rust Examples to Sonic Blockchain
    rushGeneral -->|"calls"| blockchain
    positionBlueprint -->|"calls"| blockchain
    worldToml -->|"calls"| blockchain

    %% External Integrations for TypeScript Modules
    agent -->|"uses"| openaiAPI
    openaiAPI -->|"providesData"| blockchain

    pyth -->|"feeds"| pythNetwork
    pythNetwork -->|"providesPriceFeeds"| blockchain

    %% Click Events for TypeScript Basic Operations
    click fetchBalance "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/fetch-balance.ts"
    click sendTransaction "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/send-transaction.ts"
    click memoProgram "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/memo-program.ts"
    click addPriorityFees "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/add-priority-fees.ts"
    click grpcInteraction "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/gRPC-interaction.ts"

    %% Click Events for SPL Token Operations
    click mintSPL "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/mint-spl-token.ts"
    click sendSPL "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/send-spl-token.ts"
    click fetchTokenBalance "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/basic/fetch-token-balance.ts"

    %% Click Event for NFT Operations
    click nft "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/nft/mint-nft.ts"

    %% Click Event for Pyth Integration
    click pyth "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/pyth/get-price-feed.ts"

    %% Click Event for Agent Kit
    click agent "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/ts/agent-kit/index.ts"

    %% Click Events for Rust Examples
    click rushGeneral "https://github.com/mirrorworld-universe/sonic-code-examples/tree/main/rust/rush/"
    click positionBlueprint "https://github.com/mirrorworld-universe/sonic-code-examples/tree/main/rust/rush/position/blueprint/"
    click worldToml "https://github.com/mirrorworld-universe/sonic-code-examples/blob/main/rust/rush/position/blueprint/world.toml"

    %% Styles
    classDef ts fill:#BBE1FA,stroke:#333,stroke-width:2px;
    classDef rust fill:#FFDDAD,stroke:#333,stroke-width:2px;
    classDef external fill:#FCE4EC,stroke:#333,stroke-width:2px;
```
