# piotrostr/listen architecture

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

- Interactive diagram: https://gitdiagram.com/piotrostr/listen
- Repository: https://github.com/piotrostr/listen

## Overview

Based on our analysis of the provided file tree and README, the project is an advanced, multi-service framework for algorithmic trading on the Solana blockchain. It’s structured around several interrelated components, each with its own microservice or module (such as the trading engine, data service, and the agent kit) that are deployed both as Rust services and web interfaces. The system integrates with external services like blockchain nodes, wallet management systems (via Privy), and a mobile dashboard. The architecture follows a modular design with clear responsibilities for data ingest, trade execution, and user interaction, while also offering plug’n’play integration with AI portfolio management agents.

##### Main components
- Rig Agent Kit – Contains submodules such as the Multi-tenant Stream Manager and Delegated Wallet Manager. This component handles tool calls to the blockchain and interacts with user inputs from the mobile side.
- Listen Trading Engine – Composed of internal modules including the Order Collector, Pipeline Executor, and Order Executor. It is responsible for assembling trade orders, executing pipeline processes, and signing/sending transactions to the blockchain.
- Listen Data Service – Responsible for real-time data ingestion and analytics. It includes components like the Substreams Indexer (for indexing Solana slots), price stream processing, and integration with an OLAP database (Clickhouse).
- External Systems – Include mobile applications (user interface), blockchain networks (Solana/EVM), wallet integrations (via Privy), and potentially any 3rd-party APIs.

##### Relationships and interactions
- That the Trading Engine’s flow starts with the Order Collector, flows through the Pipeline Executor, and then leads to the Order Executor for verifying and sending transactions.
- That the Data Service continuously feeds pricing updates and enriched data to both the Trading Engine and the external mobile app.
- That the Delegated Wallet Manager, part of the Rig Agent Kit, is responsible for integrating with Privy, which subsequently interacts with external wallet systems.

##### Architectural patterns and design principles
- Microservice and modular architecture: Several distinct Rust-based services (listen-adapter, listen-engine, listen-data, listen-interface, listen-kit, etc.) are designed to operate independently but interact through well-defined APIs and data streams.
- Separation of concerns: The system clearly separates data ingestion/processing (Data Service), trade decision logic (Trading Engine), and user/agent interaction (Rig Agent Kit and interfaces).
- Integration with external frameworks: The project plugs into the [$arc rig framework] and integrates closely with blockchain components using a common messaging or API layer.
- Use of infrastructure as code: The presence of Terraform and Ansible directories shows that deployment and configuration management are also factored in.

##### Technologies and frameworks
- Programming language: Rust is the primary language throughout the services.
- Blockchain: Integration with Solana/EVM.
- Data store: Clickhouse for OLAP queries.
- CI/CD and container orchestration: Docker, Docker Compose, Terraform, and Ansible.
- Web stack: The listen-interface and listen-landing directories indicate a modern TypeScript/React/Vite frontend with Tailwind CSS.

- Clear labels for each major component (e.g., “Rig Agent Kit”, “Trading Engine”, “Data Service”).
- Subdivisions: Show internal modules like “Multi-tenant Stream Manager”, “Order Collector”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rust Microservices
    subgraph "Rust Microservices"
        RA["Rig Agent Kit"]:::microservice
        subgraph "Rig Agent Kit Modules"
            MT["Multi-tenant Stream Manager"]:::microservice
            DW["Delegated Wallet Manager"]:::microservice
        end
        TE["Trading Engine"]:::microservice
        subgraph "Trading Engine Modules"
            OC["Order Collector"]:::microservice
            PE["Pipeline Executor"]:::microservice
            OE["Order Executor"]:::microservice
        end
        DS["Data Service"]:::microservice
        subgraph "Data Service Modules"
            SI["Substreams Indexer"]:::microservice
            PP["Price Stream Processing"]:::microservice
            CH["Clickhouse OLAP DB"]:::datastore
        end
    end

    %% External Integrations
    subgraph "External Integrations"
        BC["Blockchain Connections"]:::external
        WI["Wallet Integration"]:::external
        WD["Web Dashboard"]:::frontend
        MD["Mobile Demo UI"]:::frontend
    end

    %% Interactions and Data Flow
    RA -->|"interfaces"| TE
    RA -->|"sends_tool_calls"| BC
    DW -->|"integrates_wallet"| WI

    TE --> OC
    OC --> PE
    PE --> OE
    OE -->|"sends_tx"| BC

    DS -->|"feeds_pricing"| TE
    DS -->|"data_feed"| WD
    DS -->|"data_feed"| MD

    %% Click Events
    click RA "https://github.com/piotrostr/listen/tree/main/listen-kit/"
    click TE "https://github.com/piotrostr/listen/tree/main/listen-engine/"
    click DS "https://github.com/piotrostr/listen/tree/main/listen-data/"
    click WD "https://github.com/piotrostr/listen/tree/main/listen-interface/"
    click MD "https://github.com/piotrostr/listen/tree/main/listen-landing/"
    click WI "https://github.com/piotrostr/listen/tree/main/privy/"
    click BC "https://github.com/piotrostr/listen/tree/main/listen-adapter/"

    %% Styles
    classDef microservice fill:#a2d9ce,stroke:#1e8449,stroke-width:2px;
    classDef datastore fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef frontend fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
```
