# rpcpool/yellowstone-vixen architecture

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

- Interactive diagram: https://gitdiagram.com/rpcpool/yellowstone-vixen
- Repository: https://github.com/rpcpool/yellowstone-vixen

## Overview

##### Project Type and Purpose
- Yellowstone Vixen is an open-source Rust framework for building program-aware, real-time Solana data pipelines.
- It consumes gRPC streams (Dragon’s Mouth), routes raw on-chain events through pluggable parsers, and invokes user-provided handlers to log, store, or forward structured data.

##### File Structure at a Glance
- Top-level: CI configs (.github), Cargo.toml, examples/, docker-compose.yaml, Vixen.example.toml
- crates/:
- core: shared instruction & account types
- runtime: orchestrates pipelines, metrics, filters
- parser crates (e.g., boop-parser, jupiter-swap-parser, …): each contains an IDL, build.rs, generated_parser, generated_sdk
- solana-rpc-source & solana-snapshot-source: source adapters
- stream & grpc-source crates: gRPC server & client
- mock: offline testing fixtures
- examples/: minimal applications demonstrating runtime+parsers+handlers

##### Key Insights from README
- Parser+Handler architecture
- gRPC subscription via Dragon’s Mouth
- Prometheus metrics endpoint
- Offline testing of parsers

##### Main Components
A. Data Sources (plugins/adapters)
- Dragon’s Mouth gRPC stream ← solana-rpc-source
- Solana snapshot plugin ← solana-snapshot-source
B. Runtime Core
- Pipeline builder (builder.rs)
- Filter pipeline (filter_pipeline.rs)
- Handler dispatcher (handler.rs)
- Metrics collector (metrics.rs / Prometheus)
C. Parser Plugins
- One parser crate per Solana program
- build.rs → IDL → generated_parser (binary layout) + generated_sdk (Rust types)
D. Handler Interface
- Generic Handler<V> trait
- User-provided implementations (e.g., Logger, database writer, custom gRPC sink)
E. Output & Integrations
- Local logging / console
- Prometheus /metrics
- gRPC server (yellowstone-grpc-source)
- Optional database or downstream systems

##### Relationships & Data Flow
1. Configuration (Vixen.toml) initializes Runtime via CLI binary.
2. Runtime connects to one or more Data Sources.
3. Incoming blocks/transactions flow through Filter Pipeline.
4. Events are dispatched to AccountParser or InstructionParser from the selected parser crates.
5. Parsers emit structured Rust types (SDK types).
6. Runtime invokes Handler<V>::handle for each parsed value.
7. Handlers perform side-effects (log, store, forward).
8. Metrics (throughput, lag, errors) exposed on /metrics.
9. Optionally, parsed events are served over gRPC to clients.

##### Architectural Patterns & Principles
- Plugin Architecture: parser crates discovered at compile time via Cargo features.
- Builder Pattern: Runtime::builder() configures pipelines, metrics, commitment.
- Separation of Concerns: sources ↔ runtime ↔ parsers ↔ handlers
- Extensibility: add a new parser crate + register with Runtime → immediate support.
- Observability: built-in Prometheus metrics.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Sources"
        DRAGON["Dragon’s Mouth gRPC Stream"]:::source
        SNAP["Solana Snapshot Plugin"]:::source
    end

    subgraph "Core Types"
        CORE_LIB["Core Types (Instruction & Account)"]:::core
    end

    subgraph "Runtime Core"
        CONFIG["Config Loader"]:::core
        BUILDER["Pipeline Builder"]:::core
        FILTER["Filter Pipeline"]:::core
        DISPATCH["Handler Dispatcher"]:::core
        METRICS_COLLECTOR["Metrics Collector"]:::core
    end

    subgraph "Parser Plugins"
        BOOP_IDL["IDL"]:::parser
        BOOP_BUILD["build.rs"]:::parser
        BOOP_PARSER["generated_parser"]:::parser
        BOOP_SDK["generated_sdk"]:::parser
    end

    subgraph "Handlers & Outputs"
        LOG["Local Logging"]:::handler
        PROM_HANDLER["Example Prometheus Handler"]:::handler
        OTEL_HANDLER["Example OpenTelemetry Handler"]:::handler
        GRPC_OUT["gRPC Output Server"]:::handler
        METRICS_ENDPOINT["/metrics Endpoint"]:::external
    end

    CONFIG --> BUILDER
    BUILDER --> DRAGON
    BUILDER --> SNAP
    DRAGON --> FILTER
    SNAP --> FILTER
    FILTER --> BOOP_PARSER
    BOOP_IDL --> BOOP_BUILD
    BOOP_BUILD --> BOOP_PARSER
    BOOP_BUILD --> BOOP_SDK
    BOOP_PARSER --> DISPATCH
    DISPATCH --> LOG
    DISPATCH --> PROM_HANDLER
    DISPATCH --> OTEL_HANDLER
    DISPATCH --> GRPC_OUT
    DISPATCH --> METRICS_COLLECTOR
    METRICS_COLLECTOR --> METRICS_ENDPOINT

    click DRAGON "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/solana-rpc-source/src/lib.rs"
    click SNAP "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/solana-snapshot-source/src/lib.rs"
    click CONFIG "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/runtime/src/config.rs"
    click BUILDER "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/runtime/src/builder.rs"
    click FILTER "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/runtime/src/filter_pipeline.rs"
    click DISPATCH "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/runtime/src/handler.rs"
    click METRICS_COLLECTOR "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/runtime/src/metrics.rs"
    click CORE_LIB "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/core/src/lib.rs"
    click BOOP_IDL "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/boop-parser/idl.json"
    click BOOP_BUILD "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/boop-parser/build.rs"
    click BOOP_PARSER "https://github.com/rpcpool/yellowstone-vixen/tree/main/crates/boop-parser/src/generated_parser/"
    click BOOP_SDK "https://github.com/rpcpool/yellowstone-vixen/tree/main/crates/boop-parser/src/generated_sdk/"
    click PROM_HANDLER "https://github.com/rpcpool/yellowstone-vixen/blob/main/examples/prometheus/src/main.rs"
    click OTEL_HANDLER "https://github.com/rpcpool/yellowstone-vixen/blob/main/examples/opentelemetry/src/main.rs"
    click GRPC_OUT "https://github.com/rpcpool/yellowstone-vixen/blob/main/crates/yellowstone-grpc-source/src/lib.rs"

    classDef source fill:#ADD8E6,stroke:#000
    classDef parser fill:#90EE90,stroke:#000
    classDef core fill:#FFA500,stroke:#000
    classDef handler fill:#DDA0DD,stroke:#000
    classDef external fill:#F0E68C,stroke:#000
```
