# Architecture

{% hint style="info" %}
You can also add images simply by copying and pasting them directly into the editor — and GitBook will automatically add it to your file manager.
{% endhint %}

<figure><img src="/files/EimPRLsOtBrfpqF0y7gN" alt=""><figcaption></figcaption></figure>

#### System Architecture & Data Flow

Lixer's architecture is an event-driven system designed for high throughput and low latency. The flow of data from the blockchain to the end-user can be broken down into several key stages:

1. **Data Ingestion (Goldsky Subgraphs & Mirror):** The entire process begins with Goldsky.
   * **Historical Data Path:** A custom **GraphQL Subgraph** is deployed to index all historical `Swap` events from the HyperSwap V3 factory and its pools. This subgraph defines the schema (Pools, Swaps, Tokens) and contains mapping logic to decode and process Ethereum logs into structured data, which is then stored in a queryable GraphQL endpoint.
   * **Real-time Data Path:** A **Goldsky Mirror** pipeline is configured to subscribe to new blocks on the HyperEVM chain. It filters these blocks for logs emitted from a predefined set of HyperSwap V3 pool addresses. Using the contract ABI, it decodes these logs in real-time.
2. **Data Storage & Triggering (PostgreSQL):** The decoded swap data from the Mirror pipeline is streamed directly into a **PostgreSQL** database. This is a crucial integration point.
   * The database acts as the single source of truth for real-time and recent historical data.
   * Goldsky's mirror is configured with a **trigger**. Upon every `INSERT` of a new swap event into the database, this trigger automatically sends a payload (the new swap data) to a webhook URL configured in our API Server.
3. **Data Serving (Lixer API Server):** The Express.js server is the core orchestrator.
   * **REST Endpoints:** It exposes RESTful APIs that query the PostgreSQL database to serve paginated and filterable historical data (e.g., `GET /swaps`, `GET /pools`).
   * **WebSocket Endpoint:** It exposes a `WebSocket (/ws)` endpoint for clients to connect to.
   * **Webhook Listener:** It listens for the webhook calls from the PostgreSQL trigger. When a new swap event is received via this webhook, the API server immediately broadcasts this event as a JSON message to **all connected WebSocket clients**. This is the mechanism that enables sub-second latency for real-time updates.
4. **Data Consumption (Lixer SDK & Dashboard):** The final layer is the client-side consumption.
   * The **Lixer SDK** provides a simple interface for developers. Its `swaps().getAll()` method calls the REST API, while the `websocket().connect()` method establishes a connection to the real-time WebSocket stream.
   * The **Analytics Dashboard** is a prime example of a consumer, using the SDK to display both historical charts and a live event feed.

<figure><img src="/files/kwAwgNZSL9UgIwA3MvEc" alt=""><figcaption></figcaption></figure>

The following diagram illustrates this seamless data flow:

text

```
[HyperEVM Blockchain] (Emit Logs)
          |
          v
[Goldsky Infrastructure]
    |                  |
    |-> [Subgraph] -> [GraphQL Endpoint] (For historical queries) 
    |
    |-> [Mirror Pipeline] -> [PostgreSQL DB] (Sinks decoded data)
          |                         |
          |                         | (DB Trigger on INSERT)
          |                         v
          |                 [Lixer API Server] (Webhook Listener)
          |                         |
          |                         | (Broadcast via WebSocket)
          |                         v
          |                 [Connected Clients (SDK, Dashboard)]
          |
          |----------------->> (Real-time path)
          |---------------------------------->> (Historical path)
```

#### Key Technical Decisions

1. **Goldsky for Infrastructure:** Building a reliable, low-latency indexing system from scratch is a massive engineering undertaking. By leveraging **Goldsky's managed subgraphs and mirror pipelines**, we avoided the complexity of managing blockchain nodes, syncing data, handling re-orgs, and building decoding logic from the ground up. This allowed us to focus on delivering value through our API and SDK.
2. **PostgreSQL with Triggers:** Using the database as a message broker via triggers is a powerful and efficient pattern. It offloads the responsibility of detecting new events from our application code to the database, which is extremely fast at this task. This ensures no swap event is missed and is broadcasted instantly.
3. **Stateless API Server:** The API server is designed to be stateless. It does not hold any active connection data internally; WebSocket connections are managed by the underlying WS library. This allows for easy horizontal scaling to handle a large number of concurrent connections.
4. **Zero-Config SDK:** The decision to provide a hosted API and a zero-configuration SDK drastically reduces the barrier to entry for developers. They can get started with real-time blockchain data in less than a minute, without worrying about infrastructure, authentication, or rate limiting.

#### Database Schema (Simplified)

The core of the system is the `swaps` table in PostgreSQL, which is populated by the Goldsky Mirror pipeline. Its structure mirrors the SDK's `SwapEvent` interface:

sql

```
CREATE TABLE swaps (
    id VARCHAR PRIMARY KEY,           -- Unique identifier (e.g., tx_hash-log_index)
    block_number INTEGER NOT NULL,
    block_hash VARCHAR NOT NULL,
    transaction_hash VARCHAR NOT NULL,
    log_index INTEGER NOT NULL,
    pool_address VARCHAR NOT NULL,    -- Address of the pool where the swap occurred
    "timestamp" INTEGER NOT NULL,     -- Unix timestamp
    sender VARCHAR,
    recipient VARCHAR,
    amount0 VARCHAR,                  -- Stores raw Wei amount as a string to preserve precision
    amount1 VARCHAR,
    sqrt_price_x96 VARCHAR,
    liquidity VARCHAR,
    tick VARCHAR
);
-- Indexes are created on common query fields like block_number, timestamp, and pool_address for performance.
```

#### Handling Chain Reorganizations

A critical challenge in blockchain indexing is handling chain reorganizations (re-orgs), where blocks are orphaned. Goldsky's infrastructure handles this gracefully:

* The **Mirror pipeline** is designed to be re-org aware. If a re-org occurs, Goldsky automatically detects it and rolls back the affected data in the PostgreSQL sink, ensuring our database state always reflects the canonical chain.
* This means the data served by the Lixer API is always accurate and consistent with the longest chain, without requiring any custom logic in our application layer.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ironjams-organization.gitbook.io/lixer-docs/getting-started/images-and-media.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.