> ## Documentation Index
> Fetch the complete documentation index at: https://www.propeldata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Learn about Propel's cloud-native ClickHouse® architecture.

<div />

Propel combines the speed of ClickHouse with a fully managed, cloud-native serverless platform.

<Frame caption="Propel's architecture">
  <img className="block dark:hidden" src="https://mintcdn.com/propeldocs/9FdNDTkhOu7EgAUd/images/docs/main_architecture_diagram_light.svg?fit=max&auto=format&n=9FdNDTkhOu7EgAUd&q=85&s=31f3e41fbc63372abe09d1ebe5635f23" width="717" height="429" data-path="images/docs/main_architecture_diagram_light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/propeldocs/9FdNDTkhOu7EgAUd/images/docs/main_architecture_diagram_dark.svg?fit=max&auto=format&n=9FdNDTkhOu7EgAUd&q=85&s=de2840c06fe8e06381b13f18500c71df" width="720" height="425" data-path="images/docs/main_architecture_diagram_dark.svg" />
</Frame>

### Key components of Propel's architecture

<CardGroup cols={2}>
  <Card title="Serverless ClickHouse®" icon="server">
    The core of Propel's architecture is a fully-managed, serverless ClickHouse®. This eliminates the need for manual server management and provides automatic scaling based on query demands.
  </Card>

  <Card title="SQL Interfaces" icon="database">
    Propel supports the standard ClickHouse HTTP interface, allowing you to connect any ClickHouse client or application. Additionally, it offers a PostgreSQL-compatible interface, enabling connection with any BI tool or client that supports PostgreSQL for seamless integration and querying.
  </Card>

  <Card title="Ingestion Layer" icon="database">
    Propel includes robust ingestion pipelines that efficiently ingest data from external sources into ClickHouse. This layer handles data synchronization, validation, and insertion to optimize data insertion.
  </Card>

  <Card title="Access Control Policies" icon="lock">
    This layer handles identity and access management for the Serverless ClickHouse. It ensures that applications have the proper access rights, supporting multi-tenant architectures by controlling data visibility and query permissions at a granular level.
  </Card>

  <Card title="API Layer" icon="code">
    An API layer sits in front of the Serverless ClickHouse, translating API calls into ClickHouse queries. This allows developers to interact with their data using familiar API paradigms without writing SQL directly.
  </Card>

  <Card title="Embeddable UI" icon="react">
    Propel's open-source toolkit for building frontend data applications on ClickHouse. It enables rapid development of interactive dashboards, reports, and data visualizations by transforming ClickHouse query results into reusable UI components.
  </Card>
</CardGroup>

## High-availability

Propel is designed with high availability as a core principle, ensuring that your data and services remain accessible and resilient to failures. Here's how we achieve this:

<CardGroup cols={2}>
  <Card title="Multiple Replicas" icon="copy">
    Your data is automatically replicated across multiple ClickHouse instances, providing redundancy and fault tolerance.
  </Card>

  <Card title="Cross-AZ Distribution" icon="server">
    Replicas are distributed across different availability zones (AZs) within a region, mitigating the risk of zone-specific outages.
  </Card>

  <Card title="Automatic Failover" icon="rotate">
    In case of a replica failure, Propel automatically redirects traffic to healthy replicas, ensuring continuous service availability.
  </Card>

  <Card title="Load Balancing" icon="scale-balanced">
    Queries are distributed across multiple replicas to optimize performance and resource utilization.
  </Card>
</CardGroup>

This multi-layered approach to high availability ensures that your ClickHouse deployment on Propel remains robust and accessible, even in the face of hardware failures or zone-specific issues.

## Storage architecture

Propel's ClickHouse  uses a tiered storage architecture to optimize performance and cost-efficiency. This system consists of three primary tiers:

1. **High-speed cache**: The fastest storage tier, ideal for extremely hot data and frequently accessed query results.
2. **SSD**: Fast storage with limited capacity, ideal for fresh and frequently queried data.
3. **Object Storage**: Affordable storage with unlimited capacity, suitable for historical and less frequently accessed data.

The system automatically manages data movement of data between these tiers based on usage patterns. By default, the most frequently accessed data is kept in the high-speed cache, while other data is stored on SSDs, after which it's moved to object storage.

```mermaid theme={"system"}
sequenceDiagram
    participant Application
    participant Cache
    participant SSD
    participant ObjectStorage as Object storage

    Application->>Cache: Inserts data
    Cache->>SSD:  Write-through cache
    SSD->>ObjectStorage: Moves data based on storage policies
    Application->>Cache: Queries data
    Cache->>SSD: Queries data
    SSD->>ObjectStorage: Queries data
    Cache-->>Application: Query response
    SSD-->>Application: Query response
    ObjectStorage-->>Application: Query response
```

This tiered approach allows for cost-effective high-performance storage, especially for large datasets with varying access patterns, while ensuring the fastest possible access to the most critical data.
