# xnomad-ai/core architecture

> Architecture diagram of the GitHub repository xnomad-ai/core, 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/xnomad-ai/core
- Repository: https://github.com/xnomad-ai/core

## Overview

##### Project type and purpose
- This is a full-stack core service focused on supporting AI-NFT operations. It includes capabilities for indexing NFTs, running AI-powered agents (using the Eliza framework), managing a launchpad/marketplace for NFTs, and securely handling wallet services with TEE (Trusted Execution Environment) support (via the Phala Network).
- The project integrates blockchain capabilities (with primary support for Solana and plans for EVM) and leverages modular components for various NFT functionalities like indexing, launching, and secure operations.

##### File structure – key components and directories
- The top-level directories like “src”, “local_dependency”, “scripts”, “test”, and docker-related files indicate a modular structure.
- Within “src”, there are multiple modules such as:
- Address Module (src/address)
- Agent Module (src/agent) for managing AI/NFT agents and account operations.
- Eliza module and packages (src/eliza) that include the core AI agent runtime service and extendable plugins (e.g., a Solana plugin). This clearly shows the application relies on the Eliza framework for its AI capabilities.
- Launchpad Module (src/launchpad) that likely handles the marketplace and NFT launch functionalities.
- NFT Module (src/nft) managing NFT indexing, synchronization, and permission verification.
- Wallet Module (src/wallet) for managing wallet proxy services and wallet-based authentication.
- Shared services (src/shared) which include common services such as authentication, Mongo connections, third-party integrations (Twitter, NFTGo, Birdeye, Solana, etc.) and utility functions.
- The additional configuration files (Dockerfile, docker-compose-core.yml, docker-compose-wallet.yml, and devcontainer setup) show how services are containerized and orchestrated.

##### Main architectural components
- Frontend / API Gateway/Application Interface: While not a traditional “frontend,” the system exposes RESTful API endpoints via various controllers (e.g., address.controller.ts, wallet.controller.ts, launchpad.controller.ts, nft.controller.ts) that serve as the entry points.
- Core Service Layer:
- AI-NFT Indexing Service (located in src/nft)
- AI Agent Runtime Service (under src/agent and src/eliza – capturing the Eliza framework functionality)
- NFT Launchpad / Marketplace functionalities (see src/launchpad)
- Wallet Service (in src/wallet) with its own Docker service for the secure wallet operations.
- Shared Services and Utilities:
- Shared modules managing authentication (src/shared/auth), database connectivity (src/shared/mongo), logging, and various third-party integrations for Twitter, Trading, NFT data, etc.
- External and TEE Environment:
- A TEE component, as explained in the README, that integrates with the Phala Network to power secure NFT operations.
- External blockchain connectivity, particularly for Solana, and planned support for EVM.
- Infrastructure / Containerization:
- Docker and docker-compose files show that different services (e.g., core service vs. wallet service) are deployed with separate container orchestration.
- Development environments are supported by a devcontainer and local-run scripts.

##### Relationships and interactions
- Interactions between client/API requests and the various microservices/modules:
- Incoming requests hit the API controllers (from different modules) which further delegate to specific services (e.g., indexing operations in NFT module, agent management in Agent/Eliza modules).
- The wallet service operates independently as a secure component with its own container, interacting via API calls and having authentication guards in place.
- Shared services are consumed across modules (like authentication, MongoDB connection, and external API integrations).
- The system communicates with the blockchain (Solana, and eventually EVM) and the TEE environment for secure operations via specialized providers defined within the modules (e.g., in the plugin-solana actions and providers).

##### Architectural patterns and design principles
- Modular design using NestJS modules which implies clear separation of concerns.
- Containerization (Docker, Docker Compose) for isolating services—especially for the wallet portion vs. the core business logic.
- Usage of dependency injection and shared utilities, which are evident from the multiple “service” and “module” files scattered across src.
- Support for extensibility in the Eliza framework, represented by the “packages” under src/eliza.
- Emphasis on security through TEE integration.

##### Specific instructive details
- Data flow from external clients → API endpoints → microservices.
- Communication between modules (e.g., between the Wallet Service and shared authentication services).
- Connections from core services to external systems (blockchain nodes, TEE environment, external APIs).
- Rectangles for services/components.
- Clouds for external services like blockchain networks or Phala TEE.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        A["External Client"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        B["API Gateway/Controllers"]:::api
    end

    %% Core Services Layer
    subgraph "Core Services"
        C["Address Module"]:::service
        D["Agent Module (Eliza Framework)"]:::service
        F["Launchpad Module"]:::service
        G["NFT Module"]:::service
        H["Wallet Module"]:::service
        E["Plugin: Solana"]:::service
    end

    %% Shared and Database Layer
    subgraph "Shared Services & Database"
        I["Shared Services & Utilities"]:::shared
        J["Database (MongoDB)"]:::database
    end

    %% External Integrations Layer
    subgraph "External Integrations"
        K["Blockchain (Solana/EVM)"]:::external
        L["TEE Environment (Phala TEE)"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        M["Containerization & Infrastructure"]:::container
    end

    %% Connections
    A --> B
    B --> C
    B --> D
    B --> F
    B --> G
    B --> H

    D --> E
    E -->|"connects"| K
    G -->|"syncs"| K
    H -->|"secure-ops"| L

    C --> I
    D --> I
    F --> I
    G --> I
    H --> I
    I -->|"db"| J

    M -->|"deployed"| B
    M -->|"deployed"| H
    M -->|"deployed"| I

    %% Styles
    classDef api fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef service fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef container fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef shared fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef database fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;

    %% Click Events
    click C "https://github.com/xnomad-ai/core/tree/main/src/address"
    click D "https://github.com/xnomad-ai/core/tree/main/src/agent"
    click D "https://github.com/xnomad-ai/core/tree/main/src/eliza"
    click E "https://github.com/xnomad-ai/core/tree/main/src/eliza/packages/plugin-solana"
    click F "https://github.com/xnomad-ai/core/tree/main/src/launchpad"
    click G "https://github.com/xnomad-ai/core/tree/main/src/nft"
    click H "https://github.com/xnomad-ai/core/tree/main/src/wallet"
    click H "https://github.com/xnomad-ai/core/blob/main/src/main-wallet-service.ts"
    click I "https://github.com/xnomad-ai/core/tree/main/src/shared"
    click L "https://github.com/xnomad-ai/core/blob/main/src/shared/phala.service.ts"
    click M "https://github.com/xnomad-ai/core/tree/main/Dockerfile"
    click M "https://github.com/xnomad-ai/core/blob/main/docker-compose-core.yml"
    click M "https://github.com/xnomad-ai/core/blob/main/docker-compose-wallet.yml"
    click M "https://github.com/xnomad-ai/core/blob/main/.devcontainer"
```
