# ivelinweb/unitedstatesofagents architecture

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

- Interactive diagram: https://gitdiagram.com/ivelinweb/unitedstatesofagents
- Repository: https://github.com/ivelinweb/unitedstatesofagents

## Overview

##### Project type & purpose
- Full-stack decentralized metaverse dApp (“Network State of AI Agents”)
- On-chain smart contracts for token & network state (Hardhat + Ignition)
- Next.js frontend with Phaser game engine, AI agent orchestration via serverless API

##### Main components
A. Frontend (Next.js + React + Tailwind + Shadcn)
- UI pages: `frontend/src/pages/*`
- UI components: `frontend/src/components/*`
- Game engine: `frontend/src/game/*` (Phaser scenes + EventBus)
- Web3 provider: `frontend/src/components/connection/WagmiProvider.tsx`, `ConnectWallet.tsx`
- Utilities: `frontend/src/lib/firebase.ts`, `wagmiConfig.ts`, `wagmiContractConfig.ts`, `formatData.ts`
- Static resources: `frontend/public/assets`, `resources/*.tmx`
B. API layer (Next.js serverless functions)
- Agent orchestration: `frontend/src/pages/api/coinbase-agents/*` (roles, actions, agent wrappers, contract bridges)
- Specialized routes: `travelling-salesman.ts`
- Integrations: OpenAI via LangChain modules embedded in API routes
C. Blockchain network
- Target: Sei EVM Testnet (chainID 1328, plus chains 1114 & 84532 in Ignition)
- JSON-RPC endpoint (https://evm-rpc-testnet.sei-apis.com)
- Explorer (seitrace.com)
D. Smart contracts (Solidity)
- Modules: `NetworkStateModule`, `USATokenModule`
- Config & scripts: `contract/hardhat.config.js`, `contract/scripts/*.js`
- Artifacts & builds: `contract/artifacts/*`, `contract/ignition/deployments/*`
- Tests: `contract/test/*.js`
E. External services
- OpenAI API (via LangChain) for agent intelligence
- Firebase (user data / session)
- Coinbase-agents off-chain SDK for tokenSwap & sentiment analysis

##### Relationships & data flows
- User interacts with Next.js UI → requests wallet connection → WagmiProvider injects Web3 → user signs transactions
- Frontend dispatches contract calls via Wagmi/Viem → JSON-RPC → Smart Contracts on chain → events & state updates
- Phaser Game scenes emit/consume events via EventBus → route through UI/Web3 for on-chain interactions
- UI/API functions call Next.js serverless endpoints → orchestrate agent logic (LangChain/OpenAI + contract read/writes) → return results to UI
- Deployment pipeline (Hardhat + Ignition) → generates artifacts & deployed_addresses → consumed by frontend’s contract.ts adapters

##### Architectural patterns & design principles
- Layered architecture:
- Presentation (Next.js UI & Phaser)
- Application (API routes & agent services)
- Blockchain (Smart Contracts)
- Data/External (Firebase, OpenAI, RPC Node)
- Modular smart contracts for composability
- Serverless functions as micro-services for agent orchestration
- Event-driven game loop (Phaser EventBus)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        direction TB
        Pages["UI Pages"]:::frontend
        Components["UI Components"]:::frontend
        GameEngine["Phaser Game Engine"]:::frontend
        WagmiProv["WagmiProvider.tsx"]:::frontend
        ConnectWallet["ConnectWallet.tsx"]:::frontend
        Firebase["firebase.ts"]:::frontend
        FormatData["formatData.ts"]:::frontend
        WagmiConfig["wagmiConfig.ts"]:::frontend
        ContractConfig["wagmiContractConfig.ts"]:::frontend
        Assets["Static Resources"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Serverless Functions)"
        direction TB
        CommonActions["commonActions.ts"]:::api
        Roles["roles.js"]:::api
        TokenActions["tokenSwapperAgent/actions.ts"]:::api
        TokenAgent["tokenSwapperAgent/agent.ts"]:::api
        TwitterActions["twitterAnalysisAgent/actions.ts"]:::api
        TwitterAgent["twitterAnalysisAgent/agent.ts"]:::api
        TwitterContract["twitterAnalysisAgent/contract.ts"]:::api
        TravellingSalesman["travelling-salesman.ts"]:::api
    end

    %% Web3 Provider Layer
    subgraph "Web3 Layer"
        direction TB
        RPC["JSON-RPC Endpoint"]:::external
        Explorer["Blockchain Explorer"]:::external
    end

    %% Blockchain Network & Smart Contracts
    subgraph "Blockchain & Smart Contracts"
        direction TB
        NetworkState["NetworkStateModule.sol"]:::blockchain
        USAToken["USATokenModule.sol"]:::blockchain
        HardhatConfig["hardhat.config.js"]:::blockchain
        DeployScripts["deploy scripts"]:::blockchain
        Artifacts["Hardhat Artifacts"]:::blockchain
        Ignition["Ignition Deployments"]:::blockchain
        Tests["NetworkState.js (tests)"]:::blockchain
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        FirebaseSvc["Firebase"]:::external
        CoinbaseSDK["Coinbase Agents SDK"]:::external
    end

    %% Flows
    Pages -->|"uses"| Components
    Pages -->|"renders"| GameEngine
    Pages -->|"calls"| WagmiProv
    WagmiProv -->|"provides"| ConnectWallet
    Pages -->|"imports"| Firebase
    Pages -->|"imports"| FormatData
    Pages -->|"imports"| WagmiConfig
    Pages -->|"imports"| ContractConfig
    Pages -->|"loads"| Assets

    Pages -->|"HTTP"| CommonActions
    CommonActions --> Roles
    Roles --> TokenActions
    TokenActions --> TokenAgent
    Roles --> TwitterActions
    TwitterActions --> TwitterAgent
    TwitterAgent --> TwitterContract
    Pages -->|"HTTP"| TravellingSalesman

    ConnectWallet -->|".eth transactions"| RPC
    TokenAgent -->|".eth calls"| RPC
    TwitterAgent -->|".eth calls"| RPC

    RPC -->|JSON-RPC| NetworkState
    RPC -->|JSON-RPC| USAToken

    NetworkState -->|events| Pages
    USAToken -->|events| Pages

    HardhatConfig --> DeployScripts
    DeployScripts --> Artifacts
    DeployScripts --> Ignition
    Tests --> Artifacts

    OpenAI --> TwitterActions
    FirebaseSvc --> Pages
    CoinbaseSDK --> TokenActions

    Explorer -.-> RPC

    %% Click Events
    click Pages "https://github.com/ivelinweb/unitedstatesofagents/tree/main/frontend/src/pages/"
    click Components "https://github.com/ivelinweb/unitedstatesofagents/tree/main/frontend/src/components/"
    click GameEngine "https://github.com/ivelinweb/unitedstatesofagents/tree/main/frontend/src/game/"
    click WagmiProv "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/components/connection/WagmiProvider.tsx"
    click ConnectWallet "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/components/connection/ConnectWallet.tsx"
    click Firebase "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/lib/firebase.ts"
    click FormatData "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/utils/formatData.ts"
    click WagmiConfig "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/utils/wagmiConfig.ts"
    click ContractConfig "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/utils/wagmiContractConfig.ts"
    click Assets "https://github.com/ivelinweb/unitedstatesofagents/tree/main/frontend/public/assets/"
    click CommonActions "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/commonActions.ts"
    click Roles "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/roles.js"
    click TokenActions "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/tokenSwapperAgent/actions.ts"
    click TokenAgent "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/tokenSwapperAgent/agent.ts"
    click TwitterActions "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/twitterAnalysisAgent/actions.ts"
    click TwitterAgent "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/twitterAnalysisAgent/agent.ts"
    click TwitterContract "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/coinbase-agents/twitterAnalysisAgent/contract.ts"
    click TravellingSalesman "https://github.com/ivelinweb/unitedstatesofagents/blob/main/frontend/src/pages/api/travelling-salesman.ts"
    click NetworkState "https://github.com/ivelinweb/unitedstatesofagents/blob/main/contract/contracts/NetworkStateModule.sol"
    click USAToken "https://github.com/ivelinweb/unitedstatesofagents/blob/main/contract/contracts/USATokenModule.sol"
    click HardhatConfig "https://github.com/ivelinweb/unitedstatesofagents/blob/main/contract/hardhat.config.js"
    click DeployScripts "https://github.com/ivelinweb/unitedstatesofagents/blob/main/contract/scripts/deploy.js"
    click Artifacts "https://github.com/ivelinweb/unitedstatesofagents/tree/main/contract/artifacts/"
    click Ignition "https://github.com/ivelinweb/unitedstatesofagents/tree/main/contract/ignition/deployments/chain-1328/"
    click Tests "https://github.com/ivelinweb/unitedstatesofagents/blob/main/contract/test/NetworkState.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0A3D62,color:#0A3D62
    classDef api fill:#DFFFE0,stroke:#218C74,color:#218C74
    classDef blockchain fill:#FFE4B5,stroke:#E67E22,color:#E67E22
    classDef external fill:#E0D0FF,stroke:#6C5CE7,color:#6C5CE7
```
